@lotargo/memory_plugin 1.3.0 → 1.3.2

package/README.md

@@ -29,7 +29,7 @@ Automatically remembers durable user facts, ingests complex document repositorie
 
 Standard AI coding assistants lose context as soon as a chat session closes or a conversation is reset. You end up repeatedly re-explaining your preferences, architectural decisions, coding style, or project conventions.
 
-`@lotargo/memory_plugin` gives your AI tools durable, 100% local long-term memory and document retrieval capabilities that persist across restarts and work seamlessly across all supported coding environments.
+`@lotargo/memory_plugin` gives your AI tools durable, **persistent**, 100% local long-term memory and document retrieval capabilities that persist across restarts and work seamlessly across all supported coding environments. Any LLM-based coding agent (OpenCode, Claude Code, Codex, Antigravity) can query its own memory and hybrid knowledge base via the **Model Context Protocol (MCP)**.
 
 > **Project Scope & Runtime Notes**:
 > `@lotargo/memory_plugin` is designed primarily as a practical plugin to expand capabilities and streamline daily interaction with AI coding tools. Benchmark scores in this repository represent internal synthetic evaluation runs and are not intended as generalized RAG benchmarks.
@@ -58,7 +58,7 @@ Standard AI coding assistants lose context as soon as a chat session closes or a
 Run the setup command to configure all detected AI environments automatically:
 
 ```bash
-# Recommended: Global installation & setup (works across local CLI, Jules, Docker, and CI)
+# Recommended: Global installation & setup (works across local CLI, Docker, and CI)
 npm install -g @lotargo/memory_plugin && memory_plugin setup
 
 # Or via npx
@@ -81,20 +81,23 @@ npm install -g @lotargo/memory_plugin && memory_plugin setup --claude
 npm install -g @lotargo/memory_plugin && memory_plugin setup --codex
 ```
 
+`setup` also accepts `--gemini` (alias for Antigravity) and `--local` (also registers the MCP server in the project-local `.agents/` directory for Antigravity). Without a specific flag, all detected environments are configured.
+
 ---
 
 ## Dual-Layer Architecture
 
 1. **Layer 1: Notebook Store (Durable Facts)**
-   - **Tools**: `remember`, `recall`, `forget`
+   - **Tools**: `remember`, `recall`, `forget`, `update_fact`, `memory_info`
    - **Scope**: User preferences, identity, project conventions, system rules.
    - **Storage**: Human-readable Markdown format (`global` and per-project stores).
    - **Performance**: Guaranteed 100% precision instant lookup without vector degradation or threshold filtering.
+   - **Project Scoping**: Project stores are bound to their canonical directory path (e.g. `f__projects_plugins_memory.md`), so identical project names in different folders never collide. Legacy basename stores are migrated automatically with a collision guard.
 
 2. **Layer 2: RAG Knowledge Base (Technical Documents & Codebases)**
-   - **Tools**: `ingest_document`, `query_knowledge_base`, `manage_knowledge_base`
-   - **Capabilities**: Ingests raw text files, Markdown, HTML, and full code repositories.
-   - **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), and GraphRAG Lite code symbol extraction.
+   - **Tools**: `ingest_document`, `query_knowledge_base`, `manage_knowledge_base`, `link_knowledge`
+   - **Capabilities**: Ingests raw text files, Markdown, HTML, Web URLs, and full code repositories.
+   - **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.
 
 ---
 
@@ -103,11 +106,14 @@ npm install -g @lotargo/memory_plugin && memory_plugin setup --codex
 - **Zero Heavy Infrastructure**: No Docker, no Python server, no C++ compilation (`node-gyp`). Uses Node.js native SQLite database.
 - **Bilingual & Multilingual Support**: State-of-the-art semantic precision across Russian, English, and technical code symbols.
 - **3-Tier Hierarchy Chunking**: Document (Big) -> Section (Medium) -> Micro-Chunk (Small).
-- **Hybrid RRF/RSF Fusion**: Combines SQLite FTS5 keyword precision with ONNX dense vector similarity.
+- **Hybrid RRF/RSF Fusion**: Combines SQLite FTS5 keyword precision with ONNX dense vector similarity; lexical-only fallback when embeddings are disabled.
+- **Semantic Search**: Cosine-similarity vector retrieval with multilingual ONNX embeddings (E5 / BGE model families).
+- **Path-Based Project Memory**: Per-project stores keyed by canonical directory path, with automatic migration of legacy stores.
 - **GraphRAG Lite**: Automatically links documents and extracted code symbols (classes, functions, types).
+- **Memory-to-Knowledge Linking**: Associate notebook facts with specific documents or line ranges in the RAG base.
 - **Content-Addressable Storage (CAS)**: Local S3-style compressed blob store for raw original documents.
 - **Dual-Source Model Failover**: Automatic HuggingFace CDN model downloading with GitHub Repository Mirror fallback.
-- **Interactive CLI Management**: Terminal GUI interface for runtime engine tuning, database maintenance, and diagnostics.
+- **Interactive TUI**: Terminal GUI (CLI menu) for runtime engine tuning, snapshot export/import, model cache management, and diagnostics.
 
 ---
 
@@ -119,17 +125,17 @@ npm install -g @lotargo/memory_plugin && memory_plugin setup --codex
 | **OpenCode**                 | Native       | Native plugin + MCP Server (`~/.config/opencode/opencode.json`)             |
 | **Claude Code**              | Supported    | MCP Server (`~/.claude.json`)                                               |
 | **Codex**                    | Supported    | MCP Server (`~/.codex/config.toml`)                                         |
-| **Google Jules**             | Experimental | MCP Server via global install (`npm install -g @lotargo/memory_plugin`)     |
+| **Google Jules**             | Experimental | MCP Server via global install + setup (`npm install -g @lotargo/memory_plugin && memory_plugin setup`) |
 
 ### Google Jules Integration (Experimental)
 
-The plugin has been verified inside the **Google Jules** cloud workspace environment.
+The plugin has been verified inside the **Google Jules** cloud workspace environment. This feature is **experimental**.
 
-- **Setup Method**: Global pre-installation:
+- **Setup Method**: Global pre-installation with auto-setup:
   ```bash
-  npm install -g @lotargo/memory_plugin
+  npm install -g @lotargo/memory_plugin && memory_plugin setup
   ```
-- **Verification**: Google Jules automatically discovers the registered MCP server upon workspace initialization and seamlessly interacts with memory & RAG tools (`remember`, `recall`, `ingest_document`, `query_knowledge_base`).
+- **Verification**: All current tools and capabilities have been verified inside the Google Jules cloud workspace. Google Jules automatically discovers the registered MCP server upon workspace initialization and seamlessly interacts with the full set of memory & RAG tools — `remember`, `recall`, `forget`, `update_fact`, `memory_info`, `link_knowledge`, `ingest_document`, `query_knowledge_base`, and `manage_knowledge_base` — including project-scoped memory, knowledge linking, and snapshot export/import.
 - **Current Limitation**: All memory stores and vector indexes operate locally within the workspace environment. Cross-session cloud synchronization across different Jules runs is planned for upcoming releases.
 
 ---
@@ -138,11 +144,13 @@ The plugin has been verified inside the **Google Jules** cloud workspace environ
 
 ### 1. Memory Tools (Key-Value Notebook)
 
-| Tool       | Scope / Target                | Description                                  |
-| :--------- | :---------------------------- | :------------------------------------------- |
-| `remember` | `global` or `project`         | Save an important durable fact or preference |
-| `recall`   | `project`, `global`, or `all` | Display saved facts                          |
-| `forget`   | Index ID or query             | Remove a saved fact                          |
+| Tool            | Scope / Target                          | Description                                                       |
+| :-------------- | :-------------------------------------- | :---------------------------------------------------------------- |
+| `remember`      | `global` or `project`                   | Save an important durable fact or preference                       |
+| `recall`        | `project`, `global`, `all`, `list_projects` | Display saved facts; read another project's store via `project: '<path>'` |
+| `forget`        | Index ID, range, or query               | Remove a saved fact (e.g. `"3-30"` ranges; `force` for protected) |
+| `update_fact`   | Index ID, metadata id, or text          | Rewrite a fact while preserving its original date and links       |
+| `memory_info`   | -                                       | Show storage paths, fact counts, RAG stats, and package version   |
 
 ### 2. Hybrid RAG Knowledge Base Tools
 
@@ -150,13 +158,50 @@ The plugin has been verified inside the **Google Jules** cloud workspace environ
 | :---------------------- | :------------------------------ | :--------------------------------------------------------------------------- |
 | `ingest_document`       | Local files, Web URLs, Raw text | Ingest into 3-tier index with ONNX vector embeddings & symbol extraction     |
 | `query_knowledge_base`  | Text / Code query               | Perform hybrid RSF/RRF search (BM25 + Vector) to retrieve candidate sections |
-| `manage_knowledge_base` | Actions / Documents             | List documents, delete entries, view DB stats, or export/import snapshots    |
+| `manage_knowledge_base` | Actions / Documents             | Stats, list, read, delete documents, or export/import snapshots              |
+| `link_knowledge`        | Facts + Document ranges         | Explicitly link a memory fact to a KB document or line range                 |
+
+### 3. Native OpenCode Plugin
+
+When installed as an OpenCode plugin, all MCP tools above plus `list-mcp-tools` and `mcp-reminder` are exposed. A chat hook (`experimental.chat.messages.transform`) automatically injects your saved memory into every conversation as a `<MEMORY>` block, so your agent starts each session already knowing your preferences and project context.
+
+---
+
+## GraphRAG Lite
+
+The RAG engine includes a lightweight graph layer built on the same SQLite database. It combines code symbol extraction, hierarchy edges, and explicit memory-to-document links without requiring a separate graph store or an LLM at ingest time.
+
+**Code Symbol Extraction** — during `ingest_document`, code symbols are extracted from the chunk content using fast regex heuristics (no language model needed):
+
+- JavaScript / TypeScript: `function`, `class`, `interface`, `type`, `enum`, `const`, `let`, `var`
+- Python: `def`, `class`
+- Symbols shorter than 3 characters and reserved keywords (`const`, `let`, `var`, `function`, `class`, `import`, `export`, `from`, `return`, `if`, `for`, `while`, `def`, `self`) are filtered out.
+
+**Graph Edges** — three built-in relation types are created automatically, and custom relation types are supported for explicit linking:
+
+| Relation Type       | Direction / Example                                          |
+| :------------------ | :----------------------------------------------------------- |
+| `CONTAINS`          | Document -> Section -> Micro-Chunk (3-tier hierarchy)        |
+| `DEFINES_SYMBOL`    | Section -> `symbol:<name>` (extracted code symbol)           |
+| `LINKS_TO` (default) | Memory fact -> Document or line range (via `link_knowledge`) |
+
+**Memory-to-Knowledge Linking** — the `link_knowledge` tool connects a notebook fact to a specific document or line range (`RULES_FOR`, `IMPLEMENTS`, `EXPLAINS`, `REFERENCES`, ...):
+
+- `link` — create the link and its graph edge
+- `list_links` — list all links, optionally filtered by fact key
+- `get_doc_links` — list all links pointing to a given document
+
+Linked facts are surfaced automatically in `recall` results as `🔗 [Linked Docs: ...]`, and `remember` accepts an optional `docId` to link immediately.
+
+**Retrieval Integration** — `query_knowledge_base` augments each retrieved section with `defined_symbols`: the code symbols defined in that same section (a single-hop lookup along `DEFINES_SYMBOL` edges). Symbol extraction also improves BM25 scoring, since symbol names become searchable tokens.
+
+**Lifecycle** — edges are rebuilt transactionally on re-ingest of the same document, and `manage_knowledge_base` delete operations clean up all graph edges and knowledge links owned by the document (including `GLOB`-matched section/micro-chunk suffixes).
 
 ---
 
-## Interactive CLI & Engine Tuning
+## Interactive TUI (CLI Menu)
 
-Launch the interactive CLI terminal interface to manage engine settings, inspect databases, and tune retrieval parameters:
+Launch the interactive terminal UI to manage engine settings, inspect databases, tune retrieval parameters, and run diagnostics:
 
 ```bash
 # From local repository folder:
@@ -170,23 +215,50 @@ memory_plugin cli
 memory-cli
 ```
 
-### CLI Menu Overview
+### TUI Menu Overview
 
 The interactive menu exposes runtime parameters that `hybridQuery` honors, allowing search behavior modifications without restarting the MCP server. Use **Up / Down** arrows to navigate, **ENTER** to select, and **BACKSPACE** to go back.
 
-| Block               | Menu Item                    | Functionality                                                                  |
-| :------------------ | :--------------------------- | :----------------------------------------------------------------------------- |
-| **Engine Settings** | Fusion Algorithm             | Switch between `rsf`, `rrf`, `semantic_only`, `lexical_only`.                  |
-|                     | RSF Alpha Balance            | Weight of semantic over lexical in `rsf` fusion (`α ∈ [0,1]`). Default: `0.5`. |
-|                     | Embedding Model              | Select ONNX model (e.g. `Xenova/multilingual-e5-small`).                       |
-|                     | Reranker Model               | Enable Cross-Encoder reranking or disable for zero-latency fusion.             |
-| **Notebook**        | Layer 1 Facts                | Browse and manage `global` and per-project `.md` fact stores.                  |
-| **RAG Docs**        | Layer 2 RAG Base             | List ingested documents, inspect chunk counts, and purge entries.              |
-| **Diagnostics**     | Run Search Quality Benchmark | Execute in-process search evaluation across benchmark query set.               |
-|                     | Verification Query           | Run a test `hybridQuery` against the active index.                             |
-|                     | Clear Cache & Reset          | Clear cached benchmark corpus or restore factory default config.               |
+| Block                                   | Menu Item                       | Functionality                                                                  |
+| :-------------------------------------- | :------------------------------ | :----------------------------------------------------------------------------- |
+| **Engine & Hybrid Search Settings**     | Fusion Algorithm                | Switch between `rsf`, `rrf`, `semantic_only`, `lexical_only`.                  |
+|                                         | RSF Alpha Balance               | Weight of semantic over lexical in `rsf` fusion (`α ∈ [0,1]`). Default: `0.5`.  |
+|                                         | Embedding Model                 | Select ONNX model (e.g. `Xenova/multilingual-e5-small`, custom HF models).     |
+|                                         | Reranker Model                  | Enable Cross-Encoder reranking or disable for zero-latency fusion.             |
+|                                         | Vector Batch Size               | Ingestion vector batch size `[1 - 256]` (default `12`).                        |
+|                                         | GPU Attention Budget            | GPU micro-batch attention budget `[1M - 16M]` (default `2.0M`, ~1.5 GB VRAM).  |
+|                                         | CPU WASM Threads                | ONNX WASM threads: `0` auto-detect or `1-16`.                                  |
+|                                         | Execution Hardware              | `cpu` or `webgpu` (experimental).                                              |
+| **Knowledge Base & Storage Management** | Notebook (Layer 1 Facts)        | Browse and manage `global` and per-project `.md` fact stores.                  |
+|                                         | RAG Docs (Layer 2 Base)         | List ingested documents, inspect chunk counts, and purge entries.              |
+|                                         | Snapshot Export / Import        | Export or restore the full RAG base + blob store as a JSON snapshot.           |
+|                                         | Manage & Purge ML Model Cache   | Inspect or purge downloaded ONNX model weights.                                |
+|                                         | Hard Reset                      | Purge RAG base, blob storage, and graph edges.                                 |
+| **Global Prompt & Integration**         | Enable / Disable Global Prompt  | Inject memory instructions into `~/.gemini/config/AGENTS.md`, `~/.codex/AGENTS.md`, `~/.claude/CLAUDE.md`. |
+| **Diagnostics & System Actions**        | Search Quality Benchmark        | Execute in-process search evaluation across the benchmark query set.           |
+|                                         | Verification Query              | Run a test `hybridQuery` against the active index.                             |
+|                                         | Clear Benchmark Corpus Cache    | Clear cached benchmark corpus.                                                 |
+|                                         | Reset Config to Factory Defaults| Restore default engine configuration.                                          |
+
+Settings persist to `<memory-dir>/config.json` and are immediately loaded by the MCP server.
+
+---
+
+## Configuration
+
+The engine is configured through `<memory-dir>/config.json` (created with defaults on first run):
 
-Settings persist to `~/.config/opencode/memory/config.json` and are immediately loaded by the MCP server.
+| Key                   | Default                            | Description                                                     |
+| :-------------------- | :--------------------------------- | :-------------------------------------------------------------- |
+| `fusionAlgorithm`     | `rsf`                              | `rsf`, `rrf`, `semantic_only`, or `lexical_only`                |
+| `alpha`               | `0.5`                              | Vector vs BM25 weight in RSF `[0.0 - 1.0]`                      |
+| `embeddingModel`      | `Xenova/multilingual-e5-small`     | ONNX dense embedding model (E5 / BGE families supported)        |
+| `rerankerModel`       | `none`                             | Cross-encoder reranker, or `Xenova/bge-reranker-base`           |
+| `rerankerEnabled`     | `false`                            | Enable cross-encoder re-ranking                                 |
+| `batchSize`           | `12`                               | Ingestion vector batch size `[1 - 256]`                         |
+| `gpuAttentionBudget`  | `2000000`                          | GPU micro-batch attention budget `[1M - 16M]`                   |
+| `onnxThreads`         | `0`                                | ONNX WASM threads: `0` auto-detect, or `1-16`                   |
+| `executionDevice`     | `cpu`                              | `cpu` or `webgpu` (experimental)                                |
 
 ---
 
@@ -241,7 +313,7 @@ Detailed technical documentation and architectural specifications are available
 
 ## Storage & Privacy
 
-- **100% Local Storage**: All SQLite indexes, ONNX models, CAS blobs, and Markdown notebooks are stored locally under `~/.config/opencode/memory/`.
+- **100% Local Storage**: All SQLite indexes, ONNX models, CAS blobs, and Markdown notebooks are stored locally in the memory directory. The location resolves to, in order of priority: `$MEMORY_DIR`, `$OPENCODE_CONFIG_DIR/memory`, the legacy `~/.config/opencode/memory` (on Windows: `%LOCALAPPDATA%\opencode\memory`), or `$XDG_CONFIG_HOME/opencode/memory`.
 - **Dual-Source Failover Model Fetching**: Primary model weights are fetched from HuggingFace CDN with automatic failover to GitHub Repository Mirror.
 - **Zero External Telemetry**: No third-party network calls are required after initial model setup.
 

package/mcp-server/config/config_manager.js

@@ -1,6 +1,6 @@
 import fs from "fs";
 import path from "path";
-import { MEMORY_DIR, ensureDir } from "../memory.js";
+import { MEMORY_DIR, ensureDirSync } from "../memory.js";
 
 const CONFIG_FILE = path.join(MEMORY_DIR, "config.json");
 
@@ -23,7 +23,7 @@ export function getConfig() {
     return cachedConfig;
   }
 
-  ensureDir();
+  ensureDirSync();
 
   if (fs.existsSync(CONFIG_FILE)) {
     try {
@@ -42,7 +42,7 @@ export function getConfig() {
 }
 
 export function saveConfig(newConfig) {
-  ensureDir();
+  ensureDirSync();
   cachedConfig = Object.freeze({ ...DEFAULT_CONFIG, ...newConfig });
   try {
     fs.writeFileSync(CONFIG_FILE, JSON.stringify(cachedConfig, null, 2), "utf-8");

package/mcp-server/index.js

@@ -39,13 +39,6 @@ if (cliArgs.includes("setup") || cliArgs.includes("install") || cliArgs.includes
   process.exit(0);
 }
 
-if (cliArgs.includes("admin") || cliArgs.includes("--admin") || cliArgs.includes("-a")) {
-  const { startAdminServer } = await import("./admin/server.js");
-  await startAdminServer();
-  // Keep process running for web server
-  await new Promise(() => {});
-}
-
 if (cliArgs.includes("cli") || cliArgs.includes("config") || cliArgs.includes("--cli") || cliArgs.includes("-c")) {
   const { runCli } = await import("./cli.js");
   await runCli();
@@ -453,12 +446,13 @@ server.registerTool(
     description:
       "Ingest a document into the RAG knowledge base. " +
       "Accepts local file paths, web URLs, or raw Markdown/text content. " +
+      "For type='file' the file is read from disk and indexed with a code-block wrapper. " +
       "For type='url' the page is fetched and its content is indexed (not just the URL). " +
       "Processes document through 3-tier hierarchy chunking (Big/Medium/Small), " +
       "computes dense vectors, and extracts GraphRAG code symbols.",
     inputSchema: z.object({
-      content: z.string().describe("Raw text content, file path, or web URL"),
-      type: z.enum(["text", "file", "url"]).nullish().transform((v) => v || "text").describe("Input content type: 'text', 'file', or 'url' (url fetches the page content)"),
+      content: z.string().describe("Raw text content, file path, or web URL. For type='file' this can be the file path (reads from disk) or the file content directly"),
+      type: z.enum(["text", "file", "url"]).nullish().transform((v) => v || "text").describe("Input content type: 'text' (raw content), 'file' (reads from disk, wraps in code block), or 'url' (fetches page content)"),
       title: optStr().describe("Document title"),
       path: optStr().describe("Original document file path"),
       generateEmbeddings: defBool(true).describe("Compute dense vector embeddings"),

package/mcp-server/ingest/pipeline.js

@@ -1,4 +1,5 @@
 import { randomUUID } from "node:crypto";
+import { readFile } from "node:fs/promises";
 import { getDatabase, BLOBS_DIR } from "../db/database.js";
 import { saveBlob, deleteBlob } from "../storage/blob_store.js";
 import { normalizeContent, fetchUrlContent } from "./normalizer.js";
@@ -28,6 +29,13 @@ export async function ingestDocument({
     effectiveType = "text";
     effectiveTitle = title || fetched.title;
     effectivePath = path || fetched.finalUrl || content;
+  } else if (type === "file") {
+    const filePath = effectivePath || content;
+    const needsRead = !content || content === filePath;
+    if (needsRead && filePath) {
+      content = await readFile(filePath, "utf-8");
+      effectivePath = filePath;
+    }
   }
 
   const { markdown, title: docTitle, metadata } = normalizeContent({ content, type: effectiveType, path: effectivePath, title: effectiveTitle });

package/mcp-server/memory.js

@@ -1,192 +1,203 @@
-import { readFile, writeFile, mkdir, unlink, readdir } from "fs/promises";
-import { existsSync } from "fs";
-import { join, basename, resolve } from "path";
-import { homedir } from "os";
-
-function resolveMemoryDir() {
-  if (process.env.MEMORY_DIR) return process.env.MEMORY_DIR;
-  if (process.env.OPENCODE_CONFIG_DIR) return join(process.env.OPENCODE_CONFIG_DIR, "memory");
-
-  const legacyDir = join(homedir(), ".config", "opencode", "memory");
-  if (existsSync(legacyDir)) {
-    return legacyDir;
-  }
-
-  if (process.platform === "win32") {
-    const appData = process.env.LOCALAPPDATA || process.env.APPDATA || join(homedir(), "AppData", "Local");
-    return join(appData, "opencode", "memory");
-  }
-
-  const configHome = process.env.XDG_CONFIG_HOME || join(homedir(), ".config");
-  return join(configHome, "opencode", "memory");
-}
-
-export const MEMORY_DIR = resolveMemoryDir();
-export const GLOBAL_KEY = "global";
-
-export async function ensureDir() {
-  if (!existsSync(MEMORY_DIR)) await mkdir(MEMORY_DIR, { recursive: true });
-  const storageDir = join(MEMORY_DIR, "storage");
-  const blobsDir = join(storageDir, "blobs");
-  const modelsDir = join(storageDir, "models");
-  const exportsDir = join(MEMORY_DIR, "exports");
-  if (!existsSync(blobsDir)) await mkdir(blobsDir, { recursive: true });
-  if (!existsSync(modelsDir)) await mkdir(modelsDir, { recursive: true });
-  if (!existsSync(exportsDir)) await mkdir(exportsDir, { recursive: true });
-}
-
-// Canonical absolute path key: forward slashes, lowercase drive letter on win32.
-export function canonicalPath(dir) {
-  let p = resolve(dir || process.cwd());
-  if (process.platform === "win32") {
-    p = p.replace(/\\/g, "/").replace(/^([a-zA-Z]):/, (_, d) => `${d.toLowerCase()}:`);
-  }
-  return p;
-}
-
-// Project store key = full directory path. This removes basename collisions and
-// binds each store to the real project location.
-export function projectKey(worktree, directory) {
-  return canonicalPath(worktree || directory);
-}
-
-// Display label for a project (basename of the resolved directory).
-export function projectName(worktree, directory) {
-  const dir = worktree || directory || process.cwd();
-  return dir ? basename(resolve(dir)) : "default";
-}
-
-export function scopeKey(scope, worktree, directory) {
-  return scope === "global" ? GLOBAL_KEY : projectKey(worktree, directory);
-}
-
-function slugify(key) {
-  return key.replace(/[^a-zA-Z0-9_-]/g, "_");
-}
-
-function memoryPath(key) {
-  return join(MEMORY_DIR, `${slugify(key)}.md`);
-}
-
-export function memoryFileName(key) {
-  return basename(memoryPath(key));
-}
-
-export function storeFilePath(key) {
-  return memoryPath(key);
-}
-
-function parseMeta(content) {
-  const m = content.match(/<!-- path: (.+?) -->/);
-  return { path: m ? m[1].trim() : null };
-}
-
-function isSimpleKey(key) {
-  return /^[a-zA-Z0-9_-]+$/.test(key);
-}
-
-// Lazy migration: when reading a project path store that doesn't exist yet but a
-// legacy <basename>.md store (without path binding) does, claim it under the path.
-async function maybeMigrateLegacy(key) {
-  if (key === GLOBAL_KEY || isSimpleKey(key)) return null;
-  const legacyBasename = basename(key);
-  if (!legacyBasename) return null;
-  const legacyFp = join(MEMORY_DIR, `${legacyBasename}.md`);
-  if (slugify(key) === legacyBasename || !existsSync(legacyFp)) return null;
-  const content = await readFile(legacyFp, "utf-8");
-  if (parseMeta(content).path) return null; // already bound to another project
-  // Collision guard: a different path with the same basename is already bound,
-  // so this legacy store is ambiguous and must not be silently claimed.
-  const files = await readdir(MEMORY_DIR).catch(() => []);
-  for (const f of files) {
-    if (!f.endsWith(".md") || f === `${legacyBasename}.md` || f === `${GLOBAL_KEY}.md`) continue;
-    try {
-      const other = parseMeta(await readFile(join(MEMORY_DIR, f), "utf-8")).path;
-      if (other && basename(other) === legacyBasename) return null;
-    } catch (e) {}
-  }
-  const facts = content.split("\n").filter((l) => l.startsWith("- ["));
-  await writeMemory(key, facts);
-  try {
-    await unlink(legacyFp);
-  } catch (e) {}
-  return facts;
-}
-
-export async function readMemory(key) {
-  const fp = memoryPath(key);
-  if (existsSync(fp)) {
-    const content = await readFile(fp, "utf-8");
-    return content.split("\n").filter((l) => l.startsWith("- ["));
-  }
-  const migrated = await maybeMigrateLegacy(key);
-  return migrated || [];
-}
-
-export async function readMemoryRaw(key) {
-  return (await readMemory(key)).map((e) => e.slice(2));
-}
-
-export async function writeMemory(key, entries) {
-  const lines = [];
-  if (key === GLOBAL_KEY) {
-    lines.push("# Global Memory", "");
-  } else {
-    lines.push(`# Memory: ${basename(key) || key}`, "");
-    if (!isSimpleKey(key)) {
-      lines.push(`<!-- path: ${key} -->`, "");
-    }
-  }
-  const content = lines.join("\n") + "\n" + (entries.length ? entries.join("\n") + "\n" : "");
-  await writeFile(memoryPath(key), content);
-}
-
-export async function listProjectStores() {
-  const stores = [];
-  const files = await readdir(MEMORY_DIR).catch(() => []);
-  for (const f of files) {
-    if (!f.endsWith(".md") || f === `${GLOBAL_KEY}.md`) continue;
-    const fp = join(MEMORY_DIR, f);
-    let content = "";
-    try {
-      content = await readFile(fp, "utf-8");
-    } catch (e) {
-      continue;
-    }
-    const facts = content.split("\n").filter((l) => l.startsWith("- ["));
-    const meta = parseMeta(content);
-    const key = meta.path || f.slice(0, -3);
-    stores.push({
-      key,
-      path: meta.path,
-      basename: basename(meta.path || key) || key,
-      file: f,
-      count: facts.length,
-      legacy: !meta.path,
-    });
-  }
-  stores.sort((a, b) => a.basename.localeCompare(b.basename));
-  return stores;
-}
-
-// Bind an unbound legacy store (e.g. "comfy-meta-viewer") to a directory path.
-export async function migrateLegacyStore(legacyKey, targetDir) {
-  const legacyFp = join(MEMORY_DIR, `${legacyKey.replace(/[^a-zA-Z0-9_-]/g, "_")}.md`);
-  if (!existsSync(legacyFp)) return { ok: false, reason: "not_found", key: legacyKey };
-  const content = await readFile(legacyFp, "utf-8");
-  if (parseMeta(content).path) return { ok: false, reason: "already_bound", key: legacyKey };
-  const targetKey = projectKey(targetDir, null);
-  const facts = content.split("\n").filter((l) => l.startsWith("- ["));
-  await writeMemory(targetKey, facts);
-  try {
-    await unlink(legacyFp);
-  } catch (e) {}
-  return { ok: true, key: targetKey, file: memoryPath(targetKey), facts: facts.length };
-}
-
-export function today() {
-  const d = new Date();
-  const date = `${d.getFullYear()}-${String(d.getMonth() + 1).padStart(2, "0")}-${String(d.getDate()).padStart(2, "0")}`;
-  const time = `${String(d.getHours()).padStart(2, "0")}:${String(d.getMinutes()).padStart(2, "0")}`;
-  return `${date} ${time}`;
-}
+import { readFile, writeFile, mkdir, unlink, readdir } from "fs/promises";
+import { existsSync, mkdirSync } from "fs";
+import { join, basename, resolve } from "path";
+import { homedir } from "os";
+
+function resolveMemoryDir() {
+  if (process.env.MEMORY_DIR) return process.env.MEMORY_DIR;
+  if (process.env.OPENCODE_CONFIG_DIR) return join(process.env.OPENCODE_CONFIG_DIR, "memory");
+
+  const legacyDir = join(homedir(), ".config", "opencode", "memory");
+  if (existsSync(legacyDir)) {
+    return legacyDir;
+  }
+
+  if (process.platform === "win32") {
+    const appData = process.env.LOCALAPPDATA || process.env.APPDATA || join(homedir(), "AppData", "Local");
+    return join(appData, "opencode", "memory");
+  }
+
+  const configHome = process.env.XDG_CONFIG_HOME || join(homedir(), ".config");
+  return join(configHome, "opencode", "memory");
+}
+
+export const MEMORY_DIR = resolveMemoryDir();
+export const GLOBAL_KEY = "global";
+
+export async function ensureDir() {
+  if (!existsSync(MEMORY_DIR)) await mkdir(MEMORY_DIR, { recursive: true });
+  const storageDir = join(MEMORY_DIR, "storage");
+  const blobsDir = join(storageDir, "blobs");
+  const modelsDir = join(storageDir, "models");
+  const exportsDir = join(MEMORY_DIR, "exports");
+  if (!existsSync(blobsDir)) await mkdir(blobsDir, { recursive: true });
+  if (!existsSync(modelsDir)) await mkdir(modelsDir, { recursive: true });
+  if (!existsSync(exportsDir)) await mkdir(exportsDir, { recursive: true });
+}
+
+export function ensureDirSync() {
+  if (!existsSync(MEMORY_DIR)) mkdirSync(MEMORY_DIR, { recursive: true });
+  const storageDir = join(MEMORY_DIR, "storage");
+  const blobsDir = join(storageDir, "blobs");
+  const modelsDir = join(storageDir, "models");
+  const exportsDir = join(MEMORY_DIR, "exports");
+  if (!existsSync(blobsDir)) mkdirSync(blobsDir, { recursive: true });
+  if (!existsSync(modelsDir)) mkdirSync(modelsDir, { recursive: true });
+  if (!existsSync(exportsDir)) mkdirSync(exportsDir, { recursive: true });
+}
+
+// Canonical absolute path key: forward slashes, lowercase drive letter on win32.
+export function canonicalPath(dir) {
+  let p = resolve(dir || process.cwd());
+  if (process.platform === "win32") {
+    p = p.replace(/\\/g, "/").replace(/^([a-zA-Z]):/, (_, d) => `${d.toLowerCase()}:`);
+  }
+  return p;
+}
+
+// Project store key = full directory path. This removes basename collisions and
+// binds each store to the real project location.
+export function projectKey(worktree, directory) {
+  return canonicalPath(worktree || directory);
+}
+
+// Display label for a project (basename of the resolved directory).
+export function projectName(worktree, directory) {
+  const dir = worktree || directory || process.cwd();
+  return dir ? basename(resolve(dir)) : "default";
+}
+
+export function scopeKey(scope, worktree, directory) {
+  return scope === "global" ? GLOBAL_KEY : projectKey(worktree, directory);
+}
+
+function slugify(key) {
+  return key.replace(/[^a-zA-Z0-9_-]/g, "_");
+}
+
+function memoryPath(key) {
+  return join(MEMORY_DIR, `${slugify(key)}.md`);
+}
+
+export function memoryFileName(key) {
+  return basename(memoryPath(key));
+}
+
+export function storeFilePath(key) {
+  return memoryPath(key);
+}
+
+function parseMeta(content) {
+  const m = content.match(/<!-- path: (.+?) -->/);
+  return { path: m ? m[1].trim() : null };
+}
+
+function isSimpleKey(key) {
+  return /^[a-zA-Z0-9_-]+$/.test(key);
+}
+
+// Lazy migration: when reading a project path store that doesn't exist yet but a
+// legacy <basename>.md store (without path binding) does, claim it under the path.
+async function maybeMigrateLegacy(key) {
+  if (key === GLOBAL_KEY || isSimpleKey(key)) return null;
+  const legacyBasename = basename(key);
+  if (!legacyBasename) return null;
+  const legacyFp = join(MEMORY_DIR, `${legacyBasename}.md`);
+  if (slugify(key) === legacyBasename || !existsSync(legacyFp)) return null;
+  const content = await readFile(legacyFp, "utf-8");
+  if (parseMeta(content).path) return null; // already bound to another project
+  // Collision guard: a different path with the same basename is already bound,
+  // so this legacy store is ambiguous and must not be silently claimed.
+  const files = await readdir(MEMORY_DIR).catch(() => []);
+  for (const f of files) {
+    if (!f.endsWith(".md") || f === `${legacyBasename}.md` || f === `${GLOBAL_KEY}.md`) continue;
+    try {
+      const other = parseMeta(await readFile(join(MEMORY_DIR, f), "utf-8")).path;
+      if (other && basename(other) === legacyBasename) return null;
+    } catch (e) {}
+  }
+  const facts = content.split("\n").filter((l) => l.startsWith("- ["));
+  await writeMemory(key, facts);
+  try {
+    await unlink(legacyFp);
+  } catch (e) {}
+  return facts;
+}
+
+export async function readMemory(key) {
+  const fp = memoryPath(key);
+  if (existsSync(fp)) {
+    const content = await readFile(fp, "utf-8");
+    return content.split("\n").filter((l) => l.startsWith("- ["));
+  }
+  const migrated = await maybeMigrateLegacy(key);
+  return migrated || [];
+}
+
+export async function readMemoryRaw(key) {
+  return (await readMemory(key)).map((e) => e.slice(2));
+}
+
+export async function writeMemory(key, entries) {
+  const lines = [];
+  if (key === GLOBAL_KEY) {
+    lines.push("# Global Memory", "");
+  } else {
+    lines.push(`# Memory: ${basename(key) || key}`, "");
+    if (!isSimpleKey(key)) {
+      lines.push(`<!-- path: ${key} -->`, "");
+    }
+  }
+  const content = lines.join("\n") + "\n" + (entries.length ? entries.join("\n") + "\n" : "");
+  await writeFile(memoryPath(key), content);
+}
+
+export async function listProjectStores() {
+  const stores = [];
+  const files = await readdir(MEMORY_DIR).catch(() => []);
+  for (const f of files) {
+    if (!f.endsWith(".md") || f === `${GLOBAL_KEY}.md`) continue;
+    const fp = join(MEMORY_DIR, f);
+    let content = "";
+    try {
+      content = await readFile(fp, "utf-8");
+    } catch (e) {
+      continue;
+    }
+    const facts = content.split("\n").filter((l) => l.startsWith("- ["));
+    const meta = parseMeta(content);
+    const key = meta.path || f.slice(0, -3);
+    stores.push({
+      key,
+      path: meta.path,
+      basename: basename(meta.path || key) || key,
+      file: f,
+      count: facts.length,
+      legacy: !meta.path,
+    });
+  }
+  stores.sort((a, b) => a.basename.localeCompare(b.basename));
+  return stores;
+}
+
+// Bind an unbound legacy store (e.g. "comfy-meta-viewer") to a directory path.
+export async function migrateLegacyStore(legacyKey, targetDir) {
+  const legacyFp = join(MEMORY_DIR, `${legacyKey.replace(/[^a-zA-Z0-9_-]/g, "_")}.md`);
+  if (!existsSync(legacyFp)) return { ok: false, reason: "not_found", key: legacyKey };
+  const content = await readFile(legacyFp, "utf-8");
+  if (parseMeta(content).path) return { ok: false, reason: "already_bound", key: legacyKey };
+  const targetKey = projectKey(targetDir, null);
+  const facts = content.split("\n").filter((l) => l.startsWith("- ["));
+  await writeMemory(targetKey, facts);
+  try {
+    await unlink(legacyFp);
+  } catch (e) {}
+  return { ok: true, key: targetKey, file: memoryPath(targetKey), facts: facts.length };
+}
+
+export function today() {
+  const d = new Date();
+  const date = `${d.getFullYear()}-${String(d.getMonth() + 1).padStart(2, "0")}-${String(d.getDate()).padStart(2, "0")}`;
+  const time = `${String(d.getHours()).padStart(2, "0")}:${String(d.getMinutes()).padStart(2, "0")}`;
+  return `${date} ${time}`;
+}

package/mcp-server/ml/model_manager.js

@@ -388,10 +388,10 @@ export async function getReranker(modelName = "Xenova/bge-reranker-base", progre
     return rerankerInstance;
   }
 
-  checkAndSelfHealModel(modelName);
+  const cacheDir = ensureValidModelDirectory();
 
   const { pipeline, env } = await import("@huggingface/transformers");
-  env.cacheDir = MODELS_DIR;
+  env.cacheDir = cacheDir;
   env.allowLocalModels = true;
   env.allowRemoteModels = true;
   env.remoteHost = "https://huggingface.co";

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@lotargo/memory_plugin",
-  "version": "1.3.0",
-  "description": "Persistent memory agent for coding AI tools — remembers user preferences and project context across sessions. Works with Antigravity, OpenCode, Claude Code, and Codex.",
+  "version": "1.3.2",
+  "description": "100% local hybrid RAG memory for AI coding agents (OpenCode, Claude Code, Codex, Antigravity). MCP server + plugin: persistent user facts, document ingestion, vector + SQLite FTS5 retrieval across sessions.",
   "type": "module",
   "main": "opencode-plugin/index.js",
   "scripts": {
@@ -33,14 +33,29 @@
     "skills"
   ],
   "keywords": [
+    "memory",
+    "persistent-memory",
+    "ai-memory",
+    "ai-agent",
+    "ai-agents",
+    "rag",
+    "knowledge-base",
+    "llm",
+    "mcp",
+    "mcp-server",
+    "model-context-protocol",
+    "mcp-tools",
     "opencode",
     "claude-code",
     "codex",
     "antigravity",
     "plugin",
-    "memory",
-    "mcp",
-    "ai",
+    "vector-search",
+    "hybrid-search",
+    "semantic-search",
+    "embeddings",
+    "sqlite",
+    "fts5",
     "context"
   ],
   "author": "Lotargo",

package/skills/using-memory/SKILL.md

@@ -1,14 +1,15 @@
 ---
 name: using-memory
-description: Comprehensive guide for using the Memory & Hybrid RAG Knowledge Engine tools (remember, recall, forget, update_fact, memory_info, link_knowledge, ingest_document, query_knowledge_base, manage_knowledge_base). Trigger proactively whenever user preferences, project conventions, technology stack choices, or architecture decisions are introduced, or when querying ingested documentation, indexing files/repos, or managing persistent knowledge.
+description: Comprehensive guide for using the Memory, Hybrid RAG Knowledge Engine & MCP Helper tools (remember, recall, forget, update_fact, memory_info, link_knowledge, ingest_document, query_knowledge_base, manage_knowledge_base, list-mcp-tools, mcp-reminder). Trigger proactively whenever user preferences, project conventions, technology stack choices, or architecture decisions are introduced, or when querying ingested documentation, indexing files/repos, managing persistent knowledge, or looking up available MCP tool integrations.
 ---
 
-# Using Memory & Hybrid RAG Knowledge Engine
+# Using Memory, Hybrid RAG Knowledge Engine & MCP Helper Tools
 
-You have access to a persistent dual-layer memory engine supercharged with an **Agent-Driven Knowledge Graph**:
+You have access to a persistent dual-layer memory engine supercharged with an **Agent-Driven Knowledge Graph** and general MCP integration helpers:
 1. **Layer 1: Notebook Store (Key-Value Facts)**: Stores high-signal personal preferences, project conventions, and durable rules in clean Markdown.
 2. **Layer 2: RAG Knowledge Base**: Indexes documentation, repositories, and technical guides for hybrid semantic retrieval.
 3. **Layer 3: Agent-Driven Knowledge Graph**: Connects Notebook facts (Layer 1) to specific Knowledge Base documents, sections, and **exact line ranges** (Layer 2).
+4. **Integration Layer (General MCP Helpers)**: Quickly discovers connected MCP servers and identifies appropriate tools for specific tasks.
 
 ---
 
@@ -28,7 +29,9 @@ You have access to a persistent dual-layer memory engine supercharged with an **
 | User asks to index a documentation URL, file, or repository | `ingest_document` | `content` or `source_path`, `title`, `metadata` |
 | User asks a complex question about indexed docs or code | `query_knowledge_base` | `query`, `limit`, `generateEmbeddings` |
 | Read full raw content of an ambiguous/abstract document | `manage_knowledge_base` | `action: "read_document"`, `docId` |
-| User asks to view database stats, list indexed docs, or export snapshots | `manage_knowledge_base` | `action` ("stats", "list", "read_document", "delete", "export_snapshot") |
+| User asks to view database stats, list indexed docs, or export snapshots | `manage_knowledge_base` | `action` ("stats", "list", "read_document", "delete", "export_snapshot", "import_snapshot") |
+| Discover available MCP servers and their specific purposes | `list-mcp-tools` | — |
+| Ask which MCP tool / server is suitable for a specific task | `mcp-reminder` | `task` (string, e.g., "db migration") |
 
 ---
 
@@ -113,7 +116,7 @@ Use this tool when adding technical documentation, API specs, architectural docu
 
 ### Hybrid Retrieval (`query_knowledge_base`)
 Use this tool BEFORE answering deep architectural or technical questions when indexed documents exist.
-- Performs **Hybrid RRF Fusion** combining SQLite FTS5 BM25 keyword matching with dense ONNX vector semantic search.
+- Performs **Hybrid RRF/RSF Fusion** combining SQLite FTS5 BM25 keyword matching with dense ONNX vector semantic search.
 - Returns candidate sections with breadcrumb paths and defined code symbols (classes, functions, types).
 
 #### Query Formulation Rules (CRITICAL for retrieval quality)
@@ -154,13 +157,28 @@ In such cases, use the **Full Raw Document Reading** mechanism:
 - Use `action: "list"` to see all ingested documents.
 - Use `action: "read_document"` with `docId` to read the complete raw text content of any document.
 - Use `action: "delete"` with `docId` to remove an outdated document and purge its CAS blob.
+- Use `action: "export_snapshot"` with `snapshotPath` to export a JSON backup of the RAG base.
+- Use `action: "import_snapshot"` with `snapshotPath` to import and merge a JSON backup into the current database.
 
 ---
 
-## 4. Core Directives for AI Agents
+## 4. General MCP Helpers (`list-mcp-tools`, `mcp-reminder`)
+
+### Discovering Connected MCP Servers (`list-mcp-tools`)
+When working in multi-server environments (e.g., OpenCode, Claude Code), you might have several auxiliary servers installed (for database, UI design, browser automation, etc.).
+- Use `list-mcp-tools` to immediately view all registered servers and their descriptions. This avoids guessing what other capabilities are available in the current workspace.
+
+### Contextual Tool Reminders (`mcp-reminder`)
+- If you are unsure which tool/server is best suited for the task at hand (e.g., how to do browser testing, or run a database migration), run `mcp-reminder(task: "your current task definition")`.
+- It analyzes your task and suggests appropriate servers (like `playwright` for testing, `supabase` for DB, or `stitch` for UI design).
+
+---
+
+## 5. Core Directives for AI Agents
 
 1. **Read Memories First (MANDATORY)**: At the very start of any session or conversation, your VERY FIRST STEP MUST BE to execute `recall` to load all saved facts, user context, and project guidelines BEFORE performing any other task or code analysis.
 2. **Be Proactive**: When the user mentions a durable preference, personal fact, or constraint, save it immediately using `remember`. Do not wait for explicit user commands.
-3. **Check Knowledge Base First**: If a user asks how a specific module, API, or project architecture works, call `query_knowledge_base` using concept-dense search phrases.
+3. **Check Knowledge Base First**: If a query is related to specialized documentation, APIs, or project architectures, call `query_knowledge_base` using concept-dense search phrases.
 4. **Inspect Ambiguous Docs Directly**: If querying produces low relevance scores on abstractly-named documents, call `manage_knowledge_base(action: "read_document")` to inspect the full text directly.
 5. **Keep Memory Clean**: If a preference changes, call `update_fact` to edit it in place, or `remember` with `supersedes` to keep a version trail. Use `keep: true` for facts that must survive an accidental `forget`, and give ephemeral facts a `ttl` so stale ones surface as `[EXPIRED]`.
+6. **Leverage MCP Servers**: Proactively list available tools using `list-mcp-tools` and query `mcp-reminder` if unsure of which platform tool can help you automate tasks.

package/mcp-server/admin/server.js

@@ -1,228 +0,0 @@
-import { createServer } from "node:http";
-import { readFileSync, existsSync, statSync } from "node:fs";
-import { join, dirname } from "node:path";
-import { fileURLToPath } from "node:url";
-import { getDatabase, DB_PATH, BLOBS_DIR } from "../db/database.js";
-import { ingestDocument, deleteDocument } from "../ingest/pipeline.js";
-import { hybridQuery } from "../retrieval/retriever.js";
-import { exportSnapshot, importSnapshot } from "./snapshot.js";
-import { readBlob } from "../storage/blob_store.js";
-
-const __filename = fileURLToPath(import.meta.url);
-const __dirname = dirname(__filename);
-
-export function findAvailablePort(startPort = 8765, maxPort = 8785) {
-  return new Promise((resolve, reject) => {
-    let port = startPort;
-    const tryPort = () => {
-      if (port > maxPort) {
-        return reject(new Error(`No free port found between ${startPort} and ${maxPort}`));
-      }
-      const server = createServer();
-      server.listen(port, () => {
-        server.close(() => resolve(port));
-      });
-      server.on("error", () => {
-        port++;
-        tryPort();
-      });
-    };
-    tryPort();
-  });
-}
-
-function parseJsonBody(req) {
-  return new Promise((resolve, reject) => {
-    let body = "";
-    req.on("data", (chunk) => {
-      body += chunk.toString();
-    });
-    req.on("end", () => {
-      try {
-        resolve(body ? JSON.parse(body) : {});
-      } catch (err) {
-        reject(err);
-      }
-    });
-    req.on("error", reject);
-  });
-}
-
-export async function startAdminServer({ port = null, customDb = null, customBlobDir = BLOBS_DIR } = {}) {
-  const db = customDb || getDatabase();
-  const selectedPort = port || (await findAvailablePort());
-  const htmlPath = join(__dirname, "index.html");
-
-  const server = createServer(async (req, res) => {
-    const url = new URL(req.url, `http://${req.headers.host || "localhost"}`);
-    const pathname = url.pathname;
-
-    // Helper for CORS and JSON response
-    const sendJson = (data, status = 200) => {
-      res.writeHead(status, {
-        "Content-Type": "application/json",
-        "Access-Control-Allow-Origin": "*",
-        "Access-Control-Allow-Methods": "GET, POST, DELETE, OPTIONS",
-        "Access-Control-Allow-Headers": "Content-Type",
-      });
-      res.end(JSON.stringify(data));
-    };
-
-    if (req.method === "OPTIONS") {
-      res.writeHead(204, {
-        "Access-Control-Allow-Origin": "*",
-        "Access-Control-Allow-Methods": "GET, POST, DELETE, OPTIONS",
-        "Access-Control-Allow-Headers": "Content-Type",
-      });
-      return res.end();
-    }
-
-    try {
-      // 1. Static HTML SPA
-      if (pathname === "/" || pathname === "/index.html") {
-        if (!existsSync(htmlPath)) {
-          res.writeHead(404, { "Content-Type": "text/plain" });
-          return res.end("index.html not found");
-        }
-        const html = readFileSync(htmlPath, "utf-8");
-        res.writeHead(200, { "Content-Type": "text/html; charset=utf-8" });
-        return res.end(html);
-      }
-
-      // 2. API: Stats
-      if (pathname === "/api/stats" && req.method === "GET") {
-        const docCount = db.prepare("SELECT COUNT(*) as cnt FROM documents").get().cnt;
-        const secCount = db.prepare("SELECT COUNT(*) as cnt FROM sections").get().cnt;
-        const chunkCount = db.prepare("SELECT COUNT(*) as cnt FROM micro_chunks").get().cnt;
-        const edgeCount = db.prepare("SELECT COUNT(*) as cnt FROM graph_edges").get().cnt;
-        let dbSize = 0;
-        if (existsSync(DB_PATH)) {
-          try {
-            dbSize = statSync(DB_PATH).size;
-          } catch {}
-        }
-        return sendJson({
-          documents: docCount,
-          sections: secCount,
-          micro_chunks: chunkCount,
-          graph_edges: edgeCount,
-          db_size_bytes: dbSize,
-        });
-      }
-
-      // 3. API: Documents List
-      if (pathname === "/api/documents" && req.method === "GET") {
-        const docs = db.prepare("SELECT * FROM documents ORDER BY updated_at DESC").all();
-        return sendJson(docs);
-      }
-
-      // 4. API: Document Detail
-      if (pathname.startsWith("/api/documents/") && req.method === "GET") {
-        const docId = pathname.replace("/api/documents/", "");
-        const doc = db.prepare("SELECT * FROM documents WHERE id = ?").get(docId);
-        if (!doc) return sendJson({ error: "Document not found" }, 404);
-
-        const sections = db.prepare("SELECT * FROM sections WHERE doc_id = ?").all(docId);
-        const microChunks = db.prepare("SELECT id, section_id, token_count FROM micro_chunks WHERE doc_id = ?").all(docId);
-        const edges = db.prepare("SELECT * FROM graph_edges WHERE source_id = ? OR target_id = ?").all(docId, docId);
-
-        let blobContent = null;
-        if (doc.blob_hash) {
-          try {
-            blobContent = await readBlob(doc.blob_hash, customBlobDir);
-          } catch {}
-        }
-
-        return sendJson({ doc, sections, microChunks, edges, blobContent });
-      }
-
-      // 5. API: Delete Document
-      if (pathname.startsWith("/api/documents/") && req.method === "DELETE") {
-        const docId = pathname.replace("/api/documents/", "");
-        const result = await deleteDocument(docId, db, customBlobDir);
-        return sendJson(result);
-      }
-
-      // 6. API: Ingest Document
-      if (pathname === "/api/ingest" && req.method === "POST") {
-        const body = await parseJsonBody(req);
-        const result = await ingestDocument({
-          content: body.content,
-          type: body.type || "text",
-          path: body.path || null,
-          title: body.title || null,
-          generateEmbeddings: body.generateEmbeddings !== false,
-          customDb: db,
-          customBlobDir,
-        });
-        return sendJson(result, 201);
-      }
-
-      // 7. API: Query Knowledge Base
-      if (pathname === "/api/query" && req.method === "POST") {
-        const body = await parseJsonBody(req);
-        const results = await hybridQuery({
-          query: body.query,
-          limit: body.limit || 5,
-          generateEmbeddings: body.generateEmbeddings !== false,
-          customDb: db,
-        });
-        return sendJson({ results });
-      }
-
-      // 8. API: Graph Visualizer Data
-      if (pathname === "/api/graph" && req.method === "GET") {
-        const docs = db.prepare("SELECT id, title, path FROM documents").all();
-        const edges = db.prepare("SELECT * FROM graph_edges").all();
-        
-        const nodes = docs.map((d) => ({
-          id: d.id,
-          label: d.title || d.path || d.id,
-          type: "DOCUMENT",
-        }));
-
-        // Add code symbol nodes
-        const symbolEdges = edges.filter((e) => e.relation_type === "DEFINES_SYMBOL");
-        for (const se of symbolEdges) {
-          if (!nodes.some((n) => n.id === se.target_id)) {
-            nodes.push({
-              id: se.target_id,
-              label: se.target_id,
-              type: "CODE_SYMBOL",
-            });
-          }
-        }
-
-        return sendJson({ nodes, edges });
-      }
-
-      // 9. API: Export Snapshot
-      if (pathname === "/api/snapshot/export" && (req.method === "GET" || req.method === "POST")) {
-        const snapshot = await exportSnapshot({ customDb: db, customBlobDir });
-        return sendJson(snapshot);
-      }
-
-      // 10. API: Import Snapshot
-      if (pathname === "/api/snapshot/import" && req.method === "POST") {
-        const body = await parseJsonBody(req);
-        const result = await importSnapshot({ customDb: db, customBlobDir, snapshotPathOrData: body });
-        return sendJson(result);
-      }
-
-      // 404 Fallback
-      res.writeHead(404, { "Content-Type": "text/plain" });
-      res.end("Not Found");
-    } catch (err) {
-      console.error("Admin server error:", err);
-      sendJson({ error: err.message }, 500);
-    }
-  });
-
-  return new Promise((resolve) => {
-    server.listen(selectedPort, () => {
-      const url = `http://localhost:${selectedPort}`;
-      console.log(`🚀 memory-agent Web Admin Dashboard running at ${url}`);
-      resolve({ server, port: selectedPort, url });
-    });
-  });
-}