rag-memory-epf-mcp 6.3.0 → 6.3.1

package/README.md

@@ -154,6 +154,22 @@ storeDocument(id, content, metadata)
 
 ## Changelog
 
+### v6.3.1
+
+- **Changed — the engine empties the WAL while it is idle.** It runs `wal_checkpoint(TRUNCATE)` itself:
+  on a 1 s tick whenever the `-wal` file has bytes in it, ~200 ms after a tool call, first thing in the
+  signal handler, and before closing. SQLite folds the WAL only when the *last* connection closes and
+  only if that close gets to run; with several engines on one file, or a host that kills the engine
+  (measured: codex-cli 0.155.1 sends SIGTERM and SIGKILLs ~185 ms later; Windows terminates children
+  outright), frames stayed in the WAL — on 6.3.0 a fresh database sat at 4 KB main + 663 KB WAL for as
+  long as the engine ran. In a cloud-synced folder such a WAL can be replayed onto a main file written
+  by another machine. A write made in the last ~1 s before a hard kill can still be in the WAL; a 0-byte
+  `-wal` and a `-shm` left behind by a hard kill are harmless. Running engines on two machines against
+  the same synced file at the same time is still unsafe.
+- **Changed — SIGHUP and SIGBREAK shut the engine down cleanly.** Closing the terminal or multiplexer
+  pane used to kill the process by default signal action, before the database was closed.
+- No tool, argument, return shape or schema changed.
+
 ### v6.3.0 (2026-09-16)
 
 - **Changed — a relative `DB_FILE_PATH` now resolves against the server's working directory.** It used

package/dist/index.d.ts

@@ -101,6 +101,11 @@ export declare class RAGKnowledgeGraphManager {
             description: string;
         }>;
     }>;
+    checkpointWal(): boolean;
+    private walTimer;
+    private walSoon;
+    startWalKeeper(tickMs?: number): void;
+    noteActivity(delayMs?: number): void;
     cleanup(): void;
     private _timestampObservation;
     createEntities(entities: Array<Entity & {

package/dist/index.js

@@ -593,13 +593,78 @@ export class RAGKnowledgeGraphManager {
             }))
         };
     }
+    // Fold the WAL into the main file and empty it. Returns true when the WAL holds no
+    // frames afterwards.
+    //
+    // Why the engine does this itself instead of leaving it to SQLite: SQLite folds the WAL
+    // only when the LAST connection closes, and only if that close gets to run. Neither holds
+    // here — several engines keep the same file open (one per CLI), and some hosts end the
+    // engine without letting it finish (codex-cli 0.155.1, measured: SIGTERM, then SIGKILL
+    // ~185 ms later; on Windows a child is simply terminated). A WAL with frames that outlives
+    // its process is replayed at the next open against whatever main file is there by then, and
+    // in a cloud-synced folder that can be a main file written by another machine. SQLite does
+    // not check that a WAL belongs to the main file next to it. That corrupted a live database
+    // twice. So the invariant is kept continuously: while idle, the WAL is empty.
+    //
+    // TRUNCATE, not PASSIVE: PASSIVE copies the frames into the main file but leaves them in
+    // the WAL, still valid, still replayable onto a foreign main file.
+    // busy_timeout is dropped to 0 around the call: TRUNCATE runs the busy handler, and a 5 s
+    // stall inside a signal handler or a timer tick is worse than retrying on the next tick.
+    checkpointWal() {
+        if (!this.db)
+            return true;
+        try {
+            const st = fsSync.statSync(DB_FILE_PATH + '-wal', { throwIfNoEntry: false });
+            if (!st || st.size === 0)
+                return true;
+            this.db.pragma('busy_timeout = 0');
+            try {
+                const r = this.db.pragma('wal_checkpoint(TRUNCATE)');
+                return r?.[0]?.busy === 0;
+            }
+            finally {
+                this.db.pragma('busy_timeout = 5000');
+            }
+        }
+        catch {
+            return false; // inside a transaction, or the file is locked — the next tick retries
+        }
+    }
+    walTimer = null;
+    walSoon = null;
+    // Every write path ends up here without having to be listed: the periodic tick looks at
+    // the size of the -wal file, not at which tool ran, so background writers (reconciliation,
+    // backfill) are covered as well. noteActivity() only shortens the wait after a tool call.
+    startWalKeeper(tickMs = 1000) {
+        if (this.walTimer)
+            return;
+        this.walTimer = setInterval(() => { this.checkpointWal(); }, tickMs);
+        this.walTimer.unref();
+    }
+    noteActivity(delayMs = 200) {
+        if (this.walSoon)
+            return;
+        this.walSoon = setTimeout(() => { this.walSoon = null; this.checkpointWal(); }, delayMs);
+        this.walSoon.unref();
+    }
     cleanup() {
+        if (this.walTimer) {
+            clearInterval(this.walTimer);
+            this.walTimer = null;
+        }
+        if (this.walSoon) {
+            clearTimeout(this.walSoon);
+            this.walSoon = null;
+        }
         if (this.encoding) {
             this.encoding.free();
             this.encoding = null;
         }
         this.embeddingCache.clear();
         if (this.db) {
+            // close() folds the WAL only for the last connection; with other engines attached it
+            // would leave every frame behind.
+            this.checkpointWal();
             this.db.close();
             this.db = null;
         }
@@ -4061,6 +4126,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
     try {
         // Validate arguments using our structured schema
         const validatedArgs = validateToolArgs(name, args);
+        ragKgManager.noteActivity(); // fold the WAL shortly after this call, whatever it wrote
         switch (name) {
             // Original MCP tools
             case "createEntities":
@@ -4235,6 +4301,9 @@ async function main() {
             if (shuttingDown)
                 return;
             shuttingDown = true;
+            // Synchronously, before anything is awaited: a host may SIGKILL before the settle
+            // sequence below completes (codex: ~185 ms after SIGTERM).
+            ragKgManager.checkpointWal();
             void (async () => {
                 try {
                     await server.close();
@@ -4250,6 +4319,13 @@ async function main() {
         };
         process.on('SIGINT', shutdown);
         process.on('SIGTERM', shutdown);
+        // SIGHUP = the terminal or multiplexer pane was closed. Without a handler the default
+        // action kills the process before 'exit' listeners run, so the database is never closed.
+        // On Windows, Node raises SIGHUP when the console window is closed and SIGBREAK on
+        // Ctrl+Break; registering them is harmless where they never fire.
+        process.on('SIGHUP', shutdown);
+        process.on('SIGBREAK', shutdown);
+        ragKgManager.startWalKeeper();
         process.on('exit', () => { try {
             ragKgManager.cleanup();
         }

package/package.json

@@ -1,6 +1,6 @@
 {
  "name": "rag-memory-epf-mcp",
- "version": "6.3.0",
+ "version": "6.3.1",
  "engines": {
   "node": ">=24"
  },
@@ -45,7 +45,7 @@
   "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 && 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 && node test/observation-schema.test.mjs && node test/search-graph-default.test.mjs && node test/observation-migration.test.mjs && node test/observation-lifecycle.test.mjs && node test/observation-contracts.test.mjs && node test/observation-search.test.mjs && node test/observation-cascade.test.mjs && node test/observation-realdata.test.mjs && node test/chunker-c.test.mjs && node test/migration14.test.mjs && node test/chunk-params-validation.test.mjs && node test/vector-reuse.test.mjs && node test/entity-range-linking.test.mjs && node test/alias-link-gate.test.mjs && node test/entity-name-boundary.test.mjs && node test/stats-chunking.test.mjs && node test/migration14-realdata.test.mjs && node test/migration14-realdata-sync.test.mjs && node test/search-summaries-off.test.mjs && node test/document-return-contracts.test.mjs && node test/observation-date-prefix.test.mjs && node test/delete-entities-cascade.test.mjs && node test/delete-entities-kg-hygiene.test.mjs && node test/backup-publish-portable.test.mjs && node test/graph-context-explain.test.mjs && node test/eval-graph-role-libs.test.mjs && node test/eval-graph-role-t5b.test.mjs && node --test test/eval-graph-role-t8-fix.test.mjs && node --test test/eval-graph-role-t7-upstream.test.mjs && node --test test/eval-graph-role-t11-decision.test.mjs && node --test test/eval-graph-role-prereq-fix.test.mjs && node test/db-path.test.mjs && node test/mmap-option.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 && node test/observation-schema.test.mjs && node test/search-graph-default.test.mjs && node test/observation-migration.test.mjs && node test/observation-lifecycle.test.mjs && node test/observation-contracts.test.mjs && node test/observation-search.test.mjs && node test/observation-cascade.test.mjs && node test/observation-realdata.test.mjs && node test/chunker-c.test.mjs && node test/migration14.test.mjs && node test/chunk-params-validation.test.mjs && node test/vector-reuse.test.mjs && node test/entity-range-linking.test.mjs && node test/alias-link-gate.test.mjs && node test/entity-name-boundary.test.mjs && node test/stats-chunking.test.mjs && node test/migration14-realdata.test.mjs && node test/migration14-realdata-sync.test.mjs && node test/search-summaries-off.test.mjs && node test/document-return-contracts.test.mjs && node test/observation-date-prefix.test.mjs && node test/delete-entities-cascade.test.mjs && node test/delete-entities-kg-hygiene.test.mjs && node test/backup-publish-portable.test.mjs && node test/graph-context-explain.test.mjs && node test/eval-graph-role-libs.test.mjs && node test/eval-graph-role-t5b.test.mjs && node --test test/eval-graph-role-t8-fix.test.mjs && node --test test/eval-graph-role-t7-upstream.test.mjs && node --test test/eval-graph-role-t11-decision.test.mjs && node --test test/eval-graph-role-prereq-fix.test.mjs && node test/db-path.test.mjs && node test/mmap-option.test.mjs && node test/wal-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"
  },