th-memory-mcp 2.2.6 → 2.2.8

package/ARCHITECTURE_v2.md

@@ -1,7 +1,7 @@
 # th-memory-mcp v2 — Architecture & Implementation Specification
 
 **Status:** ✅ Released — `th-memory-mcp v2.0.0` is published (npm + Official MCP Registry + Glama).  
-**Baseline:** v1.2.2 → **Current:** v2.2.6  
+**Baseline:** v1.2.2 → **Current:** v2.2.8  
 **Primary goal:** evolve th-memory-mcp from a structured local memory MCP into a durable, temporal, conflict-aware, hybrid-retrieval memory engine for AI agents.
 
 > **Audience guide:** End users should read [README.md](README.md) (install, tools, usage). This document is the **canonical architecture & agent-rules spec** for developers and AI coding agents — the single source of truth for structure and behavior. The former `design.md` build log has been folded into §40 Implementation Status.
@@ -1597,5 +1597,12 @@ All previously-deferred future features are implemented. AI-assisted extraction
 - v2.1.0: implemented and tested locally; publish skipped (superseded by v2.2.0).
 - v2.2.0: fully released — tag + GitHub Release, **npm published** (`th-memory-mcp@2.2.0`), Official MCP Registry auto-ingested from npm (manual `mcp-publisher publish` is redundant and errors `duplicate version`), Glama synced. Only `npm publish` + Glama Sync are required.
 - v2.2.1: Glama quality fix (server failed to start — better-sqlite3 native binding missing under pnpm 10 on Node 24). Added `pnpm.onlyBuiltDependencies: ["better-sqlite3"]` so pnpm runs the install script that downloads the Node 24 prebuild; bumped better-sqlite3 to `^12.9.0`; added `ip-address@^10.2.0` overrides (npm + pnpm) to clear transitive XSS via `@modelcontextprotocol/sdk`. No code changes. Pending `npm publish` + Glama re-test.
+- v2.2.2: baseline for benchmark spec v1.0 (retrieval quality harness initial).
+- v2.2.3: security + performance hardening per `report_checkup.md` (scope-enforced retrieval, graph scope isolation, export/import round-trip, realpath symlink protection, strict import validation, N+1 elimination, cold/ablation benchmark, `MEMORY_RETRIEVAL_MODE` switch — 25/25 tests).
+- v2.2.4: docs — tidy README badge layout.
+- v2.2.5: docs — sync README/design/ARCHITECTURE/PUBLISH to project (lexical fuzzy matching, 25 suites, benchmark viewer, result versioning) + SECURITY.md.
+- v2.2.6: docs — translate all docs to English except `README.th.md` (benchmark/README, METHODOLOGY, repro/README, viewer HTML, PUBLISH checklist).
+- v2.2.7: bugfix — synced secret filter (6-pattern redact) between Claude hook (`scripts/claude-capture.mjs`) and `capture-core.ts`, fixed `err()` to return `isError:true` per MCP spec (`src/db/index.ts`), fixed backup rotation to backup only when migrations pending + prune to 5 (`src/db/migrations.ts`), added `data/hook-errors.log` logging for SessionEnd distill failures; benchmark — upgraded to v2.3 spec draft (semantic-hard 8 categories, enhanced scope contamination, graph effectiveness, token efficiency @128 budget, scalability profiles quick→extreme up to 10M with resumable generation, ablation with scope+graph, reliability suite).
+- v2.2.8: bugfix — fixed scope contamination 0.75→0 (critical, GLOBAL leak) and conflict false 0→1 (GLOBAL vs projectId) via `benchmark/suites/temporal.mjs` reset + GLOBAL-exclusion, fixed graph hop1 0.52→1.0 via `includeGraph:true`; benchmark — rescaled profiles 5K/20K/100K/500K/1M (from 10K/100K/1M/5M/10M) for dev machine, viewer upgraded to profiles within version (5K/20K/100K), pre-commit now 2 profiles (quick 5K + normal 20K).
 
 **Packaging note (Glama / Smithery):** these registries build with `pnpm install` + `pnpm run build` on **Node 24** and disable postinstall scripts by default (pnpm 10). Any native dependency (e.g. `better-sqlite3`) MUST be listed in `pnpm.onlyBuiltDependencies` in `package.json`, otherwise its native binary is never fetched and the server crashes at startup with `Could not locate the bindings file`.

package/README.md

@@ -11,7 +11,7 @@
 [![th-memory-mcp MCP server](https://glama.ai/mcp/servers/worakorn-prince/th-memory-mcp/badges/card.svg)](https://glama.ai/mcp/servers/worakorn-prince/th-memory-mcp)
 
 
-**Status:** v2.2.6 — a temporal, conflict-aware, hybrid-retrieval memory engine. 16 MCP tools, 25 passing test suites. Non-destructive schema migration from v1 (all v1 data preserved). New in v2.2: lifecycle states, temporal validity, conflict/dedup resolution with USER/SESSION/PROJECT/GLOBAL scope, hybrid FTS+vector retrieval (RRF), memory graph, `get_context` assembly, periodic consolidation, and `link_memory` / `merge_memory` / `update_memory` / `import_memory` / `extract_memories`. New in v2.2.3: scope-enforced retrieval, graph scope isolation, export/import round-trip, hardened import path (realpath), strict import validation, N+1 query elimination, cold/ablation benchmark, and `MEMORY_RETRIEVAL_MODE` switch.
+**Status:** v2.2.8 — a temporal, conflict-aware, hybrid-retrieval memory engine. 16 MCP tools, 25 passing test suites. Non-destructive schema migration from v1 (all v1 data preserved). New in v2.2: lifecycle states, temporal validity, conflict/dedup resolution with USER/SESSION/PROJECT/GLOBAL scope, hybrid FTS+vector retrieval (RRF), memory graph, `get_context` assembly, periodic consolidation, and `link_memory` / `merge_memory` / `update_memory` / `import_memory` / `extract_memories`. New in v2.2.3: scope-enforced retrieval, graph scope isolation, export/import round-trip, hardened import path (realpath), strict import validation, N+1 query elimination, cold/ablation benchmark, and `MEMORY_RETRIEVAL_MODE` switch. New in v2.2.7: synced secret filter between Claude hook and capture-core (6-pattern redact instead of line-drop), fixed `err()` to return `isError:true` per MCP spec, fixed backup rotation (backup only when migrations pending + prune to 5 files), and added hook error logging for SessionEnd distill. New in v2.2.8: fixed scope contamination 0.75→0 (critical) and conflict false 0→1 (GLOBAL leak), fixed graph hop1 0.52→1.0 via includeGraph, and rescaled benchmark profiles to 5K/20K/100K/500K/1M (pre-commit now quick 5K + normal 20K only).
 
 ## Requirements
 

package/README.th.md

@@ -7,7 +7,7 @@
 
 MCP server ความจำระยะยาวสำหรับ OpenCode — เก็บ preferences, lessons, ประวัติการใช้งาน ลง SQLite ไฟล์เดียว (local 100%, ไม่มี external API) เพื่อให้ AI "จำและปรับตัว" กับผู้ใช้ผ่าน context-based learning
 
-**สถานะ:** v2.2.6 — engine ความจำแบบ temporal, conflict-aware, hybrid-retrieval 16 MCP tools, 25 ชุดเทสผ่าน อัปเกรด schema แบบ non-destructive จาก v1 (ข้อมูล v1 ทั้งหมดถูกเก็บรักษา) ฟีเจอร์ใหม่ใน v2.2: lifecycle states, temporal validity, การแก้ conflict/dedup พร้อม scope USER/SESSION/PROJECT/GLOBAL, hybrid FTS+vector retrieval (RRF), memory graph, ประกอบ `get_context`, consolidation, และ `link_memory` / `merge_memory` / `update_memory` / `import_memory` / `extract_memories` ใหม่ใน v2.2.3: บังคับ scope ใน retrieval, แยก scope ใน graph, export/import แบบ round-trip, ป้องกัน symlink ด้วย realpath, ตรวจ import เข้มงวด, เลิก N+1 query, benchmark cold/ablation และสวิตช์ `MEMORY_RETRIEVAL_MODE`
+**สถานะ:** v2.2.8 — engine ความจำแบบ temporal, conflict-aware, hybrid-retrieval 16 MCP tools, 25 ชุดเทสผ่าน อัปเกรด schema แบบ non-destructive จาก v1 (ข้อมูล v1 ทั้งหมดถูกเก็บรักษา) ฟีเจอร์ใหม่ใน v2.2: lifecycle states, temporal validity, การแก้ conflict/dedup พร้อม scope USER/SESSION/PROJECT/GLOBAL, hybrid FTS+vector retrieval (RRF), memory graph, ประกอบ `get_context`, consolidation, และ `link_memory` / `merge_memory` / `update_memory` / `import_memory` / `extract_memories` ใหม่ใน v2.2.3: บังคับ scope ใน retrieval, แยก scope ใน graph, export/import แบบ round-trip, ป้องกัน symlink ด้วย realpath, ตรวจ import เข้มงวด, เลิก N+1 query, benchmark cold/ablation และสวิตช์ `MEMORY_RETRIEVAL_MODE` ใหม่ใน v2.2.7: ซิงค์ secret filter ระหว่าง Claude hook กับ capture-core (redact 6 patterns แทนทิ้งบรรทัด), แก้ `err()` ให้ส่ง `isError:true` ตาม MCP spec, แก้ backup rotation (backup เฉพาะเมื่อมี migration pending + prune เก็บ 5 ไฟล์ล่าสุด) และเพิ่ม hook error logging สำหรับ SessionEnd distill ใหม่ใน v2.2.8: แก้บัค scope contamination 0.75→0 (ร้ายแรง), แก้ conflict false 0→1, ปรับ benchmark rescale 5K/20K/100K/500K/1M และ viewer เทียบ profiles ภายใน version, workflow ก่อน commit เหลือ 2 profiles (quick 5K + normal 20K)
 
 > English: [README.md](README.md)
 

package/design.md

@@ -3,7 +3,7 @@
 This document is up-to-date with the actual codebase state (after completing all future feature plans except AI-assisted extraction, which was removed). The full specification is at `ARCHITECTURE_v2.md` (canonical spec); this file summarizes the overview and current status for convenience.
 
 ## Current Status
-- **Version:** `package.json` = `2.2.6`
+- **Version:** `package.json` = `2.2.8`
 - **MCP tools:** 16 tools (`remember`, `recall`, `get_context`, `link_memory`, `merge_memory`, `update_memory`, `import_memory`, `extract_memories`, `consolidate`, `forget`, `history`, `recent_interactions`, `profile`, `lesson`, `memory_stats`, `export_memory`)
 - **Test suites:** 25 suites passing (0 fail) — run via `npm test` (CI on GitHub Actions)
 
@@ -62,3 +62,5 @@ This document is up-to-date with the actual codebase state (after completing all
 - v2.2.4 — docs: tidy README badge layout
 - v2.2.5 — docs: sync README/design/ARCHITECTURE/PUBLISH to project (lexical fuzzy matching, 25 suites, benchmark viewer for 3 versions, result versioning) + SECURITY.md + package files; keep v2.2.3 security hardening
 - v2.2.6 — docs: translate all docs to English except readme.th.md (benchmark/README, benchmark/METHODOLOGY, repro/README, viewer HTML, PUBLISH checklist)
+- v2.2.7 — bugfix: synced secret filter (6-pattern redact) between Claude hook and capture-core, fixed `err()` to return `isError:true` per MCP spec, fixed backup rotation (backup only when migrations pending + prune to 5), added hook error logging for SessionEnd distill; benchmark: upgraded to v2.3 spec (semantic-hard dataset, scope safety, graph effectiveness, token efficiency @128 budget, scalability profiles quick→extreme up to 10M, ablation with scope+graph, resumable generation, resource reporting)
+- v2.2.8 — bugfix: fixed scope contamination 0.75→0 (critical) and conflict false 0→1 (GLOBAL leak), fixed graph hop1 0.52→1.0 via includeGraph; benchmark: rescaled profiles 5K/20K/100K/500K/1M (from 10K/100K/1M/5M/10M) for dev machine, viewer profiles within version upgraded to 5K/20K/100K

package/dist/db/index.js

@@ -197,5 +197,5 @@ export function ok(text) {
     return { content: [{ type: "text", text }] };
 }
 export function err(text) {
-    return ok(`error: ${truncate(text, 300)}`);
+    return { content: [{ type: "text", text: `error: ${truncate(text, 300)}` }], isError: true };
 }

package/dist/db/migrations.js

@@ -1,4 +1,5 @@
-import { copyFileSync } from "node:fs";
+import { copyFileSync, readdirSync, unlinkSync } from "node:fs";
+import { basename, dirname, join } from "node:path";
 import { embed, serialize } from "../lib/embed.js";
 const M001_schema_meta = {
     id: "001_schema_meta",
@@ -169,28 +170,62 @@ export const MIGRATIONS = [
     M006_scope,
     M007_user,
 ];
-export function runMigrations(db) {
+const KEEP_BACKUPS = 5;
+function pruneOldBackups(dbPath) {
     try {
-        const dbPath = db.name;
-        if (dbPath && dbPath !== ":memory:") {
-            const backupPath = `${dbPath}.backup-${Date.now()}`;
-            try {
-                copyFileSync(dbPath, backupPath);
-            }
-            catch {
-                console.error("[migrations] failed to create backup, aborting");
-                return;
+        const dir = dirname(dbPath);
+        const base = basename(dbPath);
+        const prefix = `${base}.backup-`;
+        const entries = readdirSync(dir);
+        const backups = entries.filter((n) => n.startsWith(prefix)).sort();
+        if (backups.length > KEEP_BACKUPS) {
+            for (const name of backups.slice(0, backups.length - KEEP_BACKUPS)) {
+                try {
+                    unlinkSync(join(dir, name));
+                }
+                catch { }
             }
         }
     }
     catch { }
+}
+export function runMigrations(db) {
     db.exec(`CREATE TABLE IF NOT EXISTS schema_meta (key TEXT PRIMARY KEY, value TEXT NOT NULL);`);
-    for (const m of MIGRATIONS) {
+    const pending = MIGRATIONS.filter((m) => {
         const applied = db
             .prepare("SELECT value FROM schema_meta WHERE key = ?")
             .get(m.id);
-        if (applied)
-            continue;
+        return !applied;
+    });
+    if (pending.length === 0) {
+        try {
+            const dbPath = db.name;
+            if (dbPath && dbPath !== ":memory:")
+                pruneOldBackups(dbPath);
+        }
+        catch { }
+        return;
+    }
+    const shouldBackup = process.env.MEMORY_BACKUP_ON_MIGRATE !== "0" &&
+        process.env.MEMORY_BACKUP_ON_MIGRATE !== "false";
+    if (shouldBackup) {
+        try {
+            const dbPath = db.name;
+            if (dbPath && dbPath !== ":memory:") {
+                const backupPath = `${dbPath}.backup-${Date.now()}`;
+                try {
+                    copyFileSync(dbPath, backupPath);
+                }
+                catch {
+                    console.error("[migrations] failed to create backup, aborting");
+                    return;
+                }
+                pruneOldBackups(dbPath);
+            }
+        }
+        catch { }
+    }
+    for (const m of pending) {
         const tx = db.transaction(() => {
             m.up(db);
             db.prepare("INSERT INTO schema_meta (key, value) VALUES (?, '1') ON CONFLICT(key) DO UPDATE SET value = '1'").run(m.id);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "th-memory-mcp",
-  "version": "2.2.6",
+  "version": "2.2.8",
   "mcpName": "io.github.worakorn-prince/th-memory-mcp",
   "description": "Adaptive Memory MCP server - SQLite-backed memory for OpenCode",
   "author": "worakorn-prince",
@@ -35,7 +35,11 @@
     "distill": "node dist/distill.js",
     "quickstart": "npm run build && node scripts/quickstart.mjs",
     "benchmark": "node repro/run.mjs",
-    "benchmark:heavy": "node benchmark/run.mjs --suite all --topics 100 --distractors 100 --scale 2000 --out benchmark/results",
+    "benchmark:quick": "node benchmark/run.mjs --profile quick --out benchmark/results",
+    "benchmark:normal": "node benchmark/run.mjs --profile normal --out benchmark/results",
+    "benchmark:heavy": "node benchmark/run.mjs --profile heavy --out benchmark/results",
+    "benchmark:all-profiles": "npm run benchmark:quick && npm run benchmark:normal && npm run benchmark:heavy",
+    "benchmark:pre-release": "npm run build && npm test && npm run benchmark:all-profiles",
     "benchmark:viewer": "npx serve . -l 3000"
   },
   "engines": {