mcp-rag-memory 2.4.1 → 2.5.0

package/.env.example

@@ -1,6 +1,7 @@
 # Copy to `.env` and adjust. Picked up automatically by `npx mcp-rag-memory`,
 # `npm run dev`, and `npm run start` (see src/env.ts). Host environment
-# variables always override these values.
+# variables always override these values, and only RAG_*/OPENCODE_*/EMBEDDING_*/
+# SEARCH_MODE entries in this file are loaded — anything else is ignored.
 
 # Where the SQLite store lives (default: <project>/.rag-data)
 RAG_DB_DIR=.rag-data
@@ -24,6 +25,7 @@ RAG_AUTOSYNC=1
 RAG_SESSION_CONDENSE=1
 RAG_SESSION_CONDENSE_MIN_CHARS=120
 RAG_SESSION_CONDENSE_RATIO=0.35
+# RAG_SESSION_MAX_MSGS=500
 
 # Optional pruning during consolidation
 RAG_PRUNE=0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 mcp-rag-memory contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -22,12 +22,16 @@ context **across sessions**.
 
 ## Quick start
 
+Requires **Node.js ≥ 22.12** (for `node:sqlite` read-only handles and
+`busy_timeout`).
+
 ```bash
 npm install
-npm test                 # 114 checks: unit + MCP round-trip via SDK client
+npm test                 # 160 checks: unit + MCP round-trip via SDK client
 npm run lint             # oxlint
+npm run typecheck        # src + scripts + .opencode/plugin
 npm run build            # compile to dist/
-npm run cli -- stats     # CLI playground
+npm run cli -- docs      # CLI playground
 ```
 
 ### Run from npm (npx)
@@ -133,6 +137,21 @@ The MCP server is registered here so it works in **every project**, not just thi
 > from this project's `node_modules` and stores data in the same DB
 > regardless of which project opencode is opened from.
 
+**Re-assert this global config with one command.** opencode updates have
+been observed to reset/wipe the global config (the MCP server, plugin,
+LSP and instructions disappear from new sessions). `scripts/setup-opencode.*`
+rewrite both `opencode.json` and `opencode.jsonc` (PowerShell on Windows,
+portable bash elsewhere; dispatcher `npm run setup-opencode`), **merging**
+with what is already there — user keys are never clobbered, arrays
+(`instructions`, `plugin`) are unioned, broken files are backed up to
+`.bak-<ts>`, and runs are idempotent. Re-run it (and restart opencode)
+after any opencode update:
+
+```bash
+npm run setup-opencode          # merge-in our defaults
+npm run setup-opencode -- --check   # exit 0 = up to date, 1 = changes pending
+```
+
 ### Project config (`opencode.json` in this repo)
 
 Keeps project-specific settings (model, LSP, permissions, instructions) — **no `mcp` block here**:
@@ -181,14 +200,14 @@ Restart opencode after any config change.
 | | `rag_ingest_dir` | Recursively ingest source files |
 | RAG query | `rag_search` | Hybrid (BM25 + vector) search, ranked chunks + scores |
 | | `rag_retrieve` | Ready-to-inject context block with token count |
-| RAG docs | `rag_list_documents`, `rag_document_stats` | Inventory |
+| RAG docs | `rag_list_documents`, `rag_document_stats` | Inventory (`rag_list_documents` is paginated: `limit` 1–1000, `offset`) |
 | | `rag_delete_document` | Remove a document + chunks + FTS rows |
 | Session sync | `rag_sync_session` | Ingest an opencode session's user inputs (or the latest in a workspace) |
 | Memory | `memory_remember` | Save long-term memory (type/importance/tags) |
 | | `memory_recall` | Semantic memory search (decay + recall count) |
 | | `memory_context` | Compact context block from memories for prompts |
 | | `memory_list`, `memory_get`, `memory_update`, `memory_forget` | CRUD |
-| | `memory_consolidate` | Dedupe near-identical + promote hot memories |
+| | `memory_consolidate` | Dedupe near-identical (cosine **and** word overlap) + promote hot memories |
 | | `memory_stats` | Counts, tokens, avg importance, by type |
 
 ## Run in other AI assistants
@@ -279,6 +298,7 @@ npm run cli -- recall "deployment schedule"
 npm run cli -- ingest-dir ./src/rag
 npm run cli -- search "vector similarity"
 npm run cli -- search "auth bug" --source opencode-db   # filter by source or doc-id
+npm run cli -- docs --limit 20 --offset 20            # paginated inventory
 npm run cli -- mem-context "database"
 npm run cli -- sessions              # list recent opencode sessions
 npm run cli -- sync-session ses_123  # ingest one session's inputs
@@ -383,10 +403,19 @@ Data lives in `.rag-data/rag.sqlite` (git-ignored).
 | `RAG_PRUNE_IMPORTANCE` | `0.2` | Delete memories below this importance |
 | `RAG_PRUNE_AGE_DAYS` | `90` | ...and older than this (never-recalled only) |
 | `RAG_AUTOSYNC` | `1` | Set `0` to disable the session-logger plugin's auto-sync |
-| `OPENCODE_DB` / `OPENCODE_DB_LOCAL` | `~/.local/share/opencode/*.db` | Where session transcripts are read from |
+| `OPENCODE_DB` / `OPENCODE_DB_LOCAL` | `~/.local/share/opencode/*.db` | Where session transcripts are read from (re-read on every call, so it can be set late) |
+| `RAG_SESSION_MAX_MSGS` | `500` | Cap on user messages read from one session |
 | `RAG_SESSION_CONDENSE` | `1` | Set `0` to store session inputs verbatim |
 | `RAG_SESSION_CONDENSE_MIN_CHARS` | `120` | Inputs at/below this length are saved whole |
 | `RAG_SESSION_CONDENSE_RATIO` | `0.35` | Fraction of long-input length to keep as key points |
+| `RAG_ENV_FILE` | `<cwd>/.env` | Env file to load at boot |
+
+A `.env` file can only set this server's own variables (`RAG_*`,
+`OPENCODE_*`, `EMBEDDING_*`, `SEARCH_MODE`); anything else in it is
+ignored with a warning on stderr, and a real environment variable always
+wins over the file. The loader runs from `dist/index.js` and
+`dist/cli.js` only — if you invoke `src/mcp/rag-server.ts` directly
+(TSX/`npx tsx`), import `src/env.js` yourself.
 
 ## Testing
 
@@ -489,8 +518,13 @@ instant.
 ### Opencode feels sluggish / UI lag after adding plugins
 
 Plugins that run synchronous I/O or write to stderr on every tool call
-can slow down the TUI. This project no longer ships any plugins — keep
-`opencode.json` plugin-free for clean operation.
+can slow down the TUI. This repo ships exactly one plugin
+(`.opencode/plugin/session-logger.ts`) and it is debounced to at most one
+`npx … sync-latest` per 60s, spawned detached with `stdio: "ignore"` and
+`shell: false`. If it still costs too much, set `RAG_AUTOSYNC=0` (keeps the
+plugin, disables the auto-sync) or drop the `plugin` entry from
+`opencode.json` — the MCP server and its 19 tools keep working, you just have
+to call `rag_sync_session` yourself.
 
 ---
 

package/dist/cli.js

@@ -54,25 +54,33 @@ function assertMemoryType(type) {
         throw new Error(`Invalid memory type "${type}". Valid: ${MEMORY_TYPES.join(", ")}`);
     }
 }
+function requireArg(value, usage) {
+    if (!value || value.startsWith("--"))
+        throw new Error(`Missing argument — usage: ${usage}`);
+    return value;
+}
 async function run(cmd, args) {
     let out;
     try {
         switch (cmd) {
             case "ingest-text": {
-                const [title, fileOrDash] = args;
+                const parsed = parseOpts(args);
+                const [title, fileOrDash] = parsed.positional;
+                if (!title || !fileOrDash)
+                    throw new Error("Missing argument — usage: ingest-text <title> <file|->");
                 const content = fileOrDash === "-" ? fs.readFileSync(0, "utf-8") : fs.readFileSync(fileOrDash, "utf-8");
-                out = await ingestText(content, title ?? fileOrDash ?? "untitled");
+                out = await ingestText(content, title);
                 break;
             }
             case "ingest-file":
-                out = await ingestFile(args[0]);
+                out = await ingestFile(requireArg(args[0], "ingest-file <path>"));
                 break;
             case "ingest-dir":
-                out = await ingestDirectory(args[0], { recursive: true });
+                out = await ingestDirectory(requireArg(args[0], "ingest-dir <dir>"), { recursive: true });
                 break;
             case "search": {
                 const parsed = parseOpts(args);
-                out = await searchDocs(parsed.positional.join(" "), undefined, undefined, {
+                out = await searchDocs(queryArg(parsed.positional), toNum(parsed.opts["top-k"], 10), toNum(parsed.opts["min-score"], 0.08), {
                     docId: parsed.opts["doc-id"],
                     source: parsed.opts.source,
                 });
@@ -80,67 +88,84 @@ async function run(cmd, args) {
             }
             case "retrieve": {
                 const parsed = parseOpts(args);
-                out = await retrieve(parsed.positional.join(" "), undefined, undefined, {
+                out = await retrieve(queryArg(parsed.positional), toNum(parsed.opts["top-k"], 6), toNum(parsed.opts["min-score"], 0.08), {
                     docId: parsed.opts["doc-id"],
                     source: parsed.opts.source,
                 });
                 break;
             }
-            case "docs":
-                out = listDocuments();
+            case "docs": {
+                const parsed = parseOpts(args);
+                out = listDocuments({ limit: toNum(parsed.opts.limit, undefined), offset: toNum(parsed.opts.offset, undefined) });
                 break;
+            }
             case "doc-stats":
                 out = documentStats();
                 break;
             case "rm-doc":
-                out = deleteDocument(args[0]);
+                out = deleteDocument(requireArg(args[0], "rm-doc <doc_id>"));
                 break;
             case "remember": {
                 const parsed = parseOpts(args);
+                const content = parsed.positional.join(" ");
+                if (!content)
+                    throw new Error("Missing argument — usage: remember <content> [--type fact] [--importance 0.5] [--tag x]");
                 const type = parsed.opts.type ?? "fact";
                 assertMemoryType(type);
                 out = await remember({
-                    content: parsed.positional.join(" "),
+                    content,
                     type,
-                    importance: parsed.opts.importance !== undefined ? Number(parsed.opts.importance) : 0.5,
+                    importance: toNum(parsed.opts.importance, 0.5),
                     tags: parsed.opts.tag ? [parsed.opts.tag] : undefined,
                 });
                 break;
             }
-            case "recall":
-                out = await recall(args.join(" "));
+            case "recall": {
+                const parsed = parseOpts(args);
+                out = await recall(queryArg(parsed.positional), toNum(parsed.opts["top-k"], 8), toNum(parsed.opts["min-score"], 0.1));
                 break;
+            }
             case "memory-list": {
                 const parsed = parseOpts(args);
+                const type = parsed.opts.type;
+                if (type !== undefined)
+                    assertMemoryType(type);
                 out = listMemories({
-                    type: parsed.opts.type,
+                    type,
                     tag: parsed.opts.tag,
-                    minImportance: parsed.opts["min-importance"] !== undefined ? Number(parsed.opts["min-importance"]) : undefined,
+                    minImportance: toNum(parsed.opts["min-importance"], undefined),
+                    limit: toNum(parsed.opts.limit, undefined),
                 });
                 break;
             }
             case "memory-get":
-                out = getMemory(args[0]);
+                out = getMemory(requireArg(args[0], "memory-get <id>"));
                 break;
             case "memory-update": {
                 const [id, ...restArgs] = args;
                 const parsed = parseOpts(restArgs);
-                const type = parsed.opts.type ?? "fact";
-                assertMemoryType(type);
+                if (!id)
+                    throw new Error("Missing argument — usage: memory-update <id> [--content ...] [--importance 0.8] [--type fact] [--tag x]");
+                const type = parsed.opts.type;
+                if (type !== undefined)
+                    assertMemoryType(type);
+                // --content=... (or --content <text>) sets the body; leftover positional
+                // words are the body too. The old `!== "true"` check silently discarded
+                // any content that was literally the word "true".
+                const content = parsed.opts.content ?? (parsed.positional.length ? parsed.positional.join(" ") : undefined);
+                if (content === undefined && type === undefined && parsed.opts.importance === undefined && parsed.opts.tag === undefined) {
+                    throw new Error("Nothing to update — pass --content, --type, --importance and/or --tag");
+                }
                 out = await updateMemory(id, {
-                    content: parsed.opts.content && parsed.opts.content !== "true"
-                        ? parsed.opts.content
-                        : parsed.positional.length
-                            ? parsed.positional.join(" ")
-                            : undefined,
-                    importance: parsed.opts.importance !== undefined ? Number(parsed.opts.importance) : undefined,
+                    content,
+                    importance: toNum(parsed.opts.importance, undefined),
                     type,
                     tags: parsed.opts.tag ? [parsed.opts.tag] : undefined,
                 });
                 break;
             }
             case "forget":
-                out = forget(args[0]);
+                out = forget(requireArg(args[0], "forget <id>"));
                 break;
             case "consolidate":
                 out = await consolidate();
@@ -148,15 +173,17 @@ async function run(cmd, args) {
             case "memory-stats":
                 out = memoryStats();
                 break;
-            case "mem-context":
-                out = await contextPrompt(args.join(" "));
+            case "mem-context": {
+                const parsed = parseOpts(args);
+                out = await contextPrompt(queryArg(parsed.positional), toNum(parsed.opts["top-k"], 6));
                 break;
+            }
             case "stats":
                 out = { documents: documentStats(), memories: memoryStats(), dbDir: STORAGE_DIR };
                 break;
             case "sessions": {
                 const parsed = parseOpts(args);
-                out = listOpenCodeSessions(parsed.opts.limit ? Number(parsed.opts.limit) : 15);
+                out = listOpenCodeSessions(toNum(parsed.opts.limit, 15) ?? 15, { directory: parsed.opts.dir });
                 break;
             }
             case "sync-session": {
@@ -164,12 +191,15 @@ async function run(cmd, args) {
                 const parsed = parseOpts(restArgs);
                 if (!id)
                     throw new Error("sync-session <sessionId> — run 'cli sessions' to list ids");
-                out = await ingestSession(id, { limit: parsed.opts.limit ? Number(parsed.opts.limit) : 0 });
+                out = await ingestSession(id, { limit: toNum(parsed.opts.limit, 0) ?? 0 });
                 break;
             }
             case "sync-latest": {
                 const parsed = parseOpts(args);
-                out = await ingestLatest({ limit: parsed.opts.limit ? Number(parsed.opts.limit) : 0, directory: parsed.opts.dir });
+                out = await ingestLatest({
+                    limit: toNum(parsed.opts.limit, 0) ?? 0,
+                    directory: parsed.opts.dir ?? parsed.positional[0],
+                });
                 break;
             }
             case "sync-logs": {
@@ -178,7 +208,7 @@ async function run(cmd, args) {
                 break;
             }
             case "ingest-jsonl":
-                out = await ingestJsonlFile(args[0]);
+                out = await ingestJsonlFile(requireArg(args[0], "ingest-jsonl <file>"));
                 break;
             default:
                 console.error(`Unknown command: ${cmd}`);
@@ -188,23 +218,39 @@ async function run(cmd, args) {
     }
     catch (e) {
         console.error(`Error: ${e.message}`);
+        closeDB();
         process.exit(1);
     }
     console.log(JSON.stringify(out, null, 2));
 }
+/** Query text from positional words — empty input is an error, not a silent []. */
+function queryArg(positional) {
+    const q = positional.join(" ").trim();
+    if (!q)
+        throw new Error("Missing query — usage: <command> <query>");
+    return q;
+}
 function parseOpts(args) {
     const positional = [];
     const opts = {};
     for (let i = 0; i < args.length; i++) {
         const a = args[i];
         if (a.startsWith("--")) {
+            const eq = a.indexOf("=");
+            if (eq > 0) {
+                // --key=value: the value may legitimately start with "--".
+                opts[a.slice(2, eq)] = a.slice(eq + 1);
+                continue;
+            }
             const key = a.slice(2);
             const next = args[i + 1];
-            if (next && !next.startsWith("--")) {
+            if (next !== undefined && !next.startsWith("--")) {
                 opts[key] = next;
                 i++;
             }
             else {
+                // Boolean flag. Previously the literal "true" was stored as the value,
+                // which then leaked into --content and --dir.
                 opts[key] = "true";
             }
         }
@@ -214,6 +260,13 @@ function parseOpts(args) {
     }
     return { positional, opts };
 }
+/** Parse a numeric CLI option; falls back to `fallback` for missing/garbage input. */
+function toNum(raw, fallback) {
+    if (raw === undefined)
+        return fallback;
+    const n = Number(raw);
+    return Number.isFinite(n) ? n : fallback;
+}
 main().catch((e) => {
     console.error(`Error: ${e.message}`);
     process.exit(1);

package/dist/db/database.d.ts

@@ -5,9 +5,9 @@ export declare function getDB(): DatabaseSync;
 /** SHA-256 hex of raw content — used for document dedup. */
 export declare function contentHash(content: string): string;
 export declare function newId(): string;
-/** Serialize a Float64Array embedding to a SQLite BLOB. */
+/** Serialize a Float64Array embedding to a SQLite BLOB (view-safe). */
 export declare function packVector(v: Float64Array): Uint8Array;
-/** Deserialize a BLOB back into a Float64Array. */
+/** Deserialize a BLOB back into a Float64Array. Returns null on absent/partial data. */
 export declare function unpackVector(blob: Uint8Array | null): Float64Array | null;
 export declare function nowMs(): number;
 export declare function closeDB(): void;

package/dist/db/database.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"database.d.ts","sourceRoot":"","sources":["../../src/db/database.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAK3C,eAAO,MAAM,WAAW,QAEoB,CAAC;AAE7C,eAAO,MAAM,OAAO,QAAuC,CAAC;AAU5D,wBAAgB,KAAK,IAAI,YAAY,CAUpC;AAgFD,4DAA4D;AAC5D,wBAAgB,WAAW,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAEnD;AAED,wBAAgB,KAAK,IAAI,MAAM,CAE9B;AAED,2DAA2D;AAC3D,wBAAgB,UAAU,CAAC,CAAC,EAAE,YAAY,GAAG,UAAU,CAEtD;AAED,mDAAmD;AACnD,wBAAgB,YAAY,CAAC,IAAI,EAAE,UAAU,GAAG,IAAI,GAAG,YAAY,GAAG,IAAI,CAGzE;AAED,wBAAgB,KAAK,IAAI,MAAM,CAE9B;AAED,wBAAgB,OAAO,SAGtB;AAMD,wBAAgB,WAAW,IAAI,MAAM,CAKpC;AAED,wBAAgB,YAAY,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,QAQtD;AAED;;;GAGG;AACH,wBAAgB,SAAS,CAAC,GAAG,EAAE,YAAY,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI,CAahE;AAED,wBAAgB,aAAa,IAAI,MAAM,CAKtC"}
+{"version":3,"file":"database.d.ts","sourceRoot":"","sources":["../../src/db/database.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAK3C,eAAO,MAAM,WAAW,QAEoB,CAAC;AAE7C,eAAO,MAAM,OAAO,QAAuC,CAAC;AAU5D,wBAAgB,KAAK,IAAI,YAAY,CAepC;AAyGD,4DAA4D;AAC5D,wBAAgB,WAAW,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAEnD;AAED,wBAAgB,KAAK,IAAI,MAAM,CAE9B;AAED,uEAAuE;AACvE,wBAAgB,UAAU,CAAC,CAAC,EAAE,YAAY,GAAG,UAAU,CAEtD;AAED,wFAAwF;AACxF,wBAAgB,YAAY,CAAC,IAAI,EAAE,UAAU,GAAG,IAAI,GAAG,YAAY,GAAG,IAAI,CAGzE;AAED,wBAAgB,KAAK,IAAI,MAAM,CAE9B;AAED,wBAAgB,OAAO,SAItB;AASD,wBAAgB,WAAW,IAAI,MAAM,CAQpC;AAED,wBAAgB,YAAY,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,QAStD;AAED;;;GAGG;AACH,wBAAgB,SAAS,CAAC,GAAG,EAAE,YAAY,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI,CAahE;AAED,wBAAgB,aAAa,IAAI,MAAM,CAKtC"}

package/dist/db/database.js

@@ -20,8 +20,13 @@ export function getDB() {
     db.exec("PRAGMA journal_mode = WAL;");
     db.exec("PRAGMA synchronous = NORMAL;");
     db.exec("PRAGMA foreign_keys = ON;");
-    _db = db;
+    // Wait up to 5s for a concurrent writer (CLI + MCP server + auto-save plugin
+    // all share the same store) instead of failing with SQLITE_BUSY immediately.
+    db.exec("PRAGMA busy_timeout = 5000;");
+    // Migrate BEFORE caching the handle: a failed migration must surface and be
+    // retried on the next call, never leave a half-migrated connection cached.
     migrate(db);
+    _db = db;
     return db;
 }
 function columnExists(db, table, column) {
@@ -29,6 +34,25 @@ function columnExists(db, table, column) {
     return cols.some((c) => c.name === column);
 }
 function migrate(db) {
+    // One IMMEDIATE transaction for the whole schema step: two processes opening
+    // the same fresh store (CLI + MCP server + plugin) must not race and end up
+    // with half-applied DDL or a "duplicate column" failure.
+    db.exec("BEGIN IMMEDIATE;");
+    try {
+        createSchema(db);
+        db.exec("COMMIT;");
+    }
+    catch (e) {
+        try {
+            db.exec("ROLLBACK;");
+        }
+        catch {
+            /* transaction already closed */
+        }
+        throw e;
+    }
+}
+function createSchema(db) {
     db.exec(`
     CREATE TABLE IF NOT EXISTS documents (
       id           TEXT PRIMARY KEY,
@@ -51,6 +75,7 @@ function migrate(db) {
       created_at INTEGER NOT NULL
     );
     CREATE INDEX IF NOT EXISTS idx_chunks_doc_id ON chunks(doc_id);
+    CREATE INDEX IF NOT EXISTS idx_documents_updated ON documents(updated_at DESC);
 
     CREATE TABLE IF NOT EXISTS memories (
       id           TEXT PRIMARY KEY,
@@ -66,6 +91,7 @@ function migrate(db) {
     );
     CREATE INDEX IF NOT EXISTS idx_memories_type ON memories(type);
     CREATE INDEX IF NOT EXISTS idx_memories_prune ON memories(importance, recall_count, created_at);
+    CREATE INDEX IF NOT EXISTS idx_memories_updated ON memories(updated_at DESC);
 
     CREATE TABLE IF NOT EXISTS meta (
       key   TEXT PRIMARY KEY,
@@ -84,17 +110,24 @@ function migrate(db) {
     const ftsRow = db
         .prepare("SELECT sql FROM sqlite_master WHERE type = 'table' AND name = 'chunks_fts'")
         .get();
-    if (!ftsRow) {
-        db.exec("CREATE VIRTUAL TABLE chunks_fts USING fts5(content, tokenize = 'trigram');");
-    }
-    else if (!ftsRow.sql.includes("trigram")) {
+    if (ftsRow) {
         // Existing store built with 'unicode61' — recreate with trigram and backfill.
-        db.exec("DROP TABLE chunks_fts;");
-        db.exec("CREATE VIRTUAL TABLE chunks_fts USING fts5(content, tokenize = 'trigram');");
-        db.exec(`INSERT INTO chunks_fts(rowid, content)
-         SELECT rowid, content FROM chunks`);
+        if (!ftsRow.sql.includes("trigram"))
+            rebuildFts(db);
+    }
+    else {
+        // First run with this schema (or a store whose FTS table was dropped):
+        // create AND backfill, otherwise existing chunks silently lose keyword search
+        // forever — the next boot sees "trigram" and would skip the rebuild.
+        rebuildFts(db);
     }
 }
+/** Runs inside the migrate() transaction. */
+function rebuildFts(db) {
+    db.exec("DROP TABLE IF EXISTS chunks_fts;");
+    db.exec("CREATE VIRTUAL TABLE chunks_fts USING fts5(content, tokenize = 'trigram');");
+    db.exec("INSERT INTO chunks_fts(rowid, content) SELECT rowid, content FROM chunks;");
+}
 /** SHA-256 hex of raw content — used for document dedup. */
 export function contentHash(content) {
     return createHash("sha256").update(content, "utf8").digest("hex");
@@ -102,13 +135,13 @@ export function contentHash(content) {
 export function newId() {
     return randomUUID();
 }
-/** Serialize a Float64Array embedding to a SQLite BLOB. */
+/** Serialize a Float64Array embedding to a SQLite BLOB (view-safe). */
 export function packVector(v) {
-    return new Uint8Array(v.buffer.slice(0));
+    return new Uint8Array(v.buffer.slice(v.byteOffset, v.byteOffset + v.byteLength));
 }
-/** Deserialize a BLOB back into a Float64Array. */
+/** Deserialize a BLOB back into a Float64Array. Returns null on absent/partial data. */
 export function unpackVector(blob) {
-    if (!blob || blob.byteLength === 0)
+    if (!blob || blob.byteLength === 0 || blob.byteLength % 8 !== 0)
         return null;
     return new Float64Array(blob.buffer.slice(blob.byteOffset, blob.byteOffset + blob.byteLength));
 }
@@ -118,18 +151,25 @@ export function nowMs() {
 export function closeDB() {
     _db?.close();
     _db = null;
+    cachedDim = null;
 }
 /* ------------------------------------------------------------------ */
 /* Embedding dimension metadata                                        */
 /* ------------------------------------------------------------------ */
+/** Cached embed_dim: locked on first write, so it is read once per process. */
+let cachedDim = null;
 export function getEmbedDim() {
-    const r = getDB().prepare("SELECT value FROM meta WHERE key = 'embed_dim'").get();
-    return r ? Number(r.value) : 0;
+    if (cachedDim === null) {
+        const r = getDB().prepare("SELECT value FROM meta WHERE key = 'embed_dim'").get();
+        cachedDim = r ? Number(r.value) : 0;
+    }
+    return cachedDim;
 }
 export function setEmbedMeta(dim, model) {
     const db = getDB();
     db.prepare("INSERT INTO meta(key, value) VALUES ('embed_dim', ?) ON CONFLICT(key) DO UPDATE SET value = excluded.value").run(String(dim));
     db.prepare("INSERT INTO meta(key, value) VALUES ('embed_model', ?) ON CONFLICT(key) DO UPDATE SET value = excluded.value").run(model);
+    cachedDim = dim;
 }
 /**
  * Lock the store to one embedding dimension. Call after producing a vector.

package/dist/db/database.js.map

@@ -1 +1 @@
-{"version":3,"file":"database.js","sourceRoot":"","sources":["../../src/db/database.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"database.js","sourceRoot":"","sources":["../../src/db/database.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAC3C,OAAO,KAAK,IAAI,MAAM,MAAM,CAAC;AAC7B,OAAO,KAAK,EAAE,MAAM,IAAI,CAAC;AACzB,OAAO,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAErD,MAAM,CAAC,MAAM,WAAW,GAAG,OAAO,CAAC,GAAG,CAAC,UAAU;IAC/C,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC,GAAG,CAAC,UAAU,CAAC;IACtC,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC,GAAG,EAAE,EAAE,WAAW,CAAC,CAAC;AAE7C,MAAM,CAAC,MAAM,OAAO,GAAG,IAAI,CAAC,IAAI,CAAC,WAAW,EAAE,YAAY,CAAC,CAAC;AAE5D,IAAI,GAAG,GAAwB,IAAI,CAAC;AAEpC,SAAS,SAAS;IAChB,IAAI,CAAC,EAAE,CAAC,UAAU,CAAC,WAAW,CAAC,EAAE,CAAC;QAChC,EAAE,CAAC,SAAS,CAAC,WAAW,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IACjD,CAAC;AACH,CAAC;AAED,MAAM,UAAU,KAAK;IACnB,IAAI,GAAG;QAAE,OAAO,GAAG,CAAC;IACpB,SAAS,EAAE,CAAC;IACZ,MAAM,EAAE,GAAG,IAAI,YAAY,CAAC,OAAO,CAAC,CAAC;IACrC,EAAE,CAAC,IAAI,CAAC,4BAA4B,CAAC,CAAC;IACtC,EAAE,CAAC,IAAI,CAAC,8BAA8B,CAAC,CAAC;IACxC,EAAE,CAAC,IAAI,CAAC,2BAA2B,CAAC,CAAC;IACrC,6EAA6E;IAC7E,6EAA6E;IAC7E,EAAE,CAAC,IAAI,CAAC,6BAA6B,CAAC,CAAC;IACvC,4EAA4E;IAC5E,2EAA2E;IAC3E,OAAO,CAAC,EAAE,CAAC,CAAC;IACZ,GAAG,GAAG,EAAE,CAAC;IACT,OAAO,EAAE,CAAC;AACZ,CAAC;AAED,SAAS,YAAY,CAAC,EAAgB,EAAE,KAAa,EAAE,MAAc;IACnE,MAAM,IAAI,GAAG,EAAE,CAAC,OAAO,CAAC,qBAAqB,KAAK,GAAG,CAAC,CAAC,GAAG,EAA6B,CAAC;IACxF,OAAO,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,MAAM,CAAC,CAAC;AAC7C,CAAC;AAED,SAAS,OAAO,CAAC,EAAgB;IAC/B,6EAA6E;IAC7E,4EAA4E;IAC5E,yDAAyD;IACzD,EAAE,CAAC,IAAI,CAAC,kBAAkB,CAAC,CAAC;IAC5B,IAAI,CAAC;QACH,YAAY,CAAC,EAAE,CAAC,CAAC;QACjB,EAAE,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;IACrB,CAAC;IAAC,OAAO,CAAC,EAAE,CAAC;QACX,IAAI,CAAC;YACH,EAAE,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC;QACvB,CAAC;QAAC,MAAM,CAAC;YACP,gCAAgC;QAClC,CAAC;QACD,MAAM,CAAC,CAAC;IACV,CAAC;AACH,CAAC;AAED,SAAS,YAAY,CAAC,EAAgB;IACpC,EAAE,CAAC,IAAI,CAAC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4CP,CAAC,CAAC;IAEH,2EAA2E;IAC3E,IAAI,CAAC,YAAY,CAAC,EAAE,EAAE,WAAW,EAAE,cAAc,CAAC,EAAE,CAAC;QACnD,EAAE,CAAC,IAAI,CAAC,qDAAqD,CAAC,CAAC;IACjE,CAAC;IACD,EAAE,CAAC,IAAI,CACL,yHAAyH,CAC1H,CAAC;IAEF,sEAAsE;IACtE,yEAAyE;IACzE,4EAA4E;IAC5E,8EAA8E;IAC9E,MAAM,MAAM,GAAG,EAAE;SACd,OAAO,CAAC,4EAA4E,CAAC;SACrF,GAAG,EAAkC,CAAC;IACzC,IAAI,MAAM,EAAE,CAAC;QACX,8EAA8E;QAC9E,IAAI,CAAC,MAAM,CAAC,GAAI,CAAC,QAAQ,CAAC,SAAS,CAAC;YAAE,UAAU,CAAC,EAAE,CAAC,CAAC;IACvD,CAAC;SAAM,CAAC;QACN,uEAAuE;QACvE,8EAA8E;QAC9E,qEAAqE;QACrE,UAAU,CAAC,EAAE,CAAC,CAAC;IACjB,CAAC;AACH,CAAC;AAED,6CAA6C;AAC7C,SAAS,UAAU,CAAC,EAAgB;IAClC,EAAE,CAAC,IAAI,CAAC,kCAAkC,CAAC,CAAC;IAC5C,EAAE,CAAC,IAAI,CAAC,4EAA4E,CAAC,CAAC;IACtF,EAAE,CAAC,IAAI,CAAC,2EAA2E,CAAC,CAAC;AACvF,CAAC;AAED,4DAA4D;AAC5D,MAAM,UAAU,WAAW,CAAC,OAAe;IACzC,OAAO,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;AACpE,CAAC;AAED,MAAM,UAAU,KAAK;IACnB,OAAO,UAAU,EAAE,CAAC;AACtB,CAAC;AAED,uEAAuE;AACvE,MAAM,UAAU,UAAU,CAAC,CAAe;IACxC,OAAO,IAAI,UAAU,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,UAAU,EAAE,CAAC,CAAC,UAAU,GAAG,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC;AACnF,CAAC;AAED,wFAAwF;AACxF,MAAM,UAAU,YAAY,CAAC,IAAuB;IAClD,IAAI,CAAC,IAAI,IAAI,IAAI,CAAC,UAAU,KAAK,CAAC,IAAI,IAAI,CAAC,UAAU,GAAG,CAAC,KAAK,CAAC;QAAE,OAAO,IAAI,CAAC;IAC7E,OAAO,IAAI,YAAY,CAAC,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,UAAU,EAAE,IAAI,CAAC,UAAU,GAAG,IAAI,CAAC,UAAU,CAAC,CAAC,CAAC;AACjG,CAAC;AAED,MAAM,UAAU,KAAK;IACnB,OAAO,IAAI,CAAC,GAAG,EAAE,CAAC;AACpB,CAAC;AAED,MAAM,UAAU,OAAO;IACrB,GAAG,EAAE,KAAK,EAAE,CAAC;IACb,GAAG,GAAG,IAAI,CAAC;IACX,SAAS,GAAG,IAAI,CAAC;AACnB,CAAC;AAED,wEAAwE;AACxE,yEAAyE;AACzE,wEAAwE;AAExE,+EAA+E;AAC/E,IAAI,SAAS,GAAkB,IAAI,CAAC;AAEpC,MAAM,UAAU,WAAW;IACzB,IAAI,SAAS,KAAK,IAAI,EAAE,CAAC;QACvB,MAAM,CAAC,GAAG,KAAK,EAAE,CAAC,OAAO,CAAC,gDAAgD,CAAC,CAAC,GAAG,EAElE,CAAC;QACd,SAAS,GAAG,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IACtC,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAC;AAED,MAAM,UAAU,YAAY,CAAC,GAAW,EAAE,KAAa;IACrD,MAAM,EAAE,GAAG,KAAK,EAAE,CAAC;IACnB,EAAE,CAAC,OAAO,CACR,4GAA4G,CAC7G,CAAC,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC;IACnB,EAAE,CAAC,OAAO,CACR,8GAA8G,CAC/G,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;IACb,SAAS,GAAG,GAAG,CAAC;AAClB,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,SAAS,CAAC,GAAiB,EAAE,KAAa;IACxD,MAAM,OAAO,GAAG,WAAW,EAAE,CAAC;IAC9B,IAAI,OAAO,KAAK,CAAC,EAAE,CAAC;QAClB,YAAY,CAAC,GAAG,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC;QAChC,OAAO;IACT,CAAC;IACD,IAAI,OAAO,KAAK,GAAG,CAAC,MAAM,EAAE,CAAC;QAC3B,MAAM,IAAI,KAAK,CACb,2CAA2C,OAAO,YAAY,aAAa,EAAE,KAAK;YAChF,mBAAmB,GAAG,CAAC,MAAM,YAAY,KAAK,KAAK;YACnD,+CAA+C,WAAW,GAAG,CAChE,CAAC;IACJ,CAAC;AACH,CAAC;AAED,MAAM,UAAU,aAAa;IAC3B,MAAM,CAAC,GAAG,KAAK,EAAE,CAAC,OAAO,CAAC,kDAAkD,CAAC,CAAC,GAAG,EAEpE,CAAC;IACd,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,CAAC;AAC1B,CAAC"}

package/dist/env.js

@@ -6,38 +6,58 @@
  * config (MCP clients, CI, shell) always wins. Runs synchronously at import —
  * must be imported before any module that reads `process.env.*` at load time.
  * Supports `#` comments, `export KEY=` prefixes, and single/double-quoted values.
+ *
+ * Only this package's own knobs are loadable: an untrusted repo's `.env` must
+ * not be able to inject arbitrary process.env entries into the host session.
  */
 import * as fs from "fs";
 import * as path from "path";
+/** Prefixes/names this server actually reads. */
+const LOADABLE = /^(RAG_[A-Z0-9_]+|OPENCODE_[A-Z0-9_]+|EMBEDDING_[A-Z0-9_]+|SEARCH_MODE)$/;
+const VALID_KEY = /^[A-Za-z_][A-Za-z0-9_]*$/;
+/** Strip one layer of matching quotes plus any trailing `# comment`. */
+function unquote(value) {
+    const q = value[0];
+    if (q === '"' || q === "'") {
+        const close = value.indexOf(q, 1);
+        if (close > 0) {
+            const rest = value.slice(close + 1).trim();
+            if (rest === "" || rest.startsWith("#"))
+                return value.slice(1, close);
+        }
+    }
+    const hash = value.indexOf(" #");
+    return hash >= 0 ? value.slice(0, hash).trimEnd() : value;
+}
 export function loadDotenv(file) {
     let raw;
     try {
         raw = fs.readFileSync(file, "utf8");
     }
-    catch {
+    catch (e) {
+        if (process.env.RAG_ENV_FILE) {
+            process.stderr.write(`env: cannot read RAG_ENV_FILE ${file} (${e.message})\n`);
+        }
         return;
     }
     for (const line of raw.split(/\r?\n/)) {
         let t = line.trim();
         if (!t || t.startsWith("#"))
             continue;
-        if (t.startsWith("export "))
+        if (t.startsWith("export ") || t.startsWith("export\t"))
             t = t.slice(7).trimStart();
         const eq = t.indexOf("=");
         if (eq <= 0)
             continue;
         const key = t.slice(0, eq).trim();
-        let value = t.slice(eq + 1).trim();
-        // Strip trailing inline comments for unquoted values (e.g. `KEY=val # note`).
-        if (!value.startsWith('"') && !value.startsWith("'")) {
-            const hash = value.indexOf(" #");
-            if (hash >= 0)
-                value = value.slice(0, hash).trimEnd();
-        }
-        if (value.length >= 2 && ((value.startsWith('"') && value.endsWith('"')) || (value.startsWith("'") && value.endsWith("'")))) {
-            value = value.slice(1, -1);
+        if (!VALID_KEY.test(key))
+            continue;
+        if (!LOADABLE.test(key)) {
+            process.stderr.write(`env: ignoring ${key} (not an mcp-rag-memory variable)\n`);
+            continue;
         }
-        if (key && process.env[key] === undefined)
+        const value = unquote(t.slice(eq + 1).trim());
+        if (process.env[key] === undefined)
             process.env[key] = value;
     }
 }