th-memory-mcp 2.2.4 → 2.2.7

package/design.md

@@ -1,61 +1,65 @@
-# th-memory-mcp — Design Notes (ปัจจุบัน)
+# th-memory-mcp — Design Notes (Current)
 
-เอกสารนี้อัปเดตล่าสุดสอดคล้องกับสถานะจริงของโค้ด (หลังจบแผนฟีเจอร์อนาคตทั้งหมด ยกเว้น AI-assisted extraction ที่ตัดออก)
-สเปคฉบับเต็มอยู่ที่ `ARCHITECTURE_v2.md` (canonical spec) ไฟล์นี้สรุปภาพรวมและสถานะปัจจุบันเพื่อความสะดวก
+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.
 
-## สถานะปัจจุบัน
-- **เวอร์ชัน:** `package.json` = `2.2.4`
+## Current Status
+- **Version:** `package.json` = `2.2.7`
 - **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`)
-- **ชุดเทสต์:** 25 suites ผ่านหมด (0 fail) — รันผ่าน `npm test` (มี CI บน GitHub Actions)
+- **Test suites:** 25 suites passing (0 fail) — run via `npm test` (CI on GitHub Actions)
 
-## องค์ประกอบหลัก (src/)
-- `db/` — better-sqlite3 (WAL mode), migrations เชิงเส้น (M001–M007), repositories (`memories`, `users`, `preferences`, `lessons`)
-- `lib/embed.ts` — semantic vector แบบ hashing-trick (ไม่พึ่ง LLM/network)
-- `retrieval/` — FTS5 + vector → RRF fusion → scorer (confidence × importance × recency × scope)
+## Core Components (src/)
+- `db/` — better-sqlite3 (WAL mode), linear migrations (M001–M007), repositories (`memories`, `users`, `preferences`, `lessons`)
+- `lib/embed.ts` — hashing-trick lexical fuzzy matching (hashed n-gram similarity, 512-dim FNV-1a) (no LLM/network dependency)
+- `retrieval/` — FTS5 + lexical fuzzy matching (hashed n-gram similarity, 512-dim FNV-1a) → RRF fusion → scorer (confidence × importance × recency × scope)
 - `memory/` — types, lifecycle-engine (decay/source-weights), conflict-resolver, deduplicator
 - `core/` — retrieval-engine, context-engine, graph-engine, consolidation-engine, entity-extractor
 - `tools/` — 16 MCP tool handlers
 - `index.ts` — MCP stdio server
 
-## ฟีเจอร์ที่ทำเสร็จแล้ว
+## Completed Features
 - ✅ Temporal model — validity intervals, point-in-time retrieval, supersession chains, change detection
-- ✅ Conflict/dedup — normalize → exact → similar → classify (duplicate/update/contradiction/unrelated); ambiguous conflicts ถูกเก็บไว้ (link `contradicts`) ไม่เขียนทับเงียบๆ
-- ✅ Hybrid retrieval (FTS + vector, RRF)
+- ✅ Conflict/dedup — normalize → exact → similar → classify (duplicate/update/contradiction/unrelated); ambiguous conflicts are kept (link `contradicts`) instead of silently overwriting
+- ✅ Hybrid retrieval (FTS + lexical fuzzy matching (hashed n-gram similarity, 512-dim FNV-1a), RRF)
 - ✅ Memory graph — entities/relations + bounded traversal (`link_memory`)
-- ✅ Context engine — `get_context` with token budgeting, temporal filter, graph expansion
+- ✅ Context engine — `get_context` with token budgeting, temporal filtering, graph expansion
 - ✅ Consolidation — clustering + derived memories (`derived_from` provenance)
 - ✅ Scope hierarchy — `USER` / `SESSION` / `PROJECT` / `GLOBAL` (migrations 006 + 007)
-  - `createMemory` อนุมาน scope ตามลำดับ SESSION > PROJECT > USER > GLOBAL
-  - `scopeFactorFor` boost ความจำที่เข้าข่ายบริบทปัจจุบัน (USER=1.0, PROJECT/SESSION ตามบริบท, GLOBAL เป็น base)
-- ✅ Profile auto-projection — `profile.ts` ดึงความจำสำคัญมาแทรกใน `[memories]`
-- ✅ Auto entity extraction — `entity-extractor.ts` สกัด entity แบบ heuristic (ไม่ใช้ LLM) ผูกเข้า graph ตอน consolidate
-- ✅ Benchmark in-repo:
+  - `createMemory` infers scope in order SESSION > PROJECT > USER > GLOBAL
+  - `scopeFactorFor` boosts memories matching the current context (USER=1.0, PROJECT/SESSION depending on context, GLOBAL as base)
+- ✅ Profile auto-projection — `profile.ts` injects important memories into `[memories]`
+- ✅ Auto entity extraction — `entity-extractor.ts` extracts entities heuristically (no LLM) and links them into the graph during consolidation
+- ✅ In-repo benchmark:
   - Retrieval quality (§26) — `test/retrieval_benchmark.test.mjs` (Recall@5=1.00, Precision@5=0.92, MRR=1.00)
-  - Perf (§29) — `test/benchmark.test.mjs` วัด latency ต่อ op ผ่าน CI
-  - Conflict quality (§27) — `test/conflict_benchmark.test.mjs` (100% บนชุด 14 เคส ครบ 7 หมวด)
-  - E2E transport — `test/e2e_transport.test.mjs` (spawn server ผ่าน StdioClientTransport)
+  - Perf (§29) — `test/benchmark.test.mjs` measures latency per operation via CI
+  - Conflict quality (§27) — `test/conflict_benchmark.test.mjs` (100% on 14 cases across 7 categories)
+  - E2E transport — `test/e2e_transport.test.mjs` (spawn server via StdioClientTransport)
+  - Two modes — `npm run benchmark` (normal, 180 records) and `npm run benchmark:heavy` (600 records + full suite), viewer at `benchmark/viewer/` (`npm run benchmark:viewer`, compares latest 3 versions)
 - ✅ CI pipeline — `.github/workflows/ci.yml` (ubuntu-latest, node 20, `npm ci`, `npm test`)
 
-## Scope model (รายละเอียด)
-| Scope | เงื่อนไข | พฤติกรรม |
-|-------|----------|----------|
-| SESSION | มี `sessionId` | ผูกกับ session นั้น |
-| PROJECT | มี `projectId` (ไม่มี session) | ผูกกับ project นั้น |
-| USER | มี `userId` (ไม่มี session/project) | ผูกกับ user นั้น (auto-create row ใน `users`) |
-| GLOBAL | ไม่มีอะไรเลย | ความจำร่วมกันทั้งระบบ |
+## Scope Model (Details)
+| Scope | Condition | Behavior |
+|-------|-----------|----------|
+| SESSION | has `sessionId` | bound to that session |
+| PROJECT | has `projectId` (no session) | bound to that project |
+| USER | has `userId` (no session/project) | bound to that user (auto-creates row in `users`) |
+| GLOBAL | none | shared system-wide memory |
 
-`userId` ที่รับจาก client เป็น external identity (string) — ระบบไม่มีการ authenticate; ตัวตัดความเป็นของ client ทั้งหมด
-`preferences` และ `lessons` ยังคงเป็น global (ไม่มี user column)
+`userId` received from the client is an external identity (string) — the system does not authenticate; it is entirely client-declared.
+`preferences` and `lessons` remain global (no user column).
 
-## ข้อจำกัดที่รู้อยู่ (known limitations)
-- **Trust model:** ไม่มี user authentication — `userId` คือสิ่งที่ client แจ้งมา (client-declared) เหมาะกับการ deploy แบบ local single-user ที่ไฟล์ SQLite เป็นของเจ้าของคนเดียว หากต้องการแยกผู้ใช้หลายคน แนะนำแก้ที่ระดับไฟล์ DB (หนึ่ง DB ต่อผู้ใช้) ไม่ใช่เพิ่ม auth ลงใน engine
-- `preferences` / `lessons` ไม่ถูกแบ่งตาม user (ยังเป็น global) — ยอมรับได้สำหรับ single-user
-- Semantic embedding ใช้ hashing-trick (deterministic, offline) — ไม่ใช่ embedding ระดับ LLM จึงมีขีดจำกัดเรื่อง paraphrase ที่ห่างกันมาก
-- **AI-assisted extraction ไม่พัฒนาต่อ** — เจ้าของตัดสินใจตัดหัวข้อนี้ออก `extract_memories` จึงเป็น deterministic heuristic เท่านั้น (ไม่ใช้ LLM) ตามหลักการออกแบบที่ว่า core engine ต้องไม่พึ่งพา external LLM API
+## Known Limitations
+- **Trust model:** No user authentication — `userId` is client-declared. Suitable for local single-user deployment where the SQLite file is owned by a single user. For multi-user separation, use one DB file per user instead of adding auth to the engine.
+- `preferences` / `lessons` are not partitioned by user (still global) — acceptable for single-user.
+- Lexical fuzzy matching uses hashing-trick (hashed n-gram similarity, 512-dim FNV-1a, deterministic, offline) — not LLM-level / concept-level embedding, so distant paraphrases without shared tokens or 3-grams will not be linked (affects RRF vector signal and conflict-resolver threshold).
+- **AI-assisted extraction discontinued** — the owner decided to remove this; `extract_memories` is therefore deterministic heuristic only (no LLM), per the design principle that the core engine must not depend on an external LLM API.
+- **No encryption at rest (plaintext-at-rest) — Md-4:** `data/memory.db` (WAL mode, `better-sqlite3`) is a plain, unencrypted SQLite file. `100% local & private` means no cloud or network exfiltration — it does **not** mean encrypted at rest. Anyone with filesystem access (shared machine, backup, malware, stolen device) can read preferences/lessons/interactions in plaintext. For sensitive data, use OS-level full-disk encryption (BitLocker / FileVault / LUKS) or an opt-in SQLCipher build (requires native rebuild and key management). No SQLCipher/in-code encryption is applied by default and `src/db/index.ts` documents this explicitly.
 
 ## Release
-- v2.0.0 ปล่อยแล้ว (npm, GitHub Release, Official MCP Registry, Glama)
-- v2.2.0 — ปล่อยครบ: tag + GitHub Release, **npm publish เรียบร้อย**, Official MCP Registry ดึงจาก npm อัตโนมัติ (ไม่ต้องรัน mcp-publisher แยก), Glama Sync เรียบร้อย
-- v2.2.1 — แก้ Glama quality: เพิ่ม `pnpm.onlyBuiltDependencies: ["better-sqlite3"]` ให้ pnpm รันสคริปต์ดาวน์โหลด native binary สำหรับ Node 24, ขยับ better-sqlite3 เป็น `^12.9.0`, เพิ่ม override `ip-address@^10.2.0` (npm+pnpm) อุดช่องโหว่ XSS ผ่าน MCP SDK ไม่มีการเปลี่ยนโค้ด รอ `npm publish` + Glama ทดสอบใหม่
-- v2.2.3 — ชุดแก้ความปลอดภัย + ประสิทธิภาพตาม `report_checkup.md`: บังคับ scope filtering (ไม่คืน foreign USER/SESSION), กรอง graph ไม่ข้าม scope, ห้าม link ข้าม scope, export/import แบบ round-trip, ใช้ `realpath` กัน symlink, ตรวจ import เข้มงวด (enum/0..1/ISO), เลิก N+1 query (vector JOIN, bulk fetch, cap consolidation), benchmark cold/ablation และสวิตช์ `MEMORY_RETRIEVAL_MODE`, เพิ่ม 5 เทสต์ใหม่เป็น 25/25, benchmark รันครบทุก suite
-- v2.2.4 — docs: จัดหน้า badge ใน README ให้เป็นระเบียบ
+- v2.0.0 released (npm, GitHub Release, Official MCP Registry, Glama)
+- v2.2.0 — full release: tag + GitHub Release, **npm publish done**, Official MCP Registry auto-pulls from npm (no separate mcp-publisher run), Glama Sync done
+- v2.2.1 — Glama quality fix: added `pnpm.onlyBuiltDependencies: ["better-sqlite3"]` so pnpm runs the native binary download script for Node 24, bumped better-sqlite3 to `^12.9.0`, added override `ip-address@^10.2.0` (npm+pnpm) to patch XSS via MCP SDK — no code change, waiting for `npm publish` + Glama re-test
+- v2.2.3 — security + performance hardening per `report_checkup.md`: enforced scope filtering (no foreign USER/SESSION returned), graph scope isolation, disallow cross-scope links, round-trip export/import, `realpath` against symlink, strict import validation (enum/0..1/ISO), eliminated N+1 queries (vector JOIN, bulk fetch, cap consolidation), cold/ablation benchmark and `MEMORY_RETRIEVAL_MODE` switch, added 5 new tests to 25/25, benchmark runs all suites
+- 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)

package/dist/core/context-engine.js

@@ -33,11 +33,13 @@ export function getContext(opts = {}) {
     const limit = Math.min(Math.max(opts.limit ?? 10, 1), 50);
     const maxTokens = opts.maxTokens ?? 2000;
     const now = new Date();
+    const resolvedUid = opts.userId ? resolveUserId(opts.userId) : null;
     const seeds = retrieve(query, {
         limit,
         projectId: opts.projectId,
         sessionId: opts.sessionId,
         userId: opts.userId,
+        resolvedUid,
         includeArchived: opts.includeHistory,
     });
     const seedScores = new Map();
@@ -45,7 +47,6 @@ export function getContext(opts = {}) {
         seedScores.set(s.id, s.final_score);
     const ids = new Set(seeds.map((s) => s.id));
     if (opts.includeGraph) {
-        const uid = opts.userId ? resolveUserId(opts.userId) : null;
         for (const s of seeds) {
             for (const n of traverse(s.id, { maxDepth: 1 })) {
                 const m = db
@@ -58,7 +59,7 @@ export function getContext(opts = {}) {
                         m.status === "archived" ||
                         m.status === "superseded"))
                     continue;
-                if (!isScopeVisible(m, opts, uid))
+                if (!isScopeVisible(m, opts, resolvedUid))
                     continue;
                 if (!opts.includeHistory && !isCurrentlyValid(m, now))
                     continue;
@@ -66,7 +67,6 @@ export function getContext(opts = {}) {
             }
         }
     }
-    const resolvedUid = opts.userId ? resolveUserId(opts.userId) : null;
     const all = [...ids]
         .map((id) => db.prepare("SELECT * FROM memories WHERE id = ?").get(id))
         .filter((m) => !!m)

package/dist/core/retrieval-engine.js

@@ -21,7 +21,11 @@ export function retrieve(query, opts = {}) {
     }
     const fused = rrfFuse(lists);
     const now = new Date();
-    const resolvedUid = opts.userId ? resolveUserId(opts.userId) : null;
+    const resolvedUid = opts.resolvedUid !== undefined
+        ? opts.resolvedUid
+        : opts.userId
+            ? resolveUserId(opts.userId)
+            : null;
     const visible = (m) => {
         if (m.scope === "USER") {
             if (opts.userId == null)
@@ -64,7 +68,7 @@ export function retrieve(query, opts = {}) {
         const scope = scopeFactorFor(mem, {
             projectId: opts.projectId,
             sessionId: opts.sessionId,
-            userId: opts.userId ? resolveUserId(opts.userId) : null,
+            userId: resolvedUid,
         });
         const fs = finalScore({
             rrf,

package/dist/db/index.js

@@ -1,3 +1,15 @@
+/**
+ * Security note — encryption at rest (Md-4):
+ * DB is plaintext-at-rest. `better-sqlite3` does NOT use SQLCipher or any
+ * file-level encryption by default. The file at DB_PATH (default
+ * data/memory.db, WAL mode) is readable by anyone with filesystem access
+ * (shared machine, backup, malware, stolen device). "100% local & private"
+ * means no network exfiltration — it does NOT mean encrypted at rest.
+ * If you need encryption at rest, use OS-level full-disk encryption
+ * (BitLocker / FileVault / LUKS) or migrate to an opt-in SQLCipher build
+ * (native rebuild + key management required). No in-code encryption is
+ * applied; treat the file as you would any plaintext local store.
+ */
 import Database from "better-sqlite3";
 import { mkdirSync } from "node:fs";
 import { dirname } from "node:path";
@@ -6,7 +18,9 @@ import { serialize } from "../lib/embed.js";
 import { DEFAULT_DB_PATH } from "../lib/config.js";
 import { runMigrations } from "./migrations.js";
 export const DB_PATH = process.env.MEMORY_DB_PATH ?? DEFAULT_DB_PATH;
-function initDb() {
+let _db = null;
+let _dbInitialized = false;
+function createRawDb() {
     try {
         mkdirSync(dirname(DB_PATH), { recursive: true });
         return new Database(DB_PATH);
@@ -17,10 +31,12 @@ function initDb() {
         process.exit(1);
     }
 }
-export const db = initDb();
-db.pragma("journal_mode = WAL");
-db.pragma("busy_timeout = 5000");
-db.exec(`
+function ensureDbInitialized(instance) {
+    if (_dbInitialized)
+        return;
+    instance.pragma("journal_mode = WAL");
+    instance.pragma("busy_timeout = 5000");
+    instance.exec(`
 CREATE TABLE IF NOT EXISTS interactions (
   id INTEGER PRIMARY KEY AUTOINCREMENT,
   ts TEXT NOT NULL,
@@ -66,8 +82,25 @@ CREATE TABLE IF NOT EXISTS embeddings (
   PRIMARY KEY (ref_table, ref_id)
 );
 `);
-// v2 migration engine (non-destructive: only adds new tables + backfills from v1)
-runMigrations(db);
+    runMigrations(instance);
+    _dbInitialized = true;
+}
+export function getDb() {
+    if (!_db) {
+        _db = createRawDb();
+    }
+    ensureDbInitialized(_db);
+    return _db;
+}
+export const db = new Proxy({}, {
+    get(_target, prop) {
+        const real = getDb();
+        const value = real[prop];
+        if (typeof value === "function")
+            return value.bind(real);
+        return value;
+    },
+});
 export function nowISO() {
     return new Date().toISOString();
 }
@@ -78,34 +111,91 @@ export function escapeLike(text) {
 }
 export function buildFtsMatch(query) {
     const tokens = query.trim().split(/\s+/).filter(Boolean).slice(0, 8);
-    return tokens.map((t) => `"${t.replace(/"/g, "")}"`).join(" OR ");
+    return tokens
+        .map((t) => {
+        const safe = t.replace(/\\/g, "\\\\").replace(/"/g, '""');
+        return `"${safe}"`;
+    })
+        .join(" OR ");
+}
+let _insertSearchIndex = null;
+function getInsertSearchIndex() {
+    return (_insertSearchIndex ??= db.prepare("INSERT INTO search_index (ref_table, ref_id, title, body) VALUES (?, ?, ?, ?)"));
+}
+let _deleteSearchIndex = null;
+function getDeleteSearchIndex() {
+    return (_deleteSearchIndex ??= db.prepare("DELETE FROM search_index WHERE ref_table = ? AND ref_id = ?"));
 }
-const insertSearchIndex = db.prepare("INSERT INTO search_index (ref_table, ref_id, title, body) VALUES (?, ?, ?, ?)");
-const deleteSearchIndex = db.prepare("DELETE FROM search_index WHERE ref_table = ? AND ref_id = ?");
 export function syncSearchIndex(refTable, refId, title, body) {
-    deleteSearchIndex.run(refTable, refId);
-    insertSearchIndex.run(refTable, refId, title, body);
+    getDeleteSearchIndex().run(refTable, refId);
+    getInsertSearchIndex().run(refTable, refId, title, body);
 }
 export function removeSearchIndex(refTable, refId) {
-    deleteSearchIndex.run(refTable, refId);
+    getDeleteSearchIndex().run(refTable, refId);
 }
 // --- vector embeddings (lightweight local semantic search) ---
-const upsertEmbed = db.prepare(`INSERT INTO embeddings (ref_table, ref_id, vec) VALUES (?, ?, ?)
-   ON CONFLICT(ref_table, ref_id) DO UPDATE SET vec = excluded.vec`);
-const deleteEmbed = db.prepare("DELETE FROM embeddings WHERE ref_table = ? AND ref_id = ?");
-const allEmbeds = db.prepare("SELECT ref_table, ref_id, vec FROM embeddings");
+let _upsertEmbed = null;
+function getUpsertEmbed() {
+    return (_upsertEmbed ??= db.prepare(`INSERT INTO embeddings (ref_table, ref_id, vec) VALUES (?, ?, ?)
+   ON CONFLICT(ref_table, ref_id) DO UPDATE SET vec = excluded.vec`));
+}
+let _deleteEmbed = null;
+function getDeleteEmbed() {
+    return (_deleteEmbed ??= db.prepare("DELETE FROM embeddings WHERE ref_table = ? AND ref_id = ?"));
+}
+let _allEmbeds = null;
+function getAllEmbeds() {
+    return (_allEmbeds ??= db.prepare("SELECT ref_table, ref_id, vec FROM embeddings"));
+}
+let _scopedEmbeds = null;
+function getScopedEmbeds() {
+    return (_scopedEmbeds ??= db.prepare(`
+  SELECT e.ref_table as ref_table, e.ref_id as ref_id, e.vec as vec
+  FROM embeddings e
+  JOIN memories m ON m.id = e.ref_id
+  WHERE e.ref_table = 'memories'
+    AND m.status = 'active'
+    AND (m.scope = 'GLOBAL'
+         OR (m.scope = 'USER' AND m.user_id = @uid)
+         OR (m.scope = 'SESSION' AND m.session_id = @sid)
+         OR (m.scope = 'PROJECT' AND m.project_id = @pid))
+ `));
+}
+let _legacyEmbeds = null;
+function getLegacyEmbeds() {
+    return (_legacyEmbeds ??= db.prepare("SELECT ref_table, ref_id, vec FROM embeddings WHERE ref_table IN ('preferences','lessons')"));
+}
 export function upsertEmbedding(refTable, refId, vec) {
-    upsertEmbed.run(refTable, refId, serialize(vec));
+    getUpsertEmbed().run(refTable, refId, serialize(vec));
 }
 export function removeEmbedding(refTable, refId) {
-    deleteEmbed.run(refTable, refId);
+    getDeleteEmbed().run(refTable, refId);
 }
-export function getAllEmbeddings() {
-    return allEmbeds.all();
+export function getAllEmbeddings(opts = {}) {
+    const hasScopeFilter = opts.uid !== undefined || opts.sid !== undefined || opts.pid !== undefined;
+    if (!hasScopeFilter) {
+        const uid = null;
+        const sid = null;
+        const pid = null;
+        try {
+            const memRows = getScopedEmbeds().all({ uid, sid, pid });
+            const legacyRows = getLegacyEmbeds().all();
+            return [...memRows, ...legacyRows];
+        }
+        catch {
+            return getAllEmbeds().all();
+        }
+    }
+    const uid = opts.uid ?? null;
+    const sid = opts.sid ?? null;
+    const pid = opts.pid ?? null;
+    const memRows = getScopedEmbeds().all({ uid, sid, pid });
+    const legacyRows = getLegacyEmbeds().all();
+    return [...memRows, ...legacyRows];
 }
 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,3 +1,5 @@
+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",
@@ -168,14 +170,62 @@ export const MIGRATIONS = [
     M006_scope,
     M007_user,
 ];
+const KEEP_BACKUPS = 5;
+function pruneOldBackups(dbPath) {
+    try {
+        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/dist/db/repositories/users.js

@@ -2,6 +2,10 @@ import { db, nowISO } from "../index.js";
 // Resolve or create a user by external identity (what clients pass as `userId`).
 // Returns the internal user id.
 export function ensureUser(externalId, name) {
+    if (externalId.length === 0 || externalId.length > 200)
+        throw new Error("externalId must be 1-200 chars");
+    if (/[\x00-\x1f]/.test(externalId))
+        throw new Error("externalId contains invalid characters");
     const existing = db
         .prepare("SELECT id FROM users WHERE external_id = ?")
         .get(externalId);

package/dist/index.js

@@ -102,7 +102,22 @@ server.registerTool("extract_memories", {
     description: "Scan recent captured interactions for memory-intent phrases and propose memory candidates (deterministic, no LLM). Dry-run by default; pass apply=true to create them (source=captured).",
     inputSchema: extractMemoriesInput,
 }, (args) => extractMemoriesHandler(args));
+function isSupportedHarness() {
+    const env = process.env;
+    if (env.OPENCODE || env.CLAUDE_CODE_ENTRYPOINT || env.CLAUDECODE)
+        return true;
+    const harness = (env.MCP_HARNESS ?? env.HARNESS ?? "").toLowerCase();
+    if (harness.includes("opencode") || harness.includes("claude"))
+        return true;
+    const argv = process.argv.join(" ").toLowerCase();
+    if (argv.includes("opencode") || argv.includes("claude"))
+        return true;
+    return false;
+}
 async function main() {
+    if (!isSupportedHarness()) {
+        console.error("[th-memory-mcp] warning: running outside OpenCode/Claude Code — auto-capture unavailable, MCP tools still work. See README 'Works with other harnesses'.");
+    }
     const transport = new StdioServerTransport();
     await server.connect(transport);
     console.error(`[th-memory-mcp] ready on stdio`);

package/dist/lib/capture-core.js

@@ -1,4 +1,12 @@
 export const SECRET_LINE = /(api[_-]?key|secret|token|password)\s*[=:]/i;
+export const SECRET_PATTERNS = [
+    /(api[_-]?key|secret|token|password|auth|bearer|credential|private[_-]?key|access[_-]?key|database[_-]?url|connection[_-]?string)\s*[=:]\s*\S+/i,
+    /(sk-[a-zA-Z0-9]{20,})/i,
+    /(ghp_[a-zA-Z0-9]{36})/i,
+    /(glpat-[a-zA-Z0-9\-]{20,})/i,
+    /(Bearer\s+[a-zA-Z0-9\-_]+)/i,
+    /(-----BEGIN (RSA |EC |OPENSSH )?PRIVATE KEY-----)/i,
+];
 export const CAPTURE_KINDS = ["prompt", "tool_call", "error"];
 export const LIMITS = {
     prompt: 4000,
@@ -8,13 +16,21 @@ export const LIMITS = {
 export function filterSecrets(text) {
     return text
         .split("\n")
-        .filter((line) => !SECRET_LINE.test(line))
+        .map((line) => {
+        for (const p of SECRET_PATTERNS) {
+            if (p.test(line))
+                return line.replace(p, "[REDACTED]");
+        }
+        return line;
+    })
         .join("\n");
 }
 export function truncate(text, max) {
+    if (max <= 0)
+        return "";
     if (text.length <= max)
         return text;
-    return text.slice(0, max - 1) + "\u2026";
+    return text.slice(0, Math.max(0, max - 1)) + "\u2026";
 }
 export function createDedupe(maxSize = 1000) {
     const live = new Set();

package/dist/memory/conflict-resolver.js

@@ -24,11 +24,27 @@ const NEGATION = [
 // Opposite-value lexicon for ambiguous preference conflicts (preserve, don't
 // silently supersede). A pair is contradictory when each side names a different
 // antonym from this set.
-const ANTONYMS = new Set([
+export const ANTONYMS = new Set([
     "tabs", "spaces", "vim", "emacs", "light", "dark",
     "mysql", "postgres", "windows", "mac", "linux",
     "react", "vue", "ios", "android",
+    "ชา", "กาแฟ", "แมว", "สุนัข", "กลางคืน", "กลางวัน", "ร้อน", "เย็น", "หวาน", "เค็ม",
+    "เปิด", "ปิด", "ซ้าย", "ขวา", "บน", "ล่าง", "ก่อน", "หลัง", "ไทย", "อังกฤษ",
 ]);
+function parseAntonymsExtra(raw) {
+    return raw.split(/[\s,;\n|:\/]+/).map((s) => s.trim().toLowerCase()).filter(Boolean);
+}
+if (process.env.MEMORY_ANTONYMS_EXTRA) {
+    for (const w of parseAntonymsExtra(process.env.MEMORY_ANTONYMS_EXTRA))
+        ANTONYMS.add(w);
+}
+export function addAntonyms(...words) {
+    for (const w of words.flat()) {
+        for (const t of parseAntonymsExtra(String(w)))
+            ANTONYMS.add(t);
+    }
+}
+export function getAntonyms() { return [...ANTONYMS]; }
 export function isContradiction(a, b) {
     const na = NEGATION.some((re) => re.test(a));
     const nb = NEGATION.some((re) => re.test(b));
@@ -46,17 +62,32 @@ export function isContradiction(a, b) {
 // (e.g. "Prefer tabs" vs "Prefer spaces"). Used to preserve ambiguous
 // conflicts as contradictions instead of destructively superseding them.
 export function hasAntonymPair(a, b) {
+    const lowerA = a.toLowerCase();
+    const lowerB = b.toLowerCase();
     const ta = tokenSet(a);
     const tb = tokenSet(b);
     let aAnt;
     let bAnt;
-    for (const t of ta)
-        if (ANTONYMS.has(t))
-            aAnt = t;
-    for (const t of tb)
-        if (ANTONYMS.has(t))
-            bAnt = t;
-    return !!aAnt && !!bAnt && aAnt !== bAnt;
+    for (const w of ANTONYMS) {
+        if (ta.has(w) || lowerA.includes(w))
+            aAnt = w;
+        if (tb.has(w) || lowerB.includes(w))
+            bAnt = w;
+    }
+    // Find distinct pair: ensure each side has at least one and they are different
+    if (!aAnt || !bAnt)
+        return false;
+    if (aAnt === bAnt) {
+        // Check if there are other hits that give distinct pair
+        const hitsA = [...ANTONYMS].filter((w) => ta.has(w) || lowerA.includes(w));
+        const hitsB = [...ANTONYMS].filter((w) => tb.has(w) || lowerB.includes(w));
+        for (const ha of hitsA)
+            for (const hb of hitsB)
+                if (ha !== hb)
+                    return true;
+        return false;
+    }
+    return true;
 }
 function tokenSet(s) {
     return new Set(s.toLowerCase().match(/[a-z0-9ก-์]+/gi) ?? []);

package/dist/tools/export_memory.js

@@ -1,4 +1,4 @@
-import { mkdirSync, writeFileSync, statSync } from "node:fs";
+import { mkdirSync, writeFileSync, statSync, statfsSync } from "node:fs";
 import { join, dirname } from "node:path";
 import { z } from "zod";
 import { db, DB_PATH, nowISO, truncate, ok, err, } from "../db/index.js";
@@ -79,6 +79,12 @@ export async function exportMemoryHandler(args) {
         };
         const json = JSON.stringify(payload, null, 2);
         mkdirSync(EXPORT_DIR, { recursive: true });
+        try {
+            const stats = statfsSync(EXPORT_DIR);
+            if (json.length > stats.bavail * stats.bsize * 0.9)
+                return err("insufficient disk space for export");
+        }
+        catch { }
         const filePath = join(EXPORT_DIR, filename);
         writeFileSync(filePath, json, "utf8");
         const size = statSync(filePath).size;

package/dist/tools/recall.js

@@ -44,14 +44,14 @@ export async function recallHandler(args) {
                     const line = prefLine(Number(r.ref_id));
                     if (line) {
                         prefLines += line + "\n";
-                        seen.add(`p:${r.ref_id}`);
+                        seen.add(`p:${String(r.ref_id)}`);
                     }
                 }
                 else if (r.ref_table === "lessons") {
                     const line = lessonLine(Number(r.ref_id));
                     if (line) {
                         lessonLines += line + "\n";
-                        seen.add(`l:${r.ref_id}`);
+                        seen.add(`l:${String(r.ref_id)}`);
                     }
                 }
             }
@@ -76,7 +76,7 @@ export async function recallHandler(args) {
                 .sort((a, b) => b.score - a.score)
                 .slice(0, limit);
             for (const x of scored) {
-                const key = `${x.table[0]}:${x.id}`;
+                const key = `${x.table[0]}:${String(x.id)}`;
                 if (seen.has(key))
                     continue;
                 if (x.table === "preferences") {

package/dist/tools/update_memory.js

@@ -32,6 +32,11 @@ export function updateMemoryHandler(args) {
             return err("cannot update a deleted memory");
         const supersedeContent = args.content !== undefined && (args.supersede ?? true);
         if (supersedeContent) {
+            const externalId = mem.user_id
+                ? db
+                    .prepare("SELECT external_id FROM users WHERE id = ?")
+                    .get(mem.user_id)?.external_id ?? null
+                : null;
             const newId = createMemory({
                 type: mem.type,
                 content: args.content,
@@ -42,6 +47,7 @@ export function updateMemoryHandler(args) {
                 salience: mem.salience,
                 projectId: mem.project_id,
                 sessionId: mem.session_id,
+                userId: externalId,
                 validFrom: mem.valid_from,
                 validUntil: args.validUntil !== undefined ? args.validUntil : mem.valid_until,
                 metadata: args.metadata !== undefined