th-memory-mcp 2.2.8 → 2.2.9

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.8  
+**Baseline:** v1.2.2 → **Current:** v2.2.9  
 **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.

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.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).
+**Status:** v2.2.9 — 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). New in v2.2.9: extended export to entities/users/relations, forget now removes associated links, fail-closed migration with shared ISO helper, eliminated FTS N+1, included smoke in test script, and synced viewer to rescaled profiles 5K/20K/100K/500K/1M.
 
 ## Requirements
 
@@ -255,9 +255,9 @@ npm run benchmark:viewer
 # open http://localhost:3000/benchmark/viewer/  or  http://localhost:3000/result/viewer.html
 ```
 
-The viewer loads `benchmark/results/history.jsonl`, groups by version, takes the **latest run of the 3 most recent versions** (e.g. 2.2.2 / 2.2.3 / 2.2.4) and shows a highlighted table (1 row per version) + bar charts for `Recall@5 / MRR / NDCG@5` and `Latency p95`. Results are also saved per version in `result/v*_benchmark_result.md` and `benchmark/results/versions/<ver>/`.
+The viewer loads `benchmark/results/history.jsonl`, groups by version, takes the **latest run of the 3 most recent versions** (e.g. 2.2.6 / 2.2.7 / 2.2.8) and shows a highlighted table (1 row per version) + bar charts for `Recall@5 / MRR / NDCG@5` and `Latency p95`. Results are also saved per version in `result/v*_benchmark_result.md` and `benchmark/results/versions/<ver>/`.
 
-Last internal run (v2.2.4, warm, same dataset — not third-party): Recall@5=0.92, Precision@5=0.92, MRR=1.00, NDCG@5=0.94 over 30 topics/180 records. See `result/v2.2.4_benchmark_result.md` and `repro/README.md` for details and caveats (internal small-N, single-machine self-run).
+Last internal run (v2.2.8, warm, normal profile, a2dcbce — not third-party): Recall@5=0.9060, Precision@5=0.9060, MRR=1, NDCG@5=0.9347 over 100 topics/600 records. See `result/v2.2.8_benchmark_result.md` and `repro/README.md` for details and caveats (internal, single-machine self-run).
 
 ## Known Limitations
 

package/README.th.md

@@ -7,7 +7,7 @@
 
 MCP server ความจำระยะยาวสำหรับ OpenCode — เก็บ preferences, lessons, ประวัติการใช้งาน ลง SQLite ไฟล์เดียว (local 100%, ไม่มี external API) เพื่อให้ AI "จำและปรับตัว" กับผู้ใช้ผ่าน context-based learning
 
-**สถานะ:** 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)
+**สถานะ:** v2.2.9 — 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) ใหม่ใน v2.2.9: ขยาย export ให้ครอบคลุม entities/users/relations, forget ลบลิงก์ที่เกี่ยวข้อง, migration แบบ fail-closed พร้อม ISO helper กลาง, เลิก N+1 ใน FTS, รวม smoke ในสคริปต์เทส และซิงค์ viewer กับโปรไฟล์ rescale 5K/20K/100K/500K/1M
 
 > 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.8`
+- **Version:** `package.json` = `2.2.9`
 - **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)
 

package/dist/db/migrations.js

@@ -209,21 +209,26 @@ export function runMigrations(db) {
     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;
-                }
+        const dbPath = db.name;
+        if (dbPath && dbPath !== ":memory:") {
+            try {
+                // A plain copy of the main file is not a valid snapshot while recent
+                // commits are still in the WAL. Checkpoint first, then fail closed.
+                db.pragma("wal_checkpoint(TRUNCATE)");
+                // NOTE: better-sqlite3 exposes .backup(dest) but it is async
+                // (Promise-based) while runMigrations is sync and runs inside the
+                // DB singleton init path. Awaiting it would require making the whole
+                // migration/startup chain async and risks a half-applied state, so we
+                // keep the synchronous copyFileSync snapshot here on purpose.
+                // No new dependency added.
+                copyFileSync(dbPath, `${dbPath}.backup-${Date.now()}`);
                 pruneOldBackups(dbPath);
             }
+            catch (e) {
+                const reason = e instanceof Error ? e.message : String(e);
+                throw new Error(`migration backup failed for ${dbPath}: ${reason}`);
+            }
         }
-        catch { }
     }
     for (const m of pending) {
         const tx = db.transaction(() => {

package/dist/index.js

@@ -89,7 +89,7 @@ server.registerTool("merge_memory", {
 }, (args) => mergeMemoryHandler(args));
 server.registerTool("update_memory", {
     title: "Update a memory",
-    description: "Update mutable fields (summary/importance/confidence/valid_until/metadata) in place. If content changes, a superseding memory is created by default (set supersede=false to edit in place).",
+    description: "Update mutable fields (summary/importance/confidence/valid_from/valid_until/metadata) in place. If content changes, a superseding memory is created by default (set supersede=false to edit in place).",
     inputSchema: updateMemoryInput,
 }, (args) => updateMemoryHandler(args));
 server.registerTool("import_memory", {

package/dist/lib/config.js

@@ -1,6 +1,8 @@
 // config: shared constants. Pure module — no side effects, no I/O.
 import { fileURLToPath } from "node:url";
-export const VERSION = "1.1.0";
+// Keep this in sync with package.json.  It is surfaced in the MCP handshake
+// and in export files, so a stale value makes backups harder to diagnose.
+export const VERSION = "2.2.9";
 // dist/lib/config.js -> <project>/data/memory.db (independent of cwd).
 export const DEFAULT_DB_PATH = fileURLToPath(new URL("../../data/memory.db", import.meta.url));
 export const EXPORTS_DIRNAME = "exports";

package/dist/lib/iso.js

@@ -0,0 +1,11 @@
+import { z } from "zod";
+// Single source of truth for strict ISO datetime validation.
+// Requires a full datetime with timezone offset (e.g. 2024-01-01T00:00:00.000Z).
+// Date-only strings like "2024-01-01" are intentionally rejected: they are
+// ambiguous (no timezone) and break validFrom<=validUntil comparisons.
+export const isoDateTimeSchema = z.string().datetime({ offset: true });
+export function isIsoDateString(s) {
+    if (typeof s !== "string")
+        return false;
+    return isoDateTimeSchema.safeParse(s).success;
+}

package/dist/retrieval/fts.js

@@ -6,7 +6,7 @@ export function ftsSearch(query, opts = {}) {
         ? ""
         : "AND m.status NOT IN ('deleted','archived','superseded')";
     const rows = db
-        .prepare(`SELECT m.id FROM memories m
+        .prepare(`SELECT m.id, m.scope, m.project_id, m.session_id, m.user_id FROM memories m
        JOIN search_index ON search_index.ref_table = 'memories' AND search_index.ref_id = m.id
        WHERE search_index MATCH @match ${statusClause}
        ORDER BY rank
@@ -15,16 +15,11 @@ export function ftsSearch(query, opts = {}) {
         match: buildFtsMatch(query),
         limit,
     });
-    const filtered = rows.filter(({ id }) => {
-        const m = db
-            .prepare("SELECT scope, project_id, session_id, user_id FROM memories WHERE id = ?")
-            .get(id);
-        if (!m)
-            return false;
+    const uid = opts.userId == null ? null : resolveUserId(opts.userId);
+    const filtered = rows.filter((m) => {
         if (m.scope === "USER") {
             if (opts.userId == null)
                 return false;
-            const uid = resolveUserId(opts.userId);
             return m.user_id === uid;
         }
         if (m.scope === "SESSION") {

package/dist/tools/export_memory.js

@@ -21,6 +21,36 @@ const selectPrefs = db.prepare("SELECT id, category, key, value, confidence, sou
 const selectLessons = db.prepare("SELECT id, situation, mistake, correction, created_at FROM lessons ORDER BY id");
 const selectProfile = db.prepare("SELECT section, content, updated_at FROM profile ORDER BY section");
 const selectInteractions = db.prepare("SELECT id, ts, session_id, kind, content, meta FROM interactions ORDER BY id");
+const selectMemories = db.prepare(`
+  SELECT m.id, m.type, m.content, m.summary, m.status, m.source,
+         m.confidence, m.importance, m.salience, m.project_id AS projectId,
+         m.session_id AS sessionId, u.external_id AS userId,
+         m.valid_from AS validFrom, m.valid_until AS validUntil, m.metadata
+  FROM memories m
+  LEFT JOIN users u ON u.id = m.user_id
+  ORDER BY m.id
+`);
+const selectMemoryLinks = db.prepare("SELECT source_memory_id AS sourceId, relation, target_memory_id AS targetId, confidence, created_at AS createdAt FROM memory_links ORDER BY source_memory_id, target_memory_id");
+// Batch A gap-close: export users/entities/relations so backup/restore is complete.
+// FORMAT DECISION: keep `th-memory-mcp/v2` (do NOT bump to v3) and add the three
+// new top-level fields as additive/optional. Rationale: existing consumers and
+// test/export_v2.test.mjs assert format === v2 with a strict equality check; a v3
+// bump would break them and any downstream parser that allow-lists v2. Old v2
+// files simply lack these keys and import treats missing as empty (backward compat).
+const selectUsers = db.prepare("SELECT id, external_id AS externalId, name, created_at AS createdAt FROM users ORDER BY id");
+const selectEntities = db.prepare("SELECT id, name, canonical_name AS canonicalName, type, metadata FROM entities ORDER BY id");
+const selectRelations = db.prepare("SELECT id, source_entity_id AS sourceEntityId, relation, target_entity_id AS targetEntityId, confidence, valid_from AS validFrom, valid_until AS validUntil, source_memory_id AS sourceMemoryId, metadata FROM relations ORDER BY id");
+function parseMetadata(raw) {
+    if (raw == null)
+        return null;
+    try {
+        return JSON.parse(raw);
+    }
+    catch {
+        // Preserve malformed legacy values rather than making an export fail.
+        return raw;
+    }
+}
 function timestamp(d = new Date()) {
     const p = (n) => String(n).padStart(2, "0");
     return (`${d.getFullYear()}${p(d.getMonth() + 1)}${p(d.getDate())}` +
@@ -65,9 +95,22 @@ export async function exportMemoryHandler(args) {
         const interactionsIncluded = includeInteractions
             ? selectInteractions.all()
             : undefined;
+        const memories = selectMemories.all()
+            .map((m) => ({ ...m, metadata: parseMetadata(m.metadata) }));
+        const users = selectUsers.all();
+        const entities = selectEntities.all().map((e) => ({ ...e, metadata: parseMetadata(e.metadata) }));
+        const relations = selectRelations.all().map((r) => ({ ...r, metadata: parseMetadata(r.metadata) }));
         const payload = {
             exported_at: nowISO(),
             version: VERSION,
+            format: "th-memory-mcp/v2",
+            memories,
+            memoryLinks: selectMemoryLinks.all(),
+            // Additive v2 fields (optional for backward compat): full backup of
+            // M007 users + M003 entities/relations. Old importers ignore unknown keys.
+            users,
+            entities,
+            relations,
             preferences: selectPrefs.all(),
             lessons: selectLessons.all(),
             profile: selectProfile.all(),

package/dist/tools/forget.js

@@ -7,7 +7,7 @@ export const forgetInput = {
         .positive()
         .describe("Row id to delete (id returned by remember/save_lesson)"),
     type: z
-        .enum(["preference", "lesson", "interaction"])
+        .enum(["memory", "preference", "lesson", "interaction"])
         .optional()
         .describe("Which table the id belongs to. Recommended whenever known, because numeric ids can coincide across tables."),
 };
@@ -15,10 +15,14 @@ const indexTables = db.prepare("SELECT DISTINCT ref_table FROM search_index WHER
 const existsPreference = db.prepare("SELECT id FROM preferences WHERE id = ?");
 const existsLesson = db.prepare("SELECT id FROM lessons WHERE id = ?");
 const existsInteraction = db.prepare("SELECT id FROM interactions WHERE id = ?");
+const existsMemory = db.prepare("SELECT id FROM memories WHERE id = ? AND status <> 'deleted'");
 const delPreference = db.prepare("DELETE FROM preferences WHERE id = ?");
 const delLesson = db.prepare("DELETE FROM lessons WHERE id = ?");
 const delInteraction = db.prepare("DELETE FROM interactions WHERE id = ?");
+const delMemoryLinks = db.prepare("DELETE FROM memory_links WHERE source_memory_id = ? OR target_memory_id = ?");
 function existsIn(kind, id) {
+    if (kind === "memories")
+        return !!existsMemory.get(id);
     if (kind === "preferences") {
         return !!existsPreference.get(id);
     }
@@ -31,6 +35,7 @@ export async function forgetHandler(args) {
     try {
         const id = args.target_id;
         const kindOf = {
+            memory: "memories",
             preference: "preferences",
             lesson: "lessons",
             interaction: "interactions",
@@ -44,21 +49,37 @@ export async function forgetHandler(args) {
             const indexed = indexTables.all(id);
             const evidence = indexed
                 .map((r) => r.ref_table)
-                .filter((t) => t === "preferences" || t === "lessons" || t === "interactions");
+                .filter((t) => t === "memories" || t === "preferences" || t === "lessons" || t === "interactions");
             const candidates = evidence.length > 0
                 ? evidence
-                : ["preferences", "lessons", "interactions"];
+                : ["memories", "preferences", "lessons", "interactions"];
             targets = candidates.filter((k) => existsIn(k, id));
         }
         if (targets.length === 0) {
             return ok(`nothing found with id=${id}`);
         }
         const removed = [];
+        let linksRemoved = 0;
         db.transaction(() => {
             for (const kind of targets) {
                 if (!existsIn(kind, id))
                     continue;
-                if (kind === "preferences") {
+                if (kind === "memories") {
+                    db.prepare("UPDATE memories SET status = 'deleted' WHERE id = ?").run(id);
+                    removeSearchIndex("memories", id);
+                    removeEmbedding("memories", id);
+                    // Batch A: cascade-delete memory_links referencing this id on BOTH sides
+                    // in the same transaction so forget never leaves dangling graph edges.
+                    // NOTE: entities/relations are intentionally NOT deleted here — they are
+                    // shared graph nodes that may still be referenced by other memories;
+                    // deleting them would corrupt the graph. Orphaned rows stay harmless
+                    // and can be reclaimed by consolidate/GC later.
+                    const info = delMemoryLinks.run(id, id);
+                    const n = Number(info.changes ?? 0);
+                    linksRemoved += n;
+                    removed.push(`memory #${id} (${n} link(s) removed)`);
+                }
+                else if (kind === "preferences") {
                     delPreference.run(id);
                     removeSearchIndex("preferences", id);
                     removeEmbedding("preferences", id);

package/dist/tools/import_memory.js

@@ -4,8 +4,9 @@ import { join, dirname, resolve, sep } from "node:path";
 import { db, DB_PATH, nowISO, syncSearchIndex, upsertEmbedding, ok, err, } from "../db/index.js";
 import { createMemory } from "../db/repositories/memories.js";
 import { deduplicate } from "../memory/deduplicator.js";
-import { MEMORY_TYPES, SOURCE_TYPES } from "../memory/types.js";
+import { MEMORY_TYPES, SOURCE_TYPES, LIFECYCLE_STATES, LINK_RELATIONS } from "../memory/types.js";
 import { EXPORTS_DIRNAME } from "../lib/config.js";
+import { isIsoDateString } from "../lib/iso.js";
 import { embed } from "../lib/embed.js";
 export const importMemoryInput = {
     file: z
@@ -26,20 +27,6 @@ export const importMemoryInput = {
         .optional()
         .describe("Scope imported memories to a user (USER scope)"),
 };
-function isIsoDateString(s) {
-    if (typeof s !== "string")
-        return false;
-    const d = Date.parse(s);
-    if (Number.isNaN(d))
-        return false;
-    try {
-        const iso = new Date(s).toISOString();
-        return iso.length >= 10;
-    }
-    catch {
-        return false;
-    }
-}
 function isValidSource(s) {
     return SOURCE_TYPES.includes(s);
 }
@@ -86,19 +73,15 @@ export function importMemoryHandler(args) {
         let exportPrefs = null;
         let exportLessons = null;
         let exportProfile = null;
+        let exportLinks = null;
+        // Batch A: additive backup fields (may be absent in legacy v2 files -> null = backward compat).
+        let exportUsers = null;
+        let exportEntities = null;
+        let exportRelations = null;
         if (Array.isArray(parsed)) {
             memoryItems = parsed;
         }
-        else if (parsed &&
-            typeof parsed === "object" &&
-            Array.isArray(parsed.memories)) {
-            memoryItems = parsed.memories;
-        }
-        else if (parsed &&
-            typeof parsed === "object" &&
-            ("preferences" in parsed ||
-                "lessons" in parsed ||
-                "profile" in parsed)) {
+        else if (parsed && typeof parsed === "object") {
             const p = parsed;
             if (Array.isArray(p.preferences))
                 exportPrefs = p.preferences;
@@ -108,15 +91,58 @@ export function importMemoryHandler(args) {
                 exportProfile = p.profile;
             if (Array.isArray(p.memories))
                 memoryItems = p.memories;
+            if (Array.isArray(p.memoryLinks))
+                exportLinks = p.memoryLinks;
+            // Accept both new keys and legacy absence (missing => null => skip, still pass).
+            if (Array.isArray(p.users))
+                exportUsers = p.users;
+            if (Array.isArray(p.entities))
+                exportEntities = p.entities;
+            if (Array.isArray(p.relations))
+                exportRelations = p.relations;
         }
         else {
             memoryItems = [];
         }
+        // Restore users FIRST (before memories) so createMemory()->ensureUser reuses
+        // the restored row (with original name/created_at) instead of auto-creating
+        // a bare row. Idempotent via UNIQUE(external_id) + INSERT OR IGNORE.
+        let usersImported = 0;
+        let usersInvalid = 0;
+        if (exportUsers != null) {
+            const insertUser = db.prepare("INSERT OR IGNORE INTO users (external_id, name, created_at) VALUES (?, ?, ?)");
+            for (const u of exportUsers) {
+                const external = typeof u.externalId === "string"
+                    ? u.externalId
+                    : typeof u.external_id === "string"
+                        ? u.external_id
+                        : null;
+                if (!u ||
+                    !external ||
+                    external.length === 0 ||
+                    external.length > 200 ||
+                    /[\x00-\x1f]/.test(external)) {
+                    usersInvalid++;
+                    continue;
+                }
+                const created = (typeof u.createdAt === "string" && isIsoDateString(u.createdAt)
+                    ? u.createdAt
+                    : typeof u.created_at === "string" && isIsoDateString(u.created_at)
+                        ? u.created_at
+                        : null) ?? nowISO();
+                const name = typeof u.name === "string" ? u.name.slice(0, 500) : null;
+                usersImported++;
+                if (args.apply === true) {
+                    insertUser.run(external, name, created);
+                }
+            }
+        }
         let wouldImport = 0;
         let skipped = 0;
         let invalid = 0;
         const log = [];
-        for (const it of memoryItems) {
+        const importedIds = new Map();
+        for (const [idx, it] of memoryItems.entries()) {
             if (!it ||
                 typeof it.content !== "string" ||
                 it.content.length === 0 ||
@@ -141,6 +167,14 @@ export function importMemoryHandler(args) {
                 invalid++;
                 continue;
             }
+            if (it.salience != null && (typeof it.salience !== "number" || it.salience < 0 || it.salience > 1)) {
+                invalid++;
+                continue;
+            }
+            if (it.status != null && (typeof it.status !== "string" || !LIFECYCLE_STATES.includes(it.status))) {
+                invalid++;
+                continue;
+            }
             if (it.projectId != null && (typeof it.projectId !== "string" || it.projectId.length === 0 || it.projectId.length > 200)) {
                 invalid++;
                 continue;
@@ -155,10 +189,19 @@ export function importMemoryHandler(args) {
             }
             if (it.validFrom != null && (typeof it.validFrom !== "string" || !isIsoDateString(it.validFrom))) {
                 invalid++;
+                log.push(`invalid row ${idx}: validFrom '${String(it.validFrom)}' rejected — must be a full ISO datetime with timezone offset (e.g. 2024-01-01T00:00:00.000Z), date-only '2024-01-01' is not accepted`);
                 continue;
             }
             if (it.validUntil != null && (typeof it.validUntil !== "string" || !isIsoDateString(it.validUntil))) {
                 invalid++;
+                log.push(`invalid row ${idx}: validUntil '${String(it.validUntil)}' rejected — must be a full ISO datetime with timezone offset (e.g. 2024-01-01T00:00:00.000Z), date-only '2024-01-01' is not accepted`);
+                continue;
+            }
+            if (typeof it.validFrom === "string" &&
+                typeof it.validUntil === "string" &&
+                new Date(it.validFrom) > new Date(it.validUntil)) {
+                invalid++;
+                log.push(`invalid row ${idx}: validFrom (${it.validFrom}) must not be later than validUntil (${it.validUntil})`);
                 continue;
             }
             const dup = deduplicate(it.type, it.content);
@@ -169,13 +212,14 @@ export function importMemoryHandler(args) {
             }
             wouldImport++;
             if (args.apply === true) {
-                createMemory({
+                const newId = createMemory({
                     type: it.type,
                     content: it.content,
                     summary: typeof it.summary === "string" ? it.summary : null,
                     source: it.source ?? "imported",
                     confidence: typeof it.confidence === "number" ? it.confidence : 0.7,
                     importance: typeof it.importance === "number" ? it.importance : 0.5,
+                    salience: typeof it.salience === "number" ? it.salience : 0.5,
                     projectId: typeof it.projectId === "string" ? it.projectId : null,
                     sessionId: typeof it.sessionId === "string" ? it.sessionId : null,
                     userId: typeof it.userId === "string"
@@ -187,8 +231,163 @@ export function importMemoryHandler(args) {
                     validUntil: typeof it.validUntil === "string" ? it.validUntil : null,
                     metadata: it.metadata ?? null,
                 });
+                if (typeof it.id === "number" && Number.isInteger(it.id))
+                    importedIds.set(it.id, newId);
+                if (typeof it.status === "string" && it.status !== "active") {
+                    db.prepare("UPDATE memories SET status = ? WHERE id = ?").run(it.status, newId);
+                }
+            }
+        }
+        let linksImported = 0;
+        let linksInvalid = 0;
+        if (exportLinks != null) {
+            for (const link of exportLinks) {
+                const sourceId = typeof link.sourceId === "number" ? importedIds.get(link.sourceId) : undefined;
+                const targetId = typeof link.targetId === "number" ? importedIds.get(link.targetId) : undefined;
+                if (!sourceId || !targetId || typeof link.relation !== "string" || !LINK_RELATIONS.includes(link.relation) ||
+                    (link.confidence != null && (typeof link.confidence !== "number" || link.confidence < 0 || link.confidence > 1))) {
+                    linksInvalid++;
+                    continue;
+                }
+                if (args.apply === true) {
+                    db.prepare("INSERT OR IGNORE INTO memory_links (source_memory_id, relation, target_memory_id, confidence, created_at) VALUES (?, ?, ?, ?, ?)").run(sourceId, link.relation, targetId, link.confidence ?? 0.5, nowISO());
+                }
+                linksImported++;
+            }
+        }
+        // Batch A: restore M003 entities/relations idempotently.
+        // - entities: dedupe by UNIQUE(canonical_name); keep oldId->newId map for relations.
+        // - relations: `relation` is free-form (e.g. co_occurs) so do NOT check LINK_RELATIONS
+        //   here (that check stays only for memory_links above). Keep ISO validation as-is;
+        //   another team will unify validation later. Missing arrays (legacy v2) => skip, still pass.
+        let entitiesImported = 0;
+        let entitiesInvalid = 0;
+        const importedEntityIds = new Map();
+        if (exportEntities != null) {
+            const selEntity = db.prepare("SELECT id FROM entities WHERE canonical_name = ?");
+            const insEntity = db.prepare("INSERT INTO entities (name, canonical_name, type, metadata) VALUES (?, ?, ?, ?)");
+            for (const e of exportEntities) {
+                const name = typeof e.name === "string" ? e.name : "";
+                const canonical = typeof e.canonicalName === "string"
+                    ? e.canonicalName
+                    : typeof e.canonical_name === "string"
+                        ? e.canonical_name
+                        : "";
+                if (!e || name.length === 0 || name.length > 500 || canonical.length === 0 || canonical.length > 500) {
+                    entitiesInvalid++;
+                    continue;
+                }
+                entitiesImported++;
+                if (args.apply === true) {
+                    const existing = selEntity.get(canonical);
+                    let newId;
+                    if (existing) {
+                        newId = existing.id;
+                    }
+                    else {
+                        const type = typeof e.type === "string" ? e.type.slice(0, 200) : "concept";
+                        const meta = e.metadata == null
+                            ? JSON.stringify({})
+                            : typeof e.metadata === "string"
+                                ? e.metadata
+                                : JSON.stringify(e.metadata);
+                        const res = insEntity.run(name.slice(0, 500), canonical, type, meta);
+                        newId = Number(res.lastInsertRowid);
+                    }
+                    if (typeof e.id === "number" && Number.isInteger(e.id))
+                        importedEntityIds.set(e.id, newId);
+                }
+            }
+        }
+        let relationsImported = 0;
+        let relationsInvalid = 0;
+        if (exportRelations != null) {
+            const selEntityById = db.prepare("SELECT id FROM entities WHERE id = ?");
+            const selMemById = db.prepare("SELECT id FROM memories WHERE id = ?");
+            const selRelation = db.prepare("SELECT id FROM relations WHERE source_entity_id = ? AND relation = ? AND target_entity_id = ? AND COALESCE(source_memory_id, -1) = COALESCE(?, -1)");
+            const insRelation = db.prepare("INSERT INTO relations (source_entity_id, relation, target_entity_id, confidence, valid_from, valid_until, source_memory_id, metadata) VALUES (?, ?, ?, ?, ?, ?, ?, ?)");
+            for (const r of exportRelations) {
+                const oldSource = typeof r.sourceEntityId === "number"
+                    ? r.sourceEntityId
+                    : typeof r.source_entity_id === "number"
+                        ? r.source_entity_id
+                        : null;
+                const oldTarget = typeof r.targetEntityId === "number"
+                    ? r.targetEntityId
+                    : typeof r.target_entity_id === "number"
+                        ? r.target_entity_id
+                        : null;
+                const predicate = typeof r.relation === "string" ? r.relation : "";
+                const conf = r.confidence == null ? 0.5 : r.confidence;
+                const vf = typeof r.validFrom === "string"
+                    ? r.validFrom
+                    : typeof r.valid_from === "string"
+                        ? r.valid_from
+                        : null;
+                const vu = typeof r.validUntil === "string"
+                    ? r.validUntil
+                    : typeof r.valid_until === "string"
+                        ? r.valid_until
+                        : null;
+                const oldMem = typeof r.sourceMemoryId === "number"
+                    ? r.sourceMemoryId
+                    : typeof r.source_memory_id === "number"
+                        ? r.source_memory_id
+                        : null;
+                if (!r ||
+                    oldSource == null ||
+                    oldTarget == null ||
+                    predicate.length === 0 ||
+                    predicate.length > 200 ||
+                    typeof conf !== "number" ||
+                    conf < 0 ||
+                    conf > 1 ||
+                    (vf != null && !isIsoDateString(vf)) ||
+                    (vu != null && !isIsoDateString(vu)) ||
+                    (vf != null && vu != null && new Date(vf) > new Date(vu))) {
+                    relationsInvalid++;
+                    continue;
+                }
+                // Remap entity ids: prefer import map, else keep original id if row still exists.
+                let newSource = null;
+                let newTarget = null;
+                if (importedEntityIds.has(oldSource))
+                    newSource = importedEntityIds.get(oldSource);
+                else if (selEntityById.get(oldSource))
+                    newSource = oldSource;
+                if (importedEntityIds.has(oldTarget))
+                    newTarget = importedEntityIds.get(oldTarget);
+                else if (selEntityById.get(oldTarget))
+                    newTarget = oldTarget;
+                if (newSource == null || newTarget == null) {
+                    relationsInvalid++;
+                    continue;
+                }
+                // Remap memory id: prefer import map, else keep original if still present, else NULL (orphan-safe).
+                let newMem = null;
+                if (oldMem == null)
+                    newMem = null;
+                else if (importedIds.has(oldMem))
+                    newMem = importedIds.get(oldMem);
+                else if (selMemById.get(oldMem))
+                    newMem = oldMem;
+                else
+                    newMem = null;
+                relationsImported++;
+                if (args.apply === true) {
+                    const dup = selRelation.get(newSource, predicate, newTarget, newMem);
+                    if (dup)
+                        continue;
+                    const meta = r.metadata == null
+                        ? JSON.stringify({})
+                        : typeof r.metadata === "string"
+                            ? r.metadata
+                            : JSON.stringify(r.metadata);
+                    insRelation.run(newSource, predicate, newTarget, conf, vf, vu, newMem, meta);
+                }
             }
         }
+        const graphSuffix = `users ${usersImported} ok ${usersInvalid} invalid; entities ${entitiesImported} ok ${entitiesInvalid} invalid; relations ${relationsImported} ok ${relationsInvalid} invalid`;
         if (exportPrefs != null || exportLessons != null || exportProfile != null) {
             const prefArr = Array.isArray(exportPrefs) ? exportPrefs : [];
             const lessonArr = Array.isArray(exportLessons) ? exportLessons : [];
@@ -268,11 +467,11 @@ export function importMemoryHandler(args) {
                 }
             }
             const mode = args.apply === true ? "applied" : "dry-run";
-            const summary = `import ${mode}: ${wouldImport} memories to import, ${skipped} duplicate(s) skipped, ${invalid} invalid memories; preferences ${prefOk} ok ${prefInvalid} invalid; lessons ${lessonOk} ok ${lessonInvalid} invalid; profile ${profileOk} ok`;
+            const summary = `import ${mode}: ${wouldImport} memories to import, ${skipped} duplicate(s) skipped, ${invalid} invalid memories; ${linksImported} link(s) imported, ${linksInvalid} invalid link(s); preferences ${prefOk} ok ${prefInvalid} invalid; lessons ${lessonOk} ok ${lessonInvalid} invalid; profile ${profileOk} ok; ${graphSuffix}`;
             return ok(summary);
         }
         const mode = args.apply === true ? "applied" : "dry-run";
-        const summary = `import ${mode}: ${wouldImport} to import, ${skipped} duplicate(s) skipped, ${invalid} invalid`;
+        const summary = `import ${mode}: ${wouldImport} to import, ${skipped} duplicate(s) skipped, ${invalid} invalid, ${linksImported} link(s) imported, ${linksInvalid} invalid link(s); ${graphSuffix}`;
         return ok(log.length ? `${summary}\n${log.join("\n")}` : summary);
     }
     catch (e) {

package/dist/tools/update_memory.js

@@ -2,6 +2,7 @@ import { z } from "zod";
 import { db, nowISO, ok, err, } from "../db/index.js";
 import { getMemoryById, createMemory, syncMemoryIndex, } from "../db/repositories/memories.js";
 import { supersede } from "../core/lifecycle-engine.js";
+import { isoDateTimeSchema, isIsoDateString } from "../lib/iso.js";
 export const updateMemoryInput = {
     id: z.number().int().describe("Memory id to update"),
     content: z
@@ -12,9 +13,12 @@ export const updateMemoryInput = {
     summary: z.string().max(2000).nullable().optional().describe("New summary"),
     importance: z.number().min(0).max(1).optional(),
     confidence: z.number().min(0).max(1).optional(),
+    validFrom: z
+        .union([isoDateTimeSchema, z.null()])
+        .optional()
+        .describe("ISO timestamp or null to clear"),
     validUntil: z
-        .string()
-        .nullable()
+        .union([isoDateTimeSchema, z.null()])
         .optional()
         .describe("ISO timestamp or null to clear"),
     metadata: z.unknown().optional().describe("New metadata object (replaces)"),
@@ -30,6 +34,24 @@ export function updateMemoryHandler(args) {
             return err(`memory ${args.id} not found`);
         if (mem.status === "deleted")
             return err("cannot update a deleted memory");
+        if (args.validFrom !== undefined &&
+            args.validFrom !== null &&
+            !isIsoDateString(args.validFrom)) {
+            return err(`validFrom must be a full ISO datetime with timezone offset (e.g. 2024-01-01T00:00:00.000Z), got '${args.validFrom}'`);
+        }
+        if (args.validUntil !== undefined &&
+            args.validUntil !== null &&
+            !isIsoDateString(args.validUntil)) {
+            return err(`validUntil must be a full ISO datetime with timezone offset (e.g. 2024-01-01T00:00:00.000Z), got '${args.validUntil}'`);
+        }
+        // Effective range covers new values and values mixed with the existing row.
+        const effectiveValidFrom = args.validFrom !== undefined ? args.validFrom : mem.valid_from;
+        const effectiveValidUntil = args.validUntil !== undefined ? args.validUntil : mem.valid_until;
+        if (effectiveValidFrom != null &&
+            effectiveValidUntil != null &&
+            new Date(effectiveValidFrom) > new Date(effectiveValidUntil)) {
+            return err(`validFrom (${effectiveValidFrom}) must not be later than validUntil (${effectiveValidUntil})`);
+        }
         const supersedeContent = args.content !== undefined && (args.supersede ?? true);
         if (supersedeContent) {
             const externalId = mem.user_id
@@ -48,7 +70,7 @@ export function updateMemoryHandler(args) {
                 projectId: mem.project_id,
                 sessionId: mem.session_id,
                 userId: externalId,
-                validFrom: mem.valid_from,
+                validFrom: args.validFrom !== undefined ? args.validFrom : mem.valid_from,
                 validUntil: args.validUntil !== undefined ? args.validUntil : mem.valid_until,
                 metadata: args.metadata !== undefined
                     ? args.metadata
@@ -73,6 +95,10 @@ export function updateMemoryHandler(args) {
             sets.push("confidence = ?");
             vals.push(args.confidence);
         }
+        if (args.validFrom !== undefined) {
+            sets.push("valid_from = ?");
+            vals.push(args.validFrom);
+        }
         if (args.validUntil !== undefined) {
             sets.push("valid_until = ?");
             vals.push(args.validUntil);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "th-memory-mcp",
-  "version": "2.2.8",
+  "version": "2.2.9",
   "mcpName": "io.github.worakorn-prince/th-memory-mcp",
   "description": "Adaptive Memory MCP server - SQLite-backed memory for OpenCode",
   "author": "worakorn-prince",
@@ -31,7 +31,7 @@
     "version:check": "node scripts/sync-version.mjs --check",
     "start": "node dist/index.js",
     "inspect": "npx @modelcontextprotocol/inspector node dist/index.js",
-    "test": "npm run build && node --test test/*.test.mjs",
+    "test": "npm run build && node --test test/*.test.mjs test/smoke.mjs",
     "distill": "node dist/distill.js",
     "quickstart": "npm run build && node scripts/quickstart.mjs",
     "benchmark": "node repro/run.mjs",

package/dist/db.js

@@ -1,111 +0,0 @@
-import Database from "better-sqlite3";
-import { mkdirSync } from "node:fs";
-import { dirname } from "node:path";
-import { truncate } from "./lib/capture-core.js";
-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() {
-    try {
-        mkdirSync(dirname(DB_PATH), { recursive: true });
-        return new Database(DB_PATH);
-    }
-    catch (e) {
-        const msg = e instanceof Error ? e.message : String(e);
-        console.error(`[th-memory-mcp] cannot open DB at ${DB_PATH}: ${msg}`);
-        process.exit(1);
-    }
-}
-export const db = initDb();
-db.pragma("journal_mode = WAL");
-db.pragma("busy_timeout = 5000");
-db.exec(`
-CREATE TABLE IF NOT EXISTS interactions (
-  id INTEGER PRIMARY KEY AUTOINCREMENT,
-  ts TEXT NOT NULL,
-  session_id TEXT,
-  kind TEXT NOT NULL,
-  content TEXT NOT NULL,
-  meta TEXT
-);
-
-CREATE TABLE IF NOT EXISTS preferences (
-  id INTEGER PRIMARY KEY AUTOINCREMENT,
-  category TEXT NOT NULL,
-  key TEXT NOT NULL,
-  value TEXT NOT NULL,
-  confidence REAL DEFAULT 0.5,
-  source TEXT DEFAULT 'explicit',
-  updated_at TEXT NOT NULL,
-  UNIQUE(category, key)
-);
-
-CREATE TABLE IF NOT EXISTS lessons (
-  id INTEGER PRIMARY KEY AUTOINCREMENT,
-  situation TEXT NOT NULL,
-  mistake TEXT NOT NULL,
-  correction TEXT NOT NULL,
-  created_at TEXT NOT NULL
-);
-
-CREATE TABLE IF NOT EXISTS profile (
-  section TEXT PRIMARY KEY,
-  content TEXT NOT NULL,
-  updated_at TEXT NOT NULL
-);
-
-CREATE VIRTUAL TABLE IF NOT EXISTS search_index USING fts5(
-  ref_table, ref_id, title, body
-);
-
-CREATE TABLE IF NOT EXISTS embeddings (
-  ref_table TEXT NOT NULL,
-  ref_id INTEGER NOT NULL,
-  vec BLOB NOT NULL,
-  PRIMARY KEY (ref_table, ref_id)
-);
-`);
-// v2 migration engine (non-destructive: only adds new tables + backfills from v1)
-runMigrations(db);
-export function nowISO() {
-    return new Date().toISOString();
-}
-// re-exported from lib/capture-core.js (single source of truth)
-export { truncate };
-export function escapeLike(text) {
-    return text.replace(/[\\%_]/g, (c) => "\\" + c);
-}
-export function buildFtsMatch(query) {
-    const tokens = query.trim().split(/\s+/).filter(Boolean).slice(0, 8);
-    return tokens.map((t) => `"${t.replace(/"/g, "")}"`).join(" ");
-}
-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);
-}
-export function removeSearchIndex(refTable, refId) {
-    deleteSearchIndex.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");
-export function upsertEmbedding(refTable, refId, vec) {
-    upsertEmbed.run(refTable, refId, serialize(vec));
-}
-export function removeEmbedding(refTable, refId) {
-    deleteEmbed.run(refTable, refId);
-}
-export function getAllEmbeddings() {
-    return allEmbeds.all();
-}
-export function ok(text) {
-    return { content: [{ type: "text", text }] };
-}
-export function err(text) {
-    return ok(`error: ${truncate(text, 300)}`);
-}