rag-memory-epf-mcp 3.5.2 → 3.6.0

package/docs/UPDATING.md

@@ -0,0 +1,121 @@
+# Updating rag-memory-epf-mcp
+
+Runbook for version-update reliability (introduced in v3.6).
+
+## Which version is actually running?
+
+`@latest` in your MCP config does **not** guarantee the newest version. Three
+independent reasons:
+
+1. **Process lifetime** — MCP servers are spawned when the CLI starts. A new
+   version is only picked up after you restart the CLI (or reconnect via
+   `/mcp`). Editing config mid-session has no effect on the running server.
+2. **npx cache fallback** — if the npm registry is unreachable, npx runs the
+   cached copy.
+3. **dist-tag re-resolution caching** — npx may reuse a previously resolved
+   `@latest` for a while (known npm CLI behavior family).
+
+**Check what is actually running** (v3.6+):
+
+- Startup banner on stderr: `rag-memory-epf-mcp vX.Y.Z | node vN | model ... | cache ... | db ...`
+- `getKnowledgeGraphStats` → `server.version`, plus `server.model_state`,
+  `server.reconciliation_state`, and provenance `coverage`.
+
+**Deterministic updates**: `npm i -g rag-memory-epf-mcp` and point the config
+launcher at the `rag-memory-mcp` bin directly (the framework bootstrap
+preserves this customization).
+
+## Runtime requirements
+
+- Node **>= 24** (`engines` + a runtime check at boot). Limitation: on very old
+  Node the native imports (better-sqlite3 etc.) may fail before our version
+  check prints its message.
+- Embedding dims are fixed at 1024 (bge-m3). Other dims fail fast by design.
+
+## The model cache moved in v3.6 (and why that matters)
+
+- **Pre-3.6**: the bge-m3 model (~1.2GB) was cached *inside the package
+  directory*, which lives inside the npx version slot → **every engine version
+  bump re-downloaded the model**.
+- **v3.6+**: the model lives in a version-independent user cache:
+  `RAG_MEMORY_MODEL_CACHE_DIR` → `$XDG_CACHE_HOME/rag-memory-epf-mcp` →
+  macOS `~/Library/Caches/rag-memory-epf-mcp` / Linux `~/.cache/…` /
+  Windows `%LOCALAPPDATA%\rag-memory-epf-mcp`.
+- First v3.6 boot downloads once into the new location (in the background —
+  the server is usable immediately in FTS mode). Old package-internal caches
+  are not migrated; they disappear with their npx slots.
+- **Cleaning `~/.npm/_npx` no longer touches the model cache.** Do not delete
+  the cache directory above unless you intend to re-download.
+
+## Boot modes (v3.6)
+
+`RAG_MEMORY_EMBEDDINGS` = `lazy` (default) | `eager` | `off`
+
+- `lazy` — MCP connects instantly; FTS5 search, graph and CRUD work from the
+  first second. The model loads/downloads in the background; hybrid search
+  turns on automatically (search responses carry `search_mode` /
+  `degradation_reason` so you can see why vector search is off).
+- `eager` — pre-3.6 behavior: boot waits for the model (and provenance
+  reconciliation) before connecting.
+- `off` — never loads the model. Zero download, FTS5-only, permanently.
+  Responses report `embedding_status: "disabled"` (not `"queued"` — nothing
+  will backfill in this mode).
+
+`RAG_MEMORY_TRUST_LEGACY_VECTORS=1` — only relevant if you run a custom
+`EMBEDDING_MODEL`: v3.6 refuses to grandfather pre-existing vectors under a
+custom model config unless you opt in (they are re-embedded instead).
+
+If you EVER ran a custom `EMBEDDING_MODEL` against a DB and later switched
+back to the default, the stored vectors cannot be attributed reliably. Run
+`embedAllEntities` and re-sync your documents to rebuild them.
+
+## Rollback caveats
+
+- v3.6 applies schema migration 12 (provenance columns/tables) to each project
+  DB on first boot. Older engine versions ignore the new columns — but they
+  also do not maintain them.
+- **Never run a pre-3.6 and a v3.6 server against the same project DB at the
+  same time.** Restart per project, one at a time.
+
+## Fleet rollout
+
+- Roll out machine-by-machine, restarting CLIs sequentially (the shared model
+  cache uses a cross-process download lock; sequential restarts avoid lock
+  contention entirely).
+- Concurrent servers: measured 2026-07-18 on the reference machine — 7 idle
+  MCP server processes coexist (idle servers swap out to a few MB RSS). Each
+  server that actually loads the model needs bge-m3 fp16 resident memory
+  (~1.5–2GB while active). Keep concurrently *model-active* servers to a
+  handful; sessions that don't need semantic search should run
+  `RAG_MEMORY_EMBEDDINGS=off`. Note that **lazy mode still starts the model
+  load in the background right after connect** (so hybrid search becomes
+  available without any tool call) — `off` is the only zero-load mode. When
+  restarting many CLIs at once, the shared cache download happens once (lock),
+  but each process that finishes loading holds its own model memory.
+
+## Shutdown semantics
+
+SIGTERM/SIGINT close the MCP transport, settle in-flight work (bounded, 5s),
+close the database cleanly, and exit naturally. One documented exception: if a
+model download/load is still pending after the settle deadline (the fetch
+cannot be aborted through transformers.js), the process performs a bounded
+exit **after** the database is closed — data is never at risk, but if the load
+happened to be inside native session construction you may see an abrupt
+runtime message on termination.
+
+**Stuck download lock recovery**: if a waiter times out it reports the lock
+path and holder pid (e.g. `.download-<key>.lock`). Verify the holder process
+is genuinely gone or hung (`ps -p <pid>`), then remove the lock file manually;
+the next start becomes a clean download owner.
+
+## v3.6 breaking response changes
+
+1. `hybridSearch` returns an envelope: `{results, search_mode, model_state,
+   coverage, degradation_reason?}` (per-item `search_mode` removed).
+2. `deleteObservations` returns `{results: [{entityName, deleted,
+   embedding_status}], total_deleted}` instead of a success string.
+
+All other tools are additive (`embedding_status`, `endpoint_embedding_status`,
+stats `server` block). Error responses now set `isError: true`; embedding-gate
+errors are structured: `{code: "MODEL_NOT_READY" | "EMBEDDINGS_DISABLED",
+state, retry_after_ms?, message}`.

package/package.json

@@ -1,6 +1,9 @@
 {
   "name": "rag-memory-epf-mcp",
-  "version": "3.5.2",
+  "version": "3.6.0",
+  "engines": {
+    "node": ">=24"
+  },
   "description": "Project-local RAG memory MCP server — knowledge graph + multilingual vector + FTS5 in a single SQLite file. Per-project isolation, 30 MCP tools, codepoint-safe chunking (Korean/CJK/emoji).",
   "keywords": [
     "mcp",
@@ -34,14 +37,15 @@
     "rag-memory-mcp": "dist/index.js"
   },
   "files": [
-    "dist"
+    "dist",
+    "docs/UPDATING.md"
   ],
   "scripts": {
     "build": "tsc && shx chmod +x dist/*.js",
     "prepare": "npm run build",
     "watch": "tsc --watch",
     "verify:invariants": "node test/chunk-invariants.test.mjs",
-    "verify:engine": "node test/engine-smoke.test.mjs && node test/launch-smoke.test.mjs && node test/sync-atomicity.test.mjs && node test/dedup.test.mjs && node test/search-degradation.test.mjs && node test/entity-embed-cap.test.mjs",
+    "verify:engine": "node test/engine-smoke.test.mjs && node test/launch-smoke.test.mjs && node test/sync-atomicity.test.mjs && node test/dedup.test.mjs && node test/search-degradation.test.mjs && node test/entity-embed-cap.test.mjs && node test/migration12.test.mjs && node test/model-cache.test.mjs && node test/embedding-gate.test.mjs && node test/lazy-boot.test.mjs && node test/reconciliation.test.mjs && node test/backfill.test.mjs && node test/fts-query.test.mjs && node test/search-contracts.test.mjs && node test/tool-contracts.test.mjs && node test/bounded-exit.test.mjs",
     "test": "npm run build && npm run verify:invariants && npm run verify:engine",
     "prepublishOnly": "npm run build && npm run verify:invariants && npm run verify:engine"
   },
@@ -60,7 +64,7 @@
   },
   "devDependencies": {
     "@types/better-sqlite3": "^7.6.12",
-    "@types/node": "^22",
+    "@types/node": "^24",
     "shx": "^0.3.4",
     "typescript": "^5.6.2"
   }