docs: add IdentityDB usage examples

README.md

@@ -12,14 +12,68 @@ IdentityDB stores memory as a graph made of:
 
 A single fact like `I have worked with TypeScript since 2025.` can connect the topics `I`, `TypeScript`, and `2025` at the same time.
 
-## Foundation scope
+## Current foundation capabilities
 
-The first implementation pass focuses on:
+- SQLite, PostgreSQL, MySQL, and MariaDB connection adapters
+- Automatic schema initialization for `topics`, `facts`, and `fact_topics`
+- High-level APIs for adding topics and facts
+- Query APIs for listing topics, loading topic-scoped facts, and finding connected facts/topics
+- Pluggable fact extraction so callers can use a small LLM or a deterministic extractor
 
-- SQLite, PostgreSQL, MySQL, and MariaDB adapters
-- Automatic schema initialization
-- High-level APIs for topics and facts
-- Pluggable ingestion so callers can use a small LLM to extract topics from free-form statements
+## Install
+
+```bash
+bun install
+```
+
+## Quick start
+
+```ts
+import { IdentityDB, NaiveExtractor } from 'identitydb';
+
+const db = await IdentityDB.connect({
+  client: 'sqlite',
+  filename: ':memory:',
+});
+
+await db.initialize();
+
+await db.ingestStatement('I have worked with TypeScript since 2025.', {
+  extractor: new NaiveExtractor(),
+});
+
+await db.addFact({
+  statement: 'TypeScript is a programming language.',
+  topics: [
+    {
+      name: 'TypeScript',
+      category: 'entity',
+      granularity: 'concrete',
+    },
+    {
+      name: 'programming language',
+      category: 'concept',
+      granularity: 'abstract',
+    },
+  ],
+});
+
+const topic = await db.getTopicByName('TypeScript', { includeFacts: true });
+const connected = await db.findConnectedTopics('TypeScript');
+
+console.log(topic?.facts.map((fact) => fact.statement));
+console.log(connected.map((entry) => [entry.name, entry.sharedFactCount]));
+
+await db.close();
+```
+
+## Development
+
+```bash
+bun run test
+bun run check
+bun run build
+```
 
 ## Current status