From cea45a552ace0e600dcb264eab15c156c23f33c9 Mon Sep 17 00:00:00 2001
From: Shinwoo PARK <shinwoo.park@psw.kr>
Date: Mon, 11 May 2026 14:45:35 +0900
Subject: [PATCH] docs: document space isolation usage

---
 README.md | 32 ++++++++++++++++++++++++++++++--
 1 file changed, 30 insertions(+), 2 deletions(-)

diff --git a/README.md b/README.md
index a9188ef..d98f27b 100644
--- a/README.md
+++ b/README.md
@@ -15,9 +15,9 @@ A single fact like `I have worked with TypeScript since 2025.` can connect the t
 ## Current capabilities
 
 - SQLite, PostgreSQL, MySQL, and MariaDB connection adapters
-- Automatic schema initialization for `topics`, `facts`, `fact_topics`, `topic_relations`, `topic_aliases`, and `fact_embeddings`
+- Automatic schema initialization for `spaces`, `topics`, `facts`, `fact_topics`, `topic_relations`, `topic_aliases`, and `fact_embeddings`
 - High-level APIs for adding topics and facts
-- Topic hierarchy APIs for parent/child traversal and lineage lookup
+- Hard space isolation so independent memory graphs can coexist without cross-linking
 - Topic alias and canonical resolution APIs so facts and queries can resolve alternate names
 - Semantic fact indexing and search APIs built around provider-agnostic embeddings
 - Dedup-aware ingestion hooks that can reuse an existing fact when a semantic near-duplicate is detected
@@ -101,6 +101,34 @@ console.log(matches.map((entry) => [entry.statement, entry.score]));
 await db.close();
 ```
 
+## Memory spaces
+
+IdentityDB now supports hard isolation via spaces. If you write facts into `spaceName: 'A'` and `spaceName: 'B'`, they behave like separate dimensions:
+
+- the same topic name can exist in both spaces
+- aliases resolve only inside the requested space
+- hierarchy, connected-topic traversal, semantic search, and duplicate detection stay inside the same space
+
+```ts
+await db.upsertSpace({ name: 'A' });
+await db.upsertSpace({ name: 'B' });
+
+await db.addFact({
+  spaceName: 'A',
+  statement: 'TypeScript belongs to A.',
+  topics: [{ name: 'TypeScript', category: 'entity', granularity: 'concrete' }],
+});
+
+await db.addFact({
+  spaceName: 'B',
+  statement: 'TypeScript belongs to B.',
+  topics: [{ name: 'TypeScript', category: 'entity', granularity: 'concrete' }],
+});
+
+const alphaFacts = await db.getTopicFacts('TypeScript', { spaceName: 'A' });
+const betaFacts = await db.getTopicFacts('TypeScript', { spaceName: 'B' });
+```
+
 ## Semantic ingestion and duplicate detection
 
 If you provide an embedding provider during ingestion, IdentityDB can index the new fact automatically and reuse an existing fact when a semantic near-duplicate is already present.