mcp-rag-memory 2.4.0 → 2.7.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

@@ -18,16 +18,20 @@ context **across sessions**.
 - **Context Management** — `remember` facts/decisions/preferences, `recall` them later (score-decayed by staleness), rate by importance, consolidate duplicates, filter by type/tag.
 - **Zero external APIs by default** — local hashing-embedder (1024-dim), built-in `node:sqlite`. Works fully offline. Optional `EMBEDDING_PROVIDER=transformers` for a higher-quality ONNX model.
 - **Safe ingestion** — content-hash deduplication, file size guard (`RAG_MAX_FILE_MB`) and an opt-in path allowlist (`RAG_ALLOWED_DIRS`).
-- **MCP server** — runs on stdio, 19 tools.
+- **MCP server** — runs on stdio, 20 tools.
 
 ## 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**:
@@ -171,24 +190,25 @@ the global config to apply to every project.
 
 Restart opencode after any config change.
 
-## MCP tools (19)
+## MCP tools (20)
 
 | Group | Tool | Purpose |
 |-------|------|---------|
-| System | `system_stats` | DB dir, embedding backend, doc/memory counts |
+| System | `system_stats` | DB dir, embedding backend (incl. what the vector leg measures), store state, doc/memory counts |
+| Maintenance | `rag_reindex` | Re-embed every stored vector for the current model, migrating the store in place |
 | RAG ingest | `rag_ingest_text` | Store text as a knowledge document (dedup-aware) |
 | | `rag_ingest_file` | Store a file (`content_type` auto-detected) |
 | | `rag_ingest_dir` | Recursively ingest source files |
-| RAG query | `rag_search` | Hybrid (BM25 + vector) search, ranked chunks + scores |
+| RAG query | `rag_search` | Hybrid (BM25 + vector) search, ranked chunks + scores; `explain: true` adds per-leg 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
@@ -250,9 +270,45 @@ first winning: the MCP client's `env` block → your shell environment → a
 `.env` and edit, or point at any file via `RAG_ENV_FILE`. The store defaults to
 `.rag-data/` in the working directory.
 
+## Changing the embedding model
+
+The store refuses to mix vector spaces: if `EMBEDDING_MODEL` changes, searching
+with new vectors against old ones would silently blend two spaces and return
+noise. `ensureDim` catches the mismatch and tells you to point `RAG_DB_DIR` at a
+fresh directory and re-ingest — correct, but for a memory store holding months of
+history that is a manual rebuild rather than a migration.
+
+`reindex` does the migration in place. It re-embeds every chunk and memory for the
+currently configured provider/model, then rewrites the store metadata.
+
+```bash
+# 1. install the optional provider
+npm i @huggingface/transformers
+
+# 2. migrate the existing store (documents' text is the source of truth)
+EMBEDDING_PROVIDER=transformers \
+EMBEDDING_MODEL=Xenova/all-MiniLM-L6-v2 \
+npm run cli -- reindex --batch 32
+
+# 3. bake the provider into .env so the server uses it from now on
+```
+
+Or over MCP: the `rag_reindex` tool takes the same `batch_size`.
+
+**How interruption behaves.** A half-migrated store mixes old and new vectors, so
+`reindex` marks the store `reindexing` for its whole duration and every search,
+recall and ingest refuses to run while that flag is set. This is deliberate: the
+failure mode of a partial migration is confident nonsense, and nothing about the
+results would reveal it. If the process dies mid-run, just run `reindex` again —
+the whole store is rewritten from text, so resuming is identical to starting over.
+`system_stats` reports `storeState` and the remediation if you hit this.
+
+Re-running is always safe: embedding is deterministic per model, so `reindex` is
+idempotent. On an empty store it is a no-op that just records the model.
+
 ## Custom slash commands
 
-The 19 MCP tools are called by the AI automatically — but you can also
+The 20 MCP tools are called by the AI automatically — but you can also
 trigger them directly with custom commands. Sources (same name, project
 wins):
 
@@ -279,10 +335,13 @@ 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 -- search "auth bug" --explain              # per-leg vector/keyword/RRF scores
+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
 npm run cli -- sync-latest           # ingest the most recent session
+npm run cli -- reindex --batch 32    # re-embed all vectors for the current model
 npm run clean-db -- --force          # wipe ALL documents + memories (destructive)
 ```
 
@@ -301,16 +360,16 @@ from your curated long-term memories. Three layers:
 
 1. **Plugin (real-time, debounced, cross-workspace).**
    `.opencode/plugin/session-logger.ts` watches message events and, at most
-   once a minute, runs the portable CLI — `npx -y mcp-rag-memory-cli
-   sync-latest --dir <workspace>` — so the session you are typing in lands in
-   the store. Because it invokes the published bin (not this repo's scripts),
-   it works in **any** project that adds the plugin and a `.env` pointing at
-   its store. Disable with `RAG_AUTOSYNC=0`.
+   once a minute, runs the portable CLI — `npx -y -p mcp-rag-memory
+   mcp-rag-memory-cli sync-latest --dir <workspace>` — so the session you are
+   typing in lands in the store. Because it invokes the published package (not
+   this repo's scripts), it works in **any** project that adds the plugin and a
+   `.env` pointing at its store. Disable with `RAG_AUTOSYNC=0`.
 2. **CLI on demand.**
    ```bash
-   npx -y mcp-rag-memory-cli sync-latest --dir "D:/Project/my-app"  # latest session in a workspace
-   npx -y mcp-rag-memory-cli sync-session ses_abc123                # a specific session
-   npx -y mcp-rag-memory-cli sync-logs                              # .session-logs/*.jsonl
+   npx -y -p mcp-rag-memory mcp-rag-memory-cli sync-latest --dir "D:/Project/my-app"  # latest session in a workspace
+   npx -y -p mcp-rag-memory mcp-rag-memory-cli sync-session ses_abc123                # a specific session
+   npx -y -p mcp-rag-memory mcp-rag-memory-cli sync-logs                              # .session-logs/*.jsonl
    ```
 3. **MCP tool.** `rag_sync_session` exposes the same logic over MCP:
    `{ "session_id": "..." }` or `{ "directory": "..." }` for the latest.
@@ -318,7 +377,8 @@ from your curated long-term memories. Three layers:
 > Honest scope note: the **plugin** only ships with this repo out of the box,
 > but it is a plain node script — copy it into any workspace (and give that
 > project an `.env`) and auto-save just works, since it shells out to the
-> published `mcp-rag-memory-cli` via npx. Without a plugin, auto-save is
+> published CLI bin (`mcp-rag-memory-cli`, inside the `mcp-rag-memory` package)
+> via npx. Without a plugin, auto-save is
 > "manual": run layer 2 or call layer 3 whenever you want a session ingested.
 
 How it works: sessions are read from opencode's own DB
@@ -338,14 +398,74 @@ The plugin needs an opencode restart to take effect.
 ## Performance & limits
 
 - **Search is brute-force cosine / FTS5 over every chunk**: `O(N)` per query
-  (exact, deterministic — good for a personal store of thousands of chunks).
-  ANN / HNSW indexing is planned scope (v3) for 100k+ chunks.
+    (exact, deterministic — good for a personal store of thousands of chunks).
+    ANN / HNSW indexing is planned scope (v3) for 100k+ chunks.
+- **The vector cache holds every vector in RAM**, uncapped and complete. Truncating
+    it would silently change which documents are findable, so the cache stays whole
+    and the server warns instead: 8 KB per row at the default 1024 dims, so 100k
+    chunks is roughly 800 MB. Tune the warning threshold with
+    `RAG_VECTOR_CACHE_WARN_MB` (default 256). Beyond a few hundred thousand chunks,
+    expect to prune rather than scale.
 - Keyword leg uses the FTS5 **trigram** tokenizer, so CJK text and
   Indonesian-style substring/inflection matching work without extra config.
   Consequence: keyword terms of **≤ 2 characters are skipped** (trigram needs
   3); the vector leg still covers them.
 - Vector embeddings are local hash-based (no external APIs, ~0 cost, offline).
-  They are tuned for short-phrase similarity, not full-document semantics.
+    They are tuned for short-phrase similarity, not full-document semantics.
+
+### What the vector leg actually measures
+
+This matters more than it sounds, so the server states it explicitly in
+`system_stats` (`embedding.vectorLeg`) rather than calling everything "semantic".
+
+| Provider | `vectorLeg` | Meaning |
+|---|---|---|
+| `local` (default) | `lexical` | Hashes character 1/2/3-grams into 1024 buckets. Scores **lexical and sub-word overlap**, not meaning. |
+| `transformers` | `semantic` | Real sentence embeddings from `EMBEDDING_MODEL`. Captures meaning. |
+
+Consequence for the default: `"cara fix login"` and `"masalah autentikasi"`
+share almost no n-grams, so the **vector** leg scores near zero even though they
+mean the same thing. Retrieval still works because the **FTS5 trigram** leg
+carries the query, and because the local embedder does respond to shared substrings
+and character shapes. What you should not expect from the default is
+paraphrase-level recall — restating a concept with different vocabulary is the
+known blind spot.
+
+To get true semantic recall, install the optional dependency and migrate in place:
+
+```bash
+npm i @huggingface/transformers
+EMBEDDING_PROVIDER=transformers EMBEDDING_MODEL=Xenova/all-MiniLM-L6-v2 npm run cli -- reindex
+```
+
+`reindex` rewrites every stored vector for the new model. See
+[Changing the embedding model](#changing-the-embedding-model).
+
+### Debugging a bad search
+
+`rag_search` accepts `explain: true` (CLI: `--explain`), which attaches the
+per-leg diagnostics to every hit:
+
+```jsonc
+{
+  "score": 0.71,          // final relevance, 0..1 — what min_score filters on
+  "legs": ["vector", "keyword"],
+  "explain": {
+    "vectorScore": 0.63,  // cosine similarity, -1..1
+    "keywordScore": 1.0,  // BM25 normalised against the best hit, 0..1
+    "rrfScore": 0.0246,   // fused contribution that decided the order
+    "vectorRank": 0,
+    "keywordRank": 2
+  }
+}
+```
+
+| Symptom | Likely cause |
+|---|---|
+| `legs: ["keyword"]`, no `vectorScore` | Only the trigram leg matched. Expected for paraphrase queries under the `local` provider. |
+| `legs: ["vector"]` with a low `vectorScore` | Lexical overlap only. Rephrase, or switch provider. |
+| `keywordScore` near 0 for every hit | The query terms are absent from the corpus, or under 3 characters. |
+| No hits at all | Lower `min_score`, or set `SEARCH_MODE=keyword` to isolate which leg is failing. |
 
 ## Architecture
 
@@ -360,7 +480,7 @@ src/
 │   └── pipeline.ts         async ingest/search/retrieve, dedup, guards, doc mgmt
 ├── session/transcript.ts   read opencode sessions (global+local DB), ingest inputs
 ├── memory/memory.ts        remember / recall / consolidate + decay + prune
-├── mcp/rag-server.ts       MCP server (19 tools, stdio, npm bin)
+├── mcp/rag-server.ts       MCP server (20 tools, stdio, npm bin)
 ├── cli.ts                  CLI playground (incl. sync-session / sync-latest / sync-logs)
 └── test/test-all.ts        full test suite (unit + MCP round-trip)
 ```
@@ -378,14 +498,25 @@ Data lives in `.rag-data/rag.sqlite` (git-ignored).
 | `RAG_MAX_FILE_MB` | `10` | Reject files larger than this |
 | `RAG_ALLOWED_DIRS` | *(unset = anywhere)* | Semicolon/pipe/comma-separated allowed ingest roots |
 | `RAG_MEMORY_HALF_LIFE_DAYS` | `14` | Recall score decay half-life |
+| `RAG_DEDUP_MAX_VECTORS` | `500` | Above this many memories `consolidate` skips near-duplicate detection and reports `skippedDedup`. Raise it on a dedicated server (the pass is O(n²)) |
+| `RAG_VECTOR_CACHE_WARN_MB` | `256` | Warn when the in-memory vector cache exceeds this size |
 | `RAG_PRUNE` | `0` | Set `1` to allow `consolidate` to delete non-essential memories |
 | `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
 
@@ -488,8 +619,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 20 tools keep working, you just have
+to call `rag_sync_session` yourself.
 
 ---
 

package/dist/cli.js

@@ -24,6 +24,7 @@
  *   memory-stats
  *   mem-context  <topic>
  *   stats                                       Everything
+ *   reindex    [--batch N]                      Re-embed all vectors for the current model
  *   sessions                                    List opencode sessions (recent first)
  *   sync-session <sessionId> [--limit N]        Ingest a session's user inputs to RAG
  *   sync-latest   [--limit N] [--dir PATH]      Ingest the most recent session (workspace-aware)
@@ -34,6 +35,7 @@ import "./env.js";
 import { ingestText, ingestFile, ingestDirectory, searchDocs, retrieve, listDocuments, deleteDocument, documentStats } from "./rag/pipeline.js";
 import { remember, recall, listMemories, getMemory, updateMemory, forget, consolidate, memoryStats, contextPrompt, MEMORY_TYPES } from "./memory/memory.js";
 import { ingestSession, ingestJsonlFile, ingestLogDir, ingestLatest, listOpenCodeSessions } from "./session/transcript.js";
+import { reindex } from "./rag/reindex.js";
 import { closeDB, STORAGE_DIR } from "./db/database.js";
 import * as fs from "fs";
 async function main() {
@@ -47,100 +49,125 @@ async function main() {
     closeDB();
 }
 function helpText() {
-    return `Commands: ingest-text|ingest-file|ingest-dir|search|retrieve|docs|doc-stats|rm-doc|remember|recall|memory-list|memory-get|memory-update|forget|consolidate|memory-stats|mem-context|stats|sessions|sync-session|sync-latest|sync-logs|ingest-jsonl`;
+    return `Commands: ingest-text|ingest-file|ingest-dir|search|retrieve|docs|doc-stats|rm-doc|remember|recall|memory-list|memory-get|memory-update|forget|consolidate|memory-stats|mem-context|stats|reindex|sessions|sync-session|sync-latest|sync-logs|ingest-jsonl`;
 }
 function assertMemoryType(type) {
     if (!MEMORY_TYPES.includes(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,
-                });
+                }, parsed.opts.explain !== undefined);
                 break;
             }
             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 +175,30 @@ 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 "reindex": {
+                const parsed = parseOpts(args);
+                out = await reindex({
+                    batchSize: toNum(parsed.opts.batch, undefined),
+                    onProgress: (p) => {
+                        if (p.total > 0) {
+                            process.stderr.write(`reindex ${p.phase}: ${p.done}/${p.total}\r`);
+                        }
+                    },
+                });
+                process.stderr.write("\n");
+                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 +206,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 +223,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 +233,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 +275,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;
@@ -19,4 +19,12 @@ export declare function setEmbedMeta(dim: number, model: string): void;
  */
 export declare function ensureDim(vec: Float64Array, model: string): void;
 export declare function getEmbedModel(): string;
+/**
+ * `embed_state` is '' (or 'ready') for a coherent store and 'reindexing' while a
+ * vector-space migration is in flight.
+ */
+export declare function getEmbedState(): string;
+export declare function setEmbedState(state: string): void;
+/** Throws when the store is mid-reindex. Called from ensureDim, the shared gate. */
+export declare function assertEmbedStateReady(): void;
 //# sourceMappingURL=database.d.ts.map

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,CA0BpC;AA+GD,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,CAWpC;AAED,wBAAgB,YAAY,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,QAWtD;AAED;;;GAGG;AACH,wBAAgB,SAAS,CAAC,GAAG,EAAE,YAAY,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI,CA6BhE;AAED,wBAAgB,aAAa,IAAI,MAAM,CAKtC;AAED;;;GAGG;AACH,wBAAgB,aAAa,IAAI,MAAM,CAKtC;AAED,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAIjD;AAED,oFAAoF;AACpF,wBAAgB,qBAAqB,IAAI,IAAI,CAS5C"}