@lotargo/memory_plugin 1.6.2 → 1.6.4

package/CHANGELOG.md

@@ -3,9 +3,88 @@
 All notable changes to `@lotargo/memory_plugin` are documented in this file.
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
-and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
-
-## [1.6.2] - 2026-08-12
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [1.6.4] - 2026-08-13
+
+### Added
+
+- `memory_info` now reports whether the current Git identity is `Registry: linked`
+  or `Registry: unlinked`, enabling agents to register new repositories automatically.
+- RAG documents now have explicit global/project scope associations. The default
+  project scope follows the current linked Git identity, while `scope: "all"`
+  retrieves only global knowledge plus the current project's knowledge. A source
+  shared by several scopes is stored once and associated with each scope.
+- The native OpenCode plugin now exposes `batch_query_knowledge_base`, bringing it
+  to all 15 shared tools plus its two OpenCode-only helpers.
+
+### Changed
+
+- OpenCode auto-injected memory now includes complete fact bodies for both global and
+  current-project stores without the previous ten-fact truncation and instructs the
+  agent to register an unlinked Git identity. Header-only initialization was removed
+  because it loses essential context.
+- The bundled memory skill now defines full-body session recall, strict project
+  isolation, agent-resolved conflicts, automatic Git project registration, and
+  selective RAG curation for important web findings and current technical
+  documentation, including links from project facts to supporting sources.
+- `recall` hides superseded facts by default and exposes history through
+  `includeSuperseded: true`. Filtered output keeps physical storage indices stable,
+  so a displayed number always targets the same fact in `forget`.
+
+### Fixed
+
+- Re-ingesting an existing path or URL now preserves its document ID, scope
+  associations, and fact links while rebuilding chunks, vectors, FTS rows, and
+  structural graph edges for changed content.
+- Snapshot export/import and hybrid cloud synchronization now preserve vectors,
+  retrieval policies, policy provenance, document scopes, knowledge links, and
+  structural graph metadata. The hybrid sync worker also drains tasks queued during
+  an active flush instead of leaving them pending.
+- Relinking a Git project now moves its RAG scope associations and fact-to-document
+  links together with Notebook facts.
+- Environment-specific setup flags now update only their requested integration.
+  Codex setup also synchronizes the skill to both `~/.codex/skills` and the shared
+  `~/.agents/skills` location.
+- Shared documents no longer expose fact-link metadata belonging to another project.
+  Document deletion now defaults to unlinking only the current project (or global
+  outside Git); broader `global` / `all` removal must be requested explicitly.
+- Updating or forgetting a linked Notebook fact now keeps its knowledge-graph
+  projection and cloud payload consistent. Line-range graph edges are included in
+  per-document cloud sync, and superseding legacy facts without IDs assigns distinct
+  IDs to the old and new versions.
+- README tool counts now match the implementations: 15 MCP tools, 17 native
+  OpenCode tools, and 17 unique tool names across both surfaces. The OpenCode tool
+  list documents all shared and OpenCode-only helpers explicitly.
+
+## [1.6.3] - 2026-08-13
+
+### Added
+
+- `memory_plugin doctor --codex` validates the configured executable and Node.js
+  version, performs direct MCP `initialize` / `tools/list`, and calls both
+  `memory_info` and `recall(scope="all")`.
+- Codex regression coverage for Windows paths with spaces, legacy config migration,
+  duplicate removal, standalone MCP protocol smoke testing, two-repository project
+  isolation, global-only recall outside Git, and prompt idempotency.
+
+### Fixed
+
+- Codex setup no longer launches the memory MCP through `npx` or a Windows `.cmd`
+  shim. It writes absolute paths for the active Node executable and packaged
+  `mcp-server/boot.js` entry point after validating Node.js >= 22.5.0.
+- Existing plugin-owned `[mcp_servers.memory-agent]` sections, including the legacy
+  `opencode-memory-plugin` entry, are migrated in place without modifying unrelated
+  TOML sections or creating duplicates.
+- Repeated prompt setup now collapses duplicate plugin-owned blocks while preserving
+  user-authored AGENTS.md / CLAUDE.md content.
+- README tool counts match the v1.6.3 implementations: 15 MCP tools, 16 native
+  OpenCode tools, and 17 unique tool names across both surfaces. The OpenCode tool
+  list and the MCP-only status of `batch_query_knowledge_base` are documented explicitly.
+
+## [1.6.2] - 2026-08-12
 
 ### Added
 

package/README.md

@@ -77,9 +77,29 @@ memory_plugin setup --opencode
 # Claude Code
 memory_plugin setup --claude
 
-# Codex
-memory_plugin setup --codex
-```
+# Codex
+memory_plugin setup --codex
+```
+
+Codex is configured with a direct executable chain (`node` → `mcp-server/boot.js`),
+not `npx`. This avoids Windows stdio handshake failures caused by `.cmd` launchers.
+Running setup again safely migrates legacy `npx` entries and preserves unrelated
+sections in `~/.codex/config.toml`.
+
+`memory_plugin setup --codex` updates only the Codex MCP registration, Codex prompt,
+and the Codex-compatible skill locations (`~/.codex/skills` and the shared
+`~/.agents/skills`). It does not modify Claude Code, OpenCode, or Antigravity files.
+
+To verify registration, the Node runtime, MCP initialization, tool discovery, and
+real `memory_info` / `recall(scope="all")` calls:
+
+```bash
+memory_plugin doctor --codex
+```
+
+The doctor checks the server process itself. If it passes but a fresh Codex Desktop
+task still does not expose the tools, the remaining fault is in Desktop tool
+exposure rather than the memory MCP launcher.
 
 `setup` also accepts `--gemini` (alias for Antigravity) and `--local` (registers the MCP server in the project-local `.agents/` directory). Without a specific flag, all detected environments are configured.
 
@@ -106,10 +126,13 @@ memory_plugin setup --mode only-cloud
    - **Fact Schema**: Every fact is formatted as `**Title** — body` with inline metadata badges (`[id]`, `[ttl]`, `[keep]`, `[tags]`, `[supersedes]`, `[inject]`).
    - **Project Identity**: Project stores are bound to a **Git-based project identity** — the normalized remote URL (`git:github.com/owner/repo`) or `git:local:<repo basename>` — never to a directory path. Memories follow the repository across machines, OSes, and subdirectories. Legacy path/basename stores can be linked and merged via `link_project_memory`.
 
-2. **Layer 2: RAG Knowledge Base (Technical Documents & Codebases)**
-   - **Tools**: `ingest_document`, `query_knowledge_base`, `manage_knowledge_base`, `reindex_knowledge_base`
-   - **Capabilities**: Ingests raw text files, Markdown, HTML, Web URLs, office documents (PDF, DOCX, XLSX, CSV), and codebases.
-   - **Engine Components**: 3-tier hierarchy chunking (Big / Medium / Small), SQLite FTS5 BM25 search, ONNX dense vector embeddings (`multilingual-e5-small`), Reciprocal Rank Fusion (RRF / RSF), cross-encoder reranking (optional), and GraphRAG Lite code symbol extraction.
+2. **Layer 2: RAG Knowledge Base (Technical Documents & Codebases)**
+   - **Tools**: `ingest_document`, `query_knowledge_base`, `batch_query_knowledge_base`, `manage_knowledge_base`, `reindex_knowledge_base`
+   - **Capabilities**: Ingests raw text files, Markdown, HTML, Web URLs, office documents (PDF, DOCX, XLSX, CSV), and codebases.
+   - **Curation Model**: Stores only project-relevant sources likely to be reused—for example important web findings and current library/framework documentation that may be newer than model training. Ingest the useful document or excerpt, then link it to the project memory it supports; do not archive everything the agent encounters.
+   - **Scope Isolation**: New documents default to the current linked Git project. `scope: "all"` searches global sources plus the current project's sources; outside a Git repository it searches global sources only. Use `scope: "global"` only for genuinely cross-project material.
+   - **Stable Shared Sources**: Ingesting the same path or URL in another scope reuses one document and adds a scope association. Re-ingesting updated content preserves the document ID and its fact links; removing one scope does not delete a document still used by another scope.
+   - **Engine Components**: 3-tier hierarchy chunking (Big / Medium / Small), SQLite FTS5 BM25 search, ONNX dense vector embeddings (`multilingual-e5-small`), Reciprocal Rank Fusion (RRF / RSF), cross-encoder reranking (optional), and GraphRAG Lite code symbol extraction.
 
 3. **Layer 3: Agent-Driven Knowledge Graph**
    - **Tools**: `link_knowledge` (plus `docId`, `startLine`, `endLine` in `remember`)
@@ -147,22 +170,33 @@ Cloud authentication tokens are never written to `config.json`. They are stored
 
 ---
 
-## Available MCP Tools
-
-The MCP server registers **14 MCP tools** accessible across all connected AI environments, plus **2 OpenCode-plugin helper tools** available only inside OpenCode:
-
-### 1. Memory Notebook Tools (Layer 1)
+## Available Tools
+
+The package currently exposes **17 unique tool names** across its two integration surfaces:
+
+| Integration surface | Tool count | Composition |
+| :------------------ | ---------: | :---------- |
+| **MCP server** (Codex, Claude Code, Antigravity / Gemini CLI and other MCP clients) | **15** | 6 Notebook + 4 identity/graph + 5 RAG tools |
+| **Native OpenCode plugin** | **17** | 15 shared memory/identity/RAG tools + 2 OpenCode-only helpers |
+
+The two surfaces are intentionally counted separately. The OpenCode plugin exposes
+all 15 shared tools, including `batch_query_knowledge_base`, and adds the native
+`list-mcp-tools` and `mcp-reminder` helpers.
+
+### MCP Server Tools (15)
+
+#### 1. Memory Notebook Tools (Layer 1)
 
 | Tool | Scope / Target | Key Parameters | Description |
 | :--- | :------------- | :------------- | :---------- |
 | `remember` | `project` / `global` | `fact`, `title`, `scope`, `docId`, `startLine`, `endLine`, `relationType`, `ttl`, `keep`, `tags`, `supersedes` | Save a durable fact or preference. Supports optional title, document linking, TTL, keep protection, tags, and version superseding. |
-| `recall` | `all`, `project`, `global`, `list_projects` | `scope`, `project`, `query`, `tags`, `since`, `until`, `mode`, `offset`, `limit` | Display saved facts with metadata badges and linked docs. Supports cross-project lookup via `project: '<path>'` and header-only mode (`mode: "headers"`). |
+| `recall` | `all`, `project`, `global`, `list_projects` | `scope`, `project`, `query`, `tags`, `since`, `until`, `mode`, `offset`, `limit`, `includeSuperseded` | Display saved facts with metadata badges and linked docs. Superseded facts are hidden by default; opt into history with `includeSuperseded: true`. Filtered results retain stable storage indices for safe `forget` operations. |
 | `get_fact` | `all`, `project`, `global` | `id`, `scope` | Retrieve full text, raw line, and metadata of a single fact by its metadata ID (e.g. `"8f3a2c"`). |
 | `update_fact` | `project` / `global` | `id`, `newText`, `title`, `scope` | Rewrite a fact (and optionally its `**Title**`) while preserving its original creation date, metadata, and knowledge links. |
 | `forget` | `project` / `global` | `id` / `range` / `query`, `scope`, `force` | Remove a fact by index number, ID, range (e.g. `"3-30"`), or query. Requires `force: true` for protected (`[KEEP]`) facts. |
 | `memory_info` | - | - | Show storage paths, fact counts, RAG statistics, git identity bindings, and package version. |
 
-### 2. Project Identity Tools
+#### 2. Project Identity Tools
 
 | Tool | Key Parameters | Description |
 | :--- | :------------- | :---------- |
@@ -170,23 +204,32 @@ The MCP server registers **14 MCP tools** accessible across all connected AI env
 | `unlink_project_memory` | `directory`, `purge` | Remove a path alias binding for a directory. Optionally purge the project identity entry if `purge: true`. |
 | `relink_project_memory` | `directory`, `remote` | Switch a project's primary identity to a new remote URL and merge all stored facts into the target store with fact-text deduplication. |
 
-### 3. RAG Knowledge Base & Graph Tools (Layers 2 & 3)
+#### 3. RAG Knowledge Base & Graph Tools (Layers 2 & 3)
 
 | Tool | Key Parameters | Description |
 | :--- | :------------- | :---------- |
-| `ingest_document` | `content`, `type`, `title`, `path`, `generateEmbeddings` | Ingest local files, URLs, or raw text into the 3-tier index (Big/Medium/Small) with ONNX vector embeddings and GraphRAG symbol extraction. |
-| `query_knowledge_base` | `query`, `limit`, `instruction`, `generateEmbeddings` | Perform hybrid search (RSF/RRF BM25 + dense vector similarity) to retrieve candidate document sections with defined code symbols. |
-| `batch_query_knowledge_base` | `queries` (array), `limit`, `instruction`, `generateEmbeddings` | Execute multiple queries in a single batch call. More efficient than separate `query_knowledge_base` calls — all embeddings computed in one ONNX pass, queries run in parallel. Ideal for comparisons and multi-topic analysis. |
-| `manage_knowledge_base` | `action`, `docId`, `snapshotPath` | Inspect DB stats (`stats`), list documents (`list`), read full raw document (`read_document`), delete document (`delete`), or export/import snapshots (`export_snapshot` / `import_snapshot`). |
+| `ingest_document` | `content`, `type`, `title`, `path`, `scope`, `generateEmbeddings` | Ingest local files, URLs, or raw text into the 3-tier index. Defaults to the current linked Git project; use `scope: "global"` for intentionally shared knowledge. |
+| `query_knowledge_base` | `query`, `scope`, `limit`, `instruction`, `generateEmbeddings` | Perform hybrid search (RSF/RRF BM25 + dense vectors). `all` means global plus the current project, while `project` and `global` restrict retrieval explicitly. |
+| `batch_query_knowledge_base` | `queries` (array), `scope`, `limit`, `instruction`, `generateEmbeddings` | Execute multiple scoped queries in one call. All embeddings are computed in one ONNX pass, making this the preferred API for comparisons and multi-part research. |
+| `manage_knowledge_base` | `action`, `scope`, `docId`, `snapshotPath` | Inspect, list, read, or unlink documents within the selected scope, or export/import complete snapshots. Delete defaults to the current project (global outside Git); broader removal requires explicit `global` or `all`. |
 | `reindex_knowledge_base` | `model`, `dimension` | Re-embed all stored vectors with the active (or specified) embedding model and vector dimension. Use after switching the embedding model or vector dimension so previously indexed documents remain retrievable. Preserves documents, FTS index, graph edges, and fact links. |
 | `link_knowledge` | `action`, `factText`, `docId`, `scope`, `startLine`, `endLine`, `relationType` | Create, list, or retrieve semantic graph links connecting Notebook facts to Knowledge Base documents, sections, or line ranges. Actions: `link`, `list_links`, `get_doc_links`. |
 
-### 4. Agent & OpenCode Helpers (OpenCode plugin only, not exposed by the MCP server)
-
-| Tool | Key Parameters | Description |
-| :--- | :------------- | :---------- |
-| `list-mcp-tools` | - | Discover all connected MCP servers and their available tool definitions. |
-| `mcp-reminder` | `task` | Recommends the appropriate MCP tool or server for a specific developer task. |
+### Native OpenCode Plugin Tools (17)
+
+| Group | Count | Tools |
+| :---- | ----: | :---- |
+| **Memory Notebook** | 6 | `remember`, `recall`, `get_fact`, `forget`, `update_fact`, `memory_info` |
+| **Project Identity & Knowledge Graph** | 4 | `link_knowledge`, `link_project_memory`, `unlink_project_memory`, `relink_project_memory` |
+| **RAG Knowledge Base** | 5 | `ingest_document`, `query_knowledge_base`, `batch_query_knowledge_base`, `manage_knowledge_base`, `reindex_knowledge_base` |
+| **OpenCode-only helpers** | 2 | `list-mcp-tools`, `mcp-reminder` |
+
+The OpenCode-only helpers have the following purpose:
+
+| Tool | Key Parameters | Description |
+| :--- | :------------- | :---------- |
+| `list-mcp-tools` | - | Discover connected MCP servers and their intended use cases. |
+| `mcp-reminder` | `task` | Recommend the appropriate MCP tool or server for a developer task. |
 
 ---
 
@@ -216,7 +259,8 @@ Both binaries accept the same commands. `memory_plugin` with **no** command star
 | **`identity`** | `--dir <path>` | Inspects Git project identity key, primary remote, name, and toplevel path for a directory. |
 | **`migrate_titles`** | `--key <key>` | Auto-generates `**Title**` prefixes for legacy facts without titles. |
 | **`enable-prompt`** | - | Injects memory agent instructions into client agent files (`AGENTS.md`, `CLAUDE.md`). |
-| **`disable-prompt`** | - | Removes memory agent instructions from client agent files. |
+| **`disable-prompt`** | - | Removes memory agent instructions from client agent files. |
+| **`doctor`** | `--codex` | Validates Codex config, direct Node runtime, MCP initialize/tools/list, and live `memory_info` + `recall` calls. |
 | **`login`** | `--api-token`, `--from-env`, `--db-url <URL> --db-token`, `$TURSO_API_TOKEN`, `$TURSO_DB_TOKEN` | Authenticates with Turso Cloud via API token, direct DB token, or environment variables. Token values are read from the environment or a hidden stdin prompt. |
 | **`logout`** | `--api-key` | Signs out of Turso Cloud or removes stored API key while retaining DB session. |
 | **`auth-status`** | - | Displays authentication source, endpoint URL, username, organization, database, and sync mode. |
@@ -246,10 +290,12 @@ Use **Up / Down** arrows to navigate, **ENTER** to select, and **BACKSPACE** to
 
 ### Built-in Agent Skill (`using-memory`)
 
-The plugin bundles a pre-configured Agent Skill located at [`skills/using-memory/SKILL.md`](./skills/using-memory/SKILL.md). When installed in supported environments (such as Antigravity / Gemini CLI or OpenCode), coding agents automatically read this skill to:
-1. **Initialize Sessions**: Automatically invoke `recall(scope: "all")` at the start of every chat turn to load all saved preferences and project rules.
-2. **Proactively Save Context**: Automatically call `remember` whenever you share durable facts, tech stack choices, or coding guidelines.
-3. **Architect Knowledge Graphs**: Use `link_knowledge` or `remember(docId, startLine, endLine)` to connect memories directly to technical documentation.
+The plugin bundles a pre-configured Agent Skill located at [`skills/using-memory/SKILL.md`](./skills/using-memory/SKILL.md). When installed in supported environments (such as Antigravity / Gemini CLI or OpenCode), coding agents automatically read this skill to:
+1. **Initialize Sessions**: Invoke full-body `recall(scope: "all")` first, loading global memory plus only the current Git project's memory (or global-only outside Git).
+2. **Register Git Projects**: Inspect `memory_info` after recall and automatically call `link_project_memory` when the current Git identity reports `Registry: unlinked`.
+3. **Proactively Save Context**: Automatically call `remember` whenever you share durable facts, tech stack choices, or coding guidelines.
+4. **Curate and Use RAG Deliberately**: Preserve important web findings and current technical documentation only when they are likely to matter again. Store project-specific sources in the current project scope, reserve global scope for reusable cross-project material, query with concept-dense searches, and avoid low-value bulk ingestion.
+5. **Architect Knowledge Graphs**: Use `link_knowledge` or `remember(docId, startLine, endLine)` to connect concise project memories to their supporting technical sources.
 
 ### Global System Prompt Synchronization
 
@@ -295,7 +341,7 @@ During `ingest_document`, code symbols are extracted from code blocks using fast
 | Platform | Status | Configuration Mechanism |
 | :--- | :--- | :--- |
 | **Antigravity / Gemini CLI** | Supported | MCP Server (`~/.gemini/config/mcp_config.json` & `.agents/mcp_config.json`) |
-| **OpenCode** | Native | Native plugin + MCP Server (`~/.config/opencode/opencode.json`) |
+| **OpenCode** | Native | Native plugin with 16 tools (`~/.config/opencode/opencode.json`) |
 | **Claude Code** | Supported | MCP Server (`~/.claude.json`) |
 | **Codex** | Supported | MCP Server (`~/.codex/config.toml`) |
 | **Google Jules** | Supported | MCP Server via global install + setup (`memory_plugin setup`) |
@@ -321,7 +367,6 @@ The engine is configured through `<memory-dir>/config.json` (created with defaul
 | `executionDevice` | `cpu` | `cpu` or `webgpu` (experimental) |
 | `vectorScanLimit` | `50000` | Max micro-chunks scanned per vector query (`0` = unlimited) |
 | `policyExpansion` | `true` | Expand table_summary/code_signature policy chunks for better recall (slight MRR trade-off). Disable for pure micro_chunk precision. |
-| `injectLimit` | `10` | Max facts injected into the agent's system prompt |
 | `conflictStrategy` | `merge` | Hybrid-sync conflict resolution: `merge`, `cloud-wins`, or `local-wins` |
 | `tursoUrl` | `""` | Primary Turso endpoint URL (set by `login`) |
 | `failoverUrl` | `""` | Secondary cloud endpoint for the circuit breaker; empty = failover disabled |
@@ -339,7 +384,7 @@ The engine is configured through `<memory-dir>/config.json` (created with defaul
 To run the automated test suite and benchmarks locally, from the repository root:
 
 ```bash
-# Unit + integration + cloud suites (12 files) — fast and fully offline
+# Unit + integration + cloud suites (18 files) — fast and fully offline
 npm test
 
 # End-to-end smoke test with REAL ONNX embeddings — run before a release

package/mcp-server/admin/snapshot.js

@@ -72,8 +72,10 @@ export async function exportSnapshot({ customDb = null, customBlobDir = BLOBS_DI
   const documents = await db.prepare("SELECT * FROM documents").all();
   const sections = await db.prepare("SELECT * FROM sections").all();
   const mediumChunks = await db.prepare("SELECT * FROM medium_chunks").all();
-  const rawMicroChunks = await db.prepare("SELECT * FROM micro_chunks").all();
-  const graphEdges = await db.prepare("SELECT * FROM graph_edges").all();
+  const rawMicroChunks = await db.prepare("SELECT * FROM micro_chunks").all();
+  const graphEdges = await db.prepare("SELECT * FROM graph_edges").all();
+  const knowledgeLinks = await db.prepare("SELECT * FROM knowledge_links").all();
+  const documentScopes = await db.prepare("SELECT * FROM document_scopes").all();
 
   const microChunks = rawMicroChunks.map((mc) => {
     let vecBase64 = "";
@@ -99,14 +101,16 @@ export async function exportSnapshot({ customDb = null, customBlobDir = BLOBS_DI
   }
 
   const snapshot = {
-    version: 2,
+    version: 3,
     created_at: new Date().toISOString(),
     documents,
     sections,
     medium_chunks: mediumChunks,
     micro_chunks: microChunks,
-    graph_edges: graphEdges,
-    blobs,
+    graph_edges: graphEdges,
+    knowledge_links: knowledgeLinks,
+    document_scopes: documentScopes,
+    blobs,
   };
 
   const jsonStr = JSON.stringify(snapshot, null, 2);
@@ -187,14 +191,16 @@ export async function importSnapshot({ customDb = null, customBlobDir = BLOBS_DI
       token_count=excluded.token_count
   `);
 
-  const insertChunk = db.prepare(`
-    INSERT INTO micro_chunks (id, section_id, doc_id, content, vector, token_count, medium_id)
-    VALUES (?, ?, ?, ?, ?, ?, ?)
-    ON CONFLICT(id) DO UPDATE SET
-      content=excluded.content,
-      vector=excluded.vector,
-      token_count=excluded.token_count,
-      medium_id=excluded.medium_id
+  const insertChunk = db.prepare(`
+    INSERT INTO micro_chunks (id, section_id, doc_id, content, vector, token_count, medium_id, retrieval_policy, policy_source_id)
+    VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)
+    ON CONFLICT(id) DO UPDATE SET
+      content=excluded.content,
+      vector=excluded.vector,
+      token_count=excluded.token_count,
+      medium_id=excluded.medium_id,
+      retrieval_policy=excluded.retrieval_policy,
+      policy_source_id=excluded.policy_source_id
   `);
 
   const insertFts = db.prepare(`
@@ -204,11 +210,32 @@ export async function importSnapshot({ customDb = null, customBlobDir = BLOBS_DI
 
   const deleteFts = db.prepare("DELETE FROM micro_chunks_fts WHERE id = ?");
 
-  const insertEdge = db.prepare(`
-    INSERT INTO graph_edges (source_id, target_id, relation_type)
-    VALUES (?, ?, ?)
-    ON CONFLICT(source_id, target_id, relation_type) DO NOTHING
-  `);
+  const insertEdge = db.prepare(`
+    INSERT INTO graph_edges (source_id, target_id, relation_type, metadata_json, created_at)
+    VALUES (?, ?, ?, ?, ?)
+    ON CONFLICT(source_id, target_id, relation_type) DO UPDATE SET
+      metadata_json=excluded.metadata_json,
+      created_at=excluded.created_at
+  `);
+  const insertScope = db.prepare(`
+    INSERT OR IGNORE INTO document_scopes (doc_id, scope_key, created_at)
+    VALUES (?, ?, ?)
+  `);
+  const insertLink = db.prepare(`
+    INSERT INTO knowledge_links
+      (id, fact_key, fact_text, doc_id, section_id, start_line, end_line, relation_type, metadata_json, created_at)
+    VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+    ON CONFLICT(id) DO UPDATE SET
+      fact_key=excluded.fact_key,
+      fact_text=excluded.fact_text,
+      doc_id=excluded.doc_id,
+      section_id=excluded.section_id,
+      start_line=excluded.start_line,
+      end_line=excluded.end_line,
+      relation_type=excluded.relation_type,
+      metadata_json=excluded.metadata_json,
+      created_at=excluded.created_at
+  `);
 
   await db.exec("BEGIN IMMEDIATE;");
   try {
@@ -228,11 +255,23 @@ export async function importSnapshot({ customDb = null, customBlobDir = BLOBS_DI
       }
     }
 
-    if (Array.isArray(snapshot.sections)) {
+    if (Array.isArray(snapshot.sections)) {
       for (const s of snapshot.sections) {
         await insertSection.run(s.id, s.doc_id, s.heading, s.breadcrumbs, s.content, s.token_count);
       }
-    }
+    }
+
+    if (Array.isArray(snapshot.document_scopes) && snapshot.document_scopes.length > 0) {
+      for (const scope of snapshot.document_scopes) {
+        await insertScope.run(scope.doc_id, scope.scope_key || "global", scope.created_at || Date.now());
+      }
+    } else if (Array.isArray(snapshot.documents)) {
+      // v1/v2 snapshots predate project-scoped RAG and retain their historical
+      // globally-visible behavior after import.
+      for (const d of snapshot.documents) {
+        await insertScope.run(d.id, "global", d.created_at || Date.now());
+      }
+    }
 
     if (Array.isArray(snapshot.medium_chunks)) {
       for (const m of snapshot.medium_chunks) {
@@ -246,7 +285,17 @@ export async function importSnapshot({ customDb = null, customBlobDir = BLOBS_DI
         if (mc.vector) {
           vecBuf = Buffer.from(mc.vector, "base64");
         }
-        await insertChunk.run(mc.id, mc.section_id, mc.doc_id, mc.content, vecBuf, mc.token_count, mc.medium_id || null);
+        await insertChunk.run(
+          mc.id,
+          mc.section_id,
+          mc.doc_id,
+          mc.content,
+          vecBuf,
+          mc.token_count,
+          mc.medium_id || null,
+          mc.retrieval_policy || "micro_chunk",
+          mc.policy_source_id || null
+        );
 
         try {
           await deleteFts.run(mc.id);
@@ -255,10 +304,26 @@ export async function importSnapshot({ customDb = null, customBlobDir = BLOBS_DI
       }
     }
 
-    if (Array.isArray(snapshot.graph_edges)) {
-      for (const e of snapshot.graph_edges) {
-        await insertEdge.run(e.source_id, e.target_id, e.relation_type);
-      }
+    if (Array.isArray(snapshot.graph_edges)) {
+      for (const e of snapshot.graph_edges) {
+        await insertEdge.run(e.source_id, e.target_id, e.relation_type, e.metadata_json || null, e.created_at || null);
+      }
+    }
+    if (Array.isArray(snapshot.knowledge_links)) {
+      for (const link of snapshot.knowledge_links) {
+        await insertLink.run(
+          link.id,
+          link.fact_key,
+          link.fact_text,
+          link.doc_id,
+          link.section_id || null,
+          link.start_line || null,
+          link.end_line || null,
+          link.relation_type || "LINKS_TO",
+          link.metadata_json || null,
+          link.created_at || Date.now()
+        );
+      }
     }
     await db.exec("COMMIT;");
   } catch (err) {
@@ -271,7 +336,9 @@ export async function importSnapshot({ customDb = null, customBlobDir = BLOBS_DI
     sections: snapshot.sections ? snapshot.sections.length : 0,
     medium_chunks: snapshot.medium_chunks ? snapshot.medium_chunks.length : 0,
     micro_chunks: snapshot.micro_chunks ? snapshot.micro_chunks.length : 0,
-    graph_edges: snapshot.graph_edges ? snapshot.graph_edges.length : 0,
+    graph_edges: snapshot.graph_edges ? snapshot.graph_edges.length : 0,
+    knowledge_links: snapshot.knowledge_links ? snapshot.knowledge_links.length : 0,
+    document_scopes: snapshot.document_scopes ? snapshot.document_scopes.length : 0,
     blobs: blobCount,
   };
 }

package/mcp-server/cli/direct_commands.js

@@ -11,7 +11,16 @@ import {
 } from "../memory.js";
 import { factBody } from "../fact_format.js";
 
-export async function handleDirectCommands(cliArgs) {
+export async function handleDirectCommands(cliArgs) {
+  if (cliArgs[0] === "doctor" && cliArgs.includes("--codex")) {
+    const { runCodexDoctor } = await import("../codex_diagnostics.js");
+    console.log("\nCodex memory-agent diagnostics\n");
+    const result = await runCodexDoctor();
+    console.log("");
+    if (!result.ok) process.exitCode = 1;
+    return true;
+  }
+
   if (cliArgs[0] === "link") {
     const dirIdx = cliArgs.indexOf("--dir");
     const dir = dirIdx >= 0 && cliArgs[dirIdx + 1] ? cliArgs[dirIdx + 1] : process.cwd();
@@ -127,9 +136,11 @@ export async function handleDirectCommands(cliArgs) {
       }
 
       await writeMemory(targetKey, targetFacts);
-      await db.prepare("UPDATE project_aliases SET identity_key = ? WHERE identity_key = ?;").run(targetKey, sourceKey);
-      await upsertIdentity(db, { key: targetKey, name: sourceIdentity.name, primaryRemote: normalizeRemoteUrl(remote) });
-      await removeIdentity(db, sourceKey);
+      await upsertIdentity(db, { key: targetKey, name: sourceIdentity.name, primaryRemote: normalizeRemoteUrl(remote) });
+      await db.prepare("UPDATE project_aliases SET identity_key = ? WHERE identity_key = ?;").run(targetKey, sourceKey);
+      const { moveKnowledgeScope } = await import("../graph/knowledge_linker.js");
+      await moveKnowledgeScope(db, sourceKey, targetKey);
+      await removeIdentity(db, sourceKey);
 
       try {
         const sourceFp = storeFilePath(sourceKey);

package/mcp-server/cli/handlers/storage_actions.js

@@ -405,8 +405,10 @@ export async function handleStorageAction(value, config, stats) {
             }
 
             await writeMemory(targetKey, targetFacts);
-            await db.prepare("UPDATE project_aliases SET identity_key = ? WHERE identity_key = ?;").run(targetKey, sourceKey);
             await upsertIdentity(db, { key: targetKey, name: identity.name, primaryRemote: normalizeRemoteUrl(targetRemote) });
+            await db.prepare("UPDATE project_aliases SET identity_key = ? WHERE identity_key = ?;").run(targetKey, sourceKey);
+            const { moveKnowledgeScope } = await import("../../graph/knowledge_linker.js");
+            await moveKnowledgeScope(db, sourceKey, targetKey);
             await removeIdentity(db, sourceKey);
 
             try {

package/mcp-server/cli.js

@@ -23,7 +23,8 @@ Usage:
   memory-cli auth-status
   memory-cli link|unlink|relink|identity [--dir <path>] [--remote <url>]
   memory-cli migrate_titles [--key <key>]
-  memory-cli enable-prompt | disable-prompt
+  memory-cli enable-prompt | disable-prompt
+  memory-cli doctor --codex
 
 Options:
   -h, --help                         Show this help text`);