th-memory-mcp 2.0.0 → 2.1.0

package/README.md

@@ -7,7 +7,7 @@
 
 Long-term memory MCP server for OpenCode — stores preferences, lessons, and usage history in a single local SQLite file (100% local, no external API) so the AI can "remember and adapt" to the user through context-based learning.
 
-**Status:** v2.0.0 — a temporal, conflict-aware, hybrid-retrieval memory engine. 11 MCP tools, 12 passing test suites. Non-destructive schema migration from v1 (all v1 data preserved). New in v2: lifecycle states, temporal validity, conflict/dedup resolution, hybrid FTS+vector retrieval (RRF), memory graph, `get_context` assembly, and periodic consolidation.
+**Status:** v2.1.0 — a temporal, conflict-aware, hybrid-retrieval memory engine. 16 MCP tools, 13 passing test suites. Non-destructive schema migration from v1 (all v1 data preserved). New in v2: lifecycle states, temporal validity, conflict/dedup resolution, hybrid FTS+vector retrieval (RRF), memory graph, `get_context` assembly, periodic consolidation, and `link_memory` / `merge_memory` / `update_memory` / `import_memory` / `extract_memories`.
 
 ## Requirements
 
@@ -63,12 +63,12 @@ setx MEMORY_DB_PATH "$PWD/data/memory.db"
 ```
 OpenCode ──┬─ Plugin learning-capture (Bun)  ── auto-captures prompts/tool/error into DB
             │                                   └─ injects profile back into context on compaction
-             └─ MCP th-memory-mcp (Node.js stdio)  ── 11 tools read/write the same SQLite DB
+             └─ MCP th-memory-mcp (Node.js stdio)  ── 16 tools read/write the same SQLite DB
                                                       ▲
                                Global instructions (memory-protocol.md) teach the AI to use the tools
 ```
 
-See [design.md](design.md) for full details.
+See [ARCHITECTURE_v2.md](ARCHITECTURE_v2.md) for the full architecture spec.
 
 ## Why th-memory-mcp?
 
@@ -78,7 +78,7 @@ LLMs don't remember you between sessions — every new chat starts blank. th-mem
 - **100% local & private** — a single SQLite file, no cloud, no external API. Secrets are filtered before anything is stored.
 - **Low overhead** — each tool call is capped (latency < 10 ms, bounded output size) and the AI only queries memory when it's actually useful, so it never bloats your context.
 - **Resilient** — every tool degrades gracefully; if the DB is unavailable the AI keeps working instead of crashing.
-- **Open & extensible** — MIT licensed, 11 documented tools, a rule-based distill, and an auto-capture plugin you can adapt.
+- **Open & extensible** — MIT licensed, 16 documented tools, a rule-based distill, and an auto-capture plugin you can adapt.
 
 ## Works with other harnesses
 
@@ -89,7 +89,7 @@ our hooks bridge; Codex and Cursor use the tools manually (no hook runtime yet).
 
 | Feature | OpenCode | Claude Code | Qwen Code | Codex | Cursor |
 |---|---|---|---|---|---|
-| 11 MCP tools | ✅ | ✅ | ✅ | ✅ | ✅ |
+| 16 MCP tools | ✅ | ✅ | ✅ | ✅ | ✅ |
 | Auto-capture (background) | ✅ plugin | ✅ [hooks](CLAUDE_CODE_HOOKS.md) | ⚠️ adapter | ❌ manual | ❌ Rules |
 | Profile injection | ✅ compaction | ✅ UserPromptSubmit | ❌ `get_profile` | ❌ `get_profile` | ❌ `get_profile` |
 | Local semantic search | ✅ (v2.0) | ✅ (v2.0) | ✅ (v2.0) | ✅ (v2.0) | ✅ (v2.0) |
@@ -148,9 +148,9 @@ anywhere is readable everywhere.
 | `node test/consolidation.test.mjs` | test clustering + derived memories |
 | `node test/benchmark.test.mjs` | latency benchmark over 300 memories |
 | `node test/security.test.mjs` | injection / safety checks |
-| `node test/smoke.mjs` | end-to-end smoke test over JSON-RPC (11 tools) |
+| `node test/smoke.mjs` | end-to-end smoke test over JSON-RPC (16 tools) |
 
-## Tools (11)
+## Tools (16)
 
 | Tool | Description |
 |------|-------------|
@@ -165,6 +165,11 @@ anywhere is readable everywhere.
 | `export_memory` | export memory to JSON under `data/exports/` only (filename auto-sanitized) |
 | `get_context` | assemble relevant memories for the current task via hybrid retrieval (+ optional graph expansion) with token budgeting |
 | `consolidate` | cluster similar memories via embedding similarity; optionally create derived/consolidated memories linked via `derived_from` |
+| `link_memory` | create a typed relationship between two memories in the graph (supports/contradicts/supersedes/derived_from/related_to/caused_by/depends_on) |
+| `merge_memory` | merge a duplicate/near-duplicate into a canonical memory (source becomes superseded, provenance in `metadata.merged_from`) |
+| `update_memory` | update mutable fields in place, or create a superseding memory when `content` changes (set `supersede=false` to edit in place) |
+| `import_memory` | import memories from JSON (validates type, dedupes against existing, never overwrites blindly); dry-run by default, `apply=true` to insert |
+| `extract_memories` | scan recent captured interactions for memory-intent phrases and propose memory candidates (deterministic, no LLM); dry-run by default, `apply=true` to create (source=captured) |
 
 ## Install with OpenCode
 

package/README.th.md

@@ -7,7 +7,7 @@
 
 MCP server ความจำระยะยาวสำหรับ OpenCode — เก็บ preferences, lessons, ประวัติการใช้งาน ลง SQLite ไฟล์เดียว (local 100%, ไม่มี external API) เพื่อให้ AI "จำและปรับตัว" กับผู้ใช้ผ่าน context-based learning
 
-**สถานะ:** v2.0.0 — engine ความจำแบบ temporal, conflict-aware, hybrid-retrieval 11 MCP tools, 12 ชุดเทสผ่าน อัปเกรด schema แบบ non-destructive จาก v1 (ข้อมูล v1 ทั้งหมดถูกเก็บรักษา) ฟีเจอร์ใหม่ใน v2: lifecycle states, temporal validity, การแก้ conflict/dedup, hybrid FTS+vector retrieval (RRF), memory graph, ประกอบ `get_context`, และ consolidation
+**สถานะ:** v2.1.0 — engine ความจำแบบ temporal, conflict-aware, hybrid-retrieval 16 MCP tools, 13 ชุดเทสผ่าน อัปเกรด schema แบบ non-destructive จาก v1 (ข้อมูล v1 ทั้งหมดถูกเก็บรักษา) ฟีเจอร์ใหม่ใน v2: lifecycle states, temporal validity, การแก้ conflict/dedup, hybrid FTS+vector retrieval (RRF), memory graph, ประกอบ `get_context`, consolidation, และ `link_memory` / `merge_memory` / `update_memory` / `import_memory` / `extract_memories`
 
 > English: [README.md](README.md)
 
@@ -65,12 +65,12 @@ setx MEMORY_DB_PATH "$PWD/data/memory.db"
 ```
 OpenCode ──┬─ Plugin learning-capture (Bun)  ── จับ prompt/tool/error ลง DB อัตโนมัติ
             │                                   └─ ฉีด profile กลับ context ตอน compaction
-             └─ MCP th-memory-mcp (Node.js stdio)  ── tools 11 ตัว อ่าน/เขียน SQLite เดียวกัน
+              └─ MCP th-memory-mcp (Node.js stdio)  ── tools 16 ตัว อ่าน/เขียน SQLite เดียวกัน
                                                       ▲
                                Global instructions (memory-protocol.md) สอน AI ใช้ tools
 ```
 
-รายละเอียดเต็มอยู่ใน [design.md](design.md) — คู่มืออัปเกรดจาก v1 ดูได้ที่ [MIGRATION_v2.md](MIGRATION_v2.md)
+รายละเอียดสถาปัตยกรรมเต็มอยู่ใน [ARCHITECTURE_v2.md](ARCHITECTURE_v2.md) — คู่มืออัปเกรดจาก v1 ดูได้ที่ [MIGRATION_v2.md](MIGRATION_v2.md)
 
 ## ทำไมต้องใช้ th-memory-mcp?
 
@@ -107,7 +107,7 @@ LLM ไม่ได้จำคุณข้าม session — แชทใหม
 | `node test/security.test.mjs` | ตรวจการ injection / ความปลอดภัย |
 | `node test/smoke.mjs` | smoke test end-to-end ผ่าน JSON-RPC (11 tools) |
 
-## Tools (11)
+## Tools (16)
 
 | Tool | คำอธิบาย |
 |------|----------|
@@ -122,6 +122,11 @@ LLM ไม่ได้จำคุณข้าม session — แชทใหม
 | `export_memory` | export ความจำเป็น JSON ลง `data/exports/` เท่านั้น (sanitize filename ให้เอง) |
 | `get_context` | ประกอบความจำที่เกี่ยวข้องกับงานปัจจุบันผ่าน hybrid retrieval (+ ขยายผ่าน memory graph ได้) พร้อม token budgeting |
 | `consolidate` | จัดคลัสเตอร์ความจำที่คล้ายกันด้วย embedding cosine และสร้าง derived/consolidated memory ที่ผูกด้วย `derived_from` ได้ |
+| `link_memory` | สร้างความสัมพันธ์แบบมีประเภทระหว่างความจำสองอันในกราฟ |
+| `merge_memory` | รวมความจำที่ซ้ำเข้ากับความจำหลัก (ต้นทางถูก superseded, เก็บ provenance ไว้ใน `metadata.merged_from`) |
+| `update_memory` | อัปเดตฟิลด์ที่เปลี่ยนได้แบบไม่เปลี่ยนตัวตน หรือสร้างความจำแทนที่เมื่อ `content` เปลี่ยน (ตั้ง `supersede=false` เพื่อแก้ในที่) |
+| `import_memory` | นำเข้าความจำจาก JSON (ตรวจสอบ type, dedup กับของเดิม, ไม่เขียนทับแบบมืดบอด); ค่าเริ่มต้น dry-run, ตั้ง `apply=true` เพื่อเพิ่ม |
+| `extract_memories` | สแกน interactions ล่าสุดหาเจตนาบันทึกความจำ และเสนอ/สร้างความจำ (ไม่ใช้ LLM); ค่าเริ่มต้น dry-run, ตั้ง `apply=true` เพื่อสร้าง (source=captured) |
 
 ## ติดตั้งกับ OpenCode
 

package/dist/index.js

@@ -12,6 +12,11 @@ import { recentInteractionsInput, getRecentInteractionsHandler, } from "./tools/
 import { exportMemoryInput, exportMemoryHandler, } from "./tools/export_memory.js";
 import { contextInput, contextHandler } from "./tools/context.js";
 import { consolidateInput, consolidateHandler } from "./tools/consolidate.js";
+import { linkMemoryInput, linkMemoryHandler } from "./tools/link_memory.js";
+import { mergeMemoryInput, mergeMemoryHandler } from "./tools/merge_memory.js";
+import { updateMemoryInput, updateMemoryHandler } from "./tools/update_memory.js";
+import { importMemoryInput, importMemoryHandler } from "./tools/import_memory.js";
+import { extractMemoriesInput, extractMemoriesHandler } from "./tools/extract_memories.js";
 import { VERSION } from "./lib/config.js";
 const server = new McpServer({
     name: "th-memory-mcp",
@@ -72,6 +77,31 @@ server.registerTool("consolidate", {
     description: "Cluster similar memories via embedding similarity and optionally create derived/consolidated memories linked via 'derived_from'. Use during periodic consolidation.",
     inputSchema: consolidateInput,
 }, (args) => consolidateHandler(args));
+server.registerTool("link_memory", {
+    title: "Link two memories",
+    description: "Create a typed relationship between two memories in the graph (supports/contradicts/supersedes/derived_from/related_to/caused_by/depends_on).",
+    inputSchema: linkMemoryInput,
+}, (args) => linkMemoryHandler(args));
+server.registerTool("merge_memory", {
+    title: "Merge memories",
+    description: "Merge a duplicate/near-duplicate memory into a canonical one. The source becomes superseded and provenance is recorded in metadata.merged_from.",
+    inputSchema: mergeMemoryInput,
+}, (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).",
+    inputSchema: updateMemoryInput,
+}, (args) => updateMemoryHandler(args));
+server.registerTool("import_memory", {
+    title: "Import memories",
+    description: "Import memories from a JSON array or a .json file inside data/exports/. Validates type, dedupes against existing memories, and never overwrites active memory blindly. Dry-run by default; pass apply=true to insert.",
+    inputSchema: importMemoryInput,
+}, (args) => importMemoryHandler(args));
+server.registerTool("extract_memories", {
+    title: "Extract memories from interactions",
+    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));
 async function main() {
     const transport = new StdioServerTransport();
     await server.connect(transport);

package/dist/tools/extract_memories.js

@@ -0,0 +1,90 @@
+import { z } from "zod";
+import { db, ok, err } from "../db/index.js";
+import { createMemory } from "../db/repositories/memories.js";
+import { deduplicate } from "../memory/deduplicator.js";
+// Deterministic, LLM-free intent heuristics (spec §19 "optional extraction").
+// Scans captured interactions and proposes memory candidates. Safe by default:
+// dry-run proposes; pass apply=true to actually create memories (source=captured).
+const INTENT_PATTERNS = [
+    { re: /(?:remember|จำไว้ว่า|บันทึกว่า)\s+(?:that\s+)?(.+)/i, type: "FACT" },
+    {
+        re: /(?:i prefer|my preference is|ผมชอบ|ฉันชอบ|เราชอบ)\s+(.+)/i,
+        type: "PREFERENCE",
+    },
+    {
+        re: /(?:i use|เราใช้|ฉันใช้)\s+([^\s,]+)\s+(?:for|ในการ|เพื่อ)\s+(.+)/i,
+        type: "PREFERENCE",
+    },
+    {
+        re: /(?:don'?t use|ห้ามใช้|อย่าใช้)\s+(.+?)(?:,\s*(?:use|ใช้)\s+(.+))?/i,
+        type: "LESSON",
+    },
+    {
+        re: /(?:instead|use)\s+(.+?)\s+(?:rather than|แทน)\s+(.+)/i,
+        type: "LESSON",
+    },
+];
+export const extractMemoriesInput = {
+    limit: z
+        .number()
+        .int()
+        .min(1)
+        .max(200)
+        .optional()
+        .describe("Max recent interactions to scan (default 50)"),
+    kind: z
+        .enum(["prompt", "tool_call", "error"])
+        .optional()
+        .describe("Interaction kind to scan (default prompt)"),
+    apply: z
+        .boolean()
+        .optional()
+        .describe("Create the proposed memories (default false = propose only)"),
+};
+export function extractMemoriesHandler(args) {
+    try {
+        const limit = args.limit ?? 50;
+        const kind = args.kind ?? "prompt";
+        const rows = db
+            .prepare("SELECT id, content FROM interactions WHERE kind = ? ORDER BY id DESC LIMIT ?")
+            .all(kind, limit);
+        const candidates = [];
+        for (const r of rows) {
+            for (const p of INTENT_PATTERNS) {
+                const m = r.content.match(p.re);
+                if (m) {
+                    const clause = (m[1] || "").trim();
+                    if (clause.length >= 3) {
+                        candidates.push({
+                            interactionId: r.id,
+                            type: p.type,
+                            content: clause,
+                        });
+                    }
+                    break;
+                }
+            }
+        }
+        const distinct = candidates.filter((c) => deduplicate(c.type, c.content).verdict === "distinct");
+        if (args.apply === true) {
+            let n = 0;
+            for (const c of distinct) {
+                createMemory({
+                    type: c.type,
+                    content: c.content,
+                    source: "captured",
+                });
+                n++;
+            }
+            return ok(`extracted and created ${n} memories from interactions (${candidates.length} candidates, ${candidates.length - distinct.length} duplicates skipped)`);
+        }
+        const preview = distinct
+            .slice(0, 20)
+            .map((c) => `[${c.type}] ${c.content}`)
+            .join("\n") || "(no candidates)";
+        return ok(`proposed ${distinct.length} memory candidate(s) from ${rows.length} ${kind} interactions (dry-run; pass apply=true to create):\n${preview}`);
+    }
+    catch (e) {
+        return err(e instanceof Error ? e.message : String(e));
+    }
+}

package/dist/tools/import_memory.js

@@ -0,0 +1,95 @@
+import { z } from "zod";
+import { readFileSync } from "node:fs";
+import { join, dirname, resolve, sep } from "node:path";
+import { DB_PATH, ok, err } from "../db/index.js";
+import { createMemory } from "../db/repositories/memories.js";
+import { deduplicate } from "../memory/deduplicator.js";
+import { MEMORY_TYPES } from "../memory/types.js";
+import { EXPORTS_DIRNAME } from "../lib/config.js";
+export const importMemoryInput = {
+    file: z
+        .string()
+        .optional()
+        .describe("Path to a .json export file (must be inside data/exports/)"),
+    json: z
+        .string()
+        .optional()
+        .describe("Inline JSON: an array of memory objects, or { memories: [...] }"),
+    apply: z
+        .boolean()
+        .optional()
+        .describe("Actually insert memories (default false = dry run, just report)"),
+};
+export function importMemoryHandler(args) {
+    try {
+        let raw;
+        if (args.json) {
+            raw = args.json;
+        }
+        else if (args.file) {
+            const exportDir = join(dirname(DB_PATH), EXPORTS_DIRNAME);
+            const full = resolve(args.file);
+            const allowed = resolve(exportDir);
+            if (!full.startsWith(allowed + sep))
+                return err(`file must be inside ${exportDir}`);
+            if (!full.endsWith(".json"))
+                return err("file must end with .json");
+            raw = readFileSync(full, "utf8");
+        }
+        else {
+            return err("provide either file or json");
+        }
+        let parsed;
+        try {
+            parsed = JSON.parse(raw);
+        }
+        catch {
+            return err("invalid JSON");
+        }
+        const items = Array.isArray(parsed)
+            ? parsed
+            : Array.isArray(parsed.memories)
+                ? (parsed.memories)
+                : [];
+        let wouldImport = 0;
+        let skipped = 0;
+        let invalid = 0;
+        const log = [];
+        for (const it of items) {
+            if (!it ||
+                typeof it.content !== "string" ||
+                !MEMORY_TYPES.includes(it.type)) {
+                invalid++;
+                continue;
+            }
+            const dup = deduplicate(it.type, it.content);
+            if (dup.verdict === "duplicate") {
+                skipped++;
+                log.push(`skip duplicate -> existing ${dup.existingId}`);
+                continue;
+            }
+            wouldImport++;
+            if (args.apply === true) {
+                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,
+                    projectId: typeof it.projectId === "string" ? it.projectId : null,
+                    sessionId: typeof it.sessionId === "string" ? it.sessionId : null,
+                    validFrom: typeof it.validFrom === "string" ? it.validFrom : null,
+                    validUntil: typeof it.validUntil === "string" ? it.validUntil : null,
+                    metadata: it.metadata ?? null,
+                });
+            }
+        }
+        const mode = args.apply === true ? "applied" : "dry-run";
+        const summary = `import ${mode}: ${wouldImport} to import, ${skipped} duplicate(s) skipped, ${invalid} invalid`;
+        return ok(log.length ? `${summary}\n${log.join("\n")}` : summary);
+    }
+    catch (e) {
+        return err(e instanceof Error ? e.message : String(e));
+    }
+}

package/dist/tools/link_memory.js

@@ -0,0 +1,31 @@
+import { z } from "zod";
+import { ok, err } from "../db/index.js";
+import { linkMemories } from "../core/graph-engine.js";
+import { getMemoryById } from "../db/repositories/memories.js";
+import { LINK_RELATIONS } from "../memory/types.js";
+export const linkMemoryInput = {
+    sourceId: z.number().int().describe("Source memory id"),
+    targetId: z.number().int().describe("Target memory id"),
+    relation: z
+        .enum(LINK_RELATIONS)
+        .describe("Link relation (supports/contradicts/supersedes/derived_from/related_to/caused_by/depends_on)"),
+};
+export function linkMemoryHandler(args) {
+    try {
+        const src = getMemoryById(args.sourceId);
+        const tgt = getMemoryById(args.targetId);
+        if (!src)
+            return err(`source memory ${args.sourceId} not found`);
+        if (!tgt)
+            return err(`target memory ${args.targetId} not found`);
+        if (src.status === "deleted" || tgt.status === "deleted")
+            return err("cannot link deleted memories");
+        if (src.id === tgt.id)
+            return err("cannot link a memory to itself");
+        linkMemories(args.sourceId, args.targetId, args.relation);
+        return ok(`linked memory ${args.sourceId} -[${args.relation}]-> ${args.targetId}`);
+    }
+    catch (e) {
+        return err(e instanceof Error ? e.message : String(e));
+    }
+}

package/dist/tools/merge_memory.js

@@ -0,0 +1,49 @@
+import { z } from "zod";
+import { db, nowISO, ok, err } from "../db/index.js";
+import { getMemoryById } from "../db/repositories/memories.js";
+import { supersede } from "../core/lifecycle-engine.js";
+export const mergeMemoryInput = {
+    sourceId: z
+        .number()
+        .int()
+        .describe("Memory to merge away (becomes superseded)"),
+    targetId: z
+        .number()
+        .int()
+        .describe("Canonical memory to keep (becomes active)"),
+};
+function mergeMetadata(existing, mergedId) {
+    let obj = {};
+    if (existing) {
+        try {
+            obj = JSON.parse(existing);
+        }
+        catch {
+            obj = {};
+        }
+    }
+    const from = Array.isArray(obj.merged_from) ? obj.merged_from : [];
+    from.push(mergedId);
+    obj.merged_from = from;
+    return JSON.stringify(obj);
+}
+export function mergeMemoryHandler(args) {
+    try {
+        const src = getMemoryById(args.sourceId);
+        const tgt = getMemoryById(args.targetId);
+        if (!src)
+            return err(`source memory ${args.sourceId} not found`);
+        if (!tgt)
+            return err(`target memory ${args.targetId} not found`);
+        if (src.id === tgt.id)
+            return err("cannot merge a memory into itself");
+        if (src.status === "deleted" || tgt.status === "deleted")
+            return err("cannot merge deleted memories");
+        db.prepare("UPDATE memories SET metadata = ?, updated_at = ? WHERE id = ?").run(mergeMetadata(tgt.metadata, src.id), nowISO(), tgt.id);
+        supersede(src.id, tgt.id);
+        return ok(`merged memory ${src.id} into ${tgt.id} (source superseded, provenance recorded in metadata.merged_from)`);
+    }
+    catch (e) {
+        return err(e instanceof Error ? e.message : String(e));
+    }
+}

package/dist/tools/update_memory.js

@@ -0,0 +1,98 @@
+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";
+export const updateMemoryInput = {
+    id: z.number().int().describe("Memory id to update"),
+    content: z
+        .string()
+        .max(2000)
+        .optional()
+        .describe("New content. When provided, a superseding memory is created (supersede=true) unless supersede=false."),
+    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(),
+    validUntil: z
+        .string()
+        .nullable()
+        .optional()
+        .describe("ISO timestamp or null to clear"),
+    metadata: z.unknown().optional().describe("New metadata object (replaces)"),
+    supersede: z
+        .boolean()
+        .optional()
+        .describe("If content changes, create a superseding memory instead of editing in place (default true)"),
+};
+export function updateMemoryHandler(args) {
+    try {
+        const mem = getMemoryById(args.id);
+        if (!mem)
+            return err(`memory ${args.id} not found`);
+        if (mem.status === "deleted")
+            return err("cannot update a deleted memory");
+        const supersedeContent = args.content !== undefined && (args.supersede ?? true);
+        if (supersedeContent) {
+            const newId = createMemory({
+                type: mem.type,
+                content: args.content,
+                summary: args.summary ?? mem.summary,
+                source: mem.source,
+                confidence: args.confidence ?? mem.confidence,
+                importance: args.importance ?? mem.importance,
+                salience: mem.salience,
+                projectId: mem.project_id,
+                sessionId: mem.session_id,
+                validFrom: mem.valid_from,
+                validUntil: args.validUntil !== undefined ? args.validUntil : mem.valid_until,
+                metadata: args.metadata !== undefined
+                    ? args.metadata
+                    : mem.metadata
+                        ? JSON.parse(mem.metadata)
+                        : null,
+            });
+            supersede(mem.id, newId);
+            return ok(`created superseding memory id=${newId} for old id=${mem.id} (old now superseded)`);
+        }
+        const sets = [];
+        const vals = [];
+        if (args.summary !== undefined) {
+            sets.push("summary = ?");
+            vals.push(args.summary);
+        }
+        if (args.importance !== undefined) {
+            sets.push("importance = ?");
+            vals.push(args.importance);
+        }
+        if (args.confidence !== undefined) {
+            sets.push("confidence = ?");
+            vals.push(args.confidence);
+        }
+        if (args.validUntil !== undefined) {
+            sets.push("valid_until = ?");
+            vals.push(args.validUntil);
+        }
+        if (args.metadata !== undefined) {
+            sets.push("metadata = ?");
+            vals.push(JSON.stringify(args.metadata));
+        }
+        if (args.content !== undefined) {
+            sets.push("content = ?");
+            vals.push(args.content);
+        }
+        if (sets.length === 0)
+            return ok(`no mutable fields provided; memory ${mem.id} unchanged`);
+        sets.push("updated_at = ?");
+        vals.push(nowISO());
+        vals.push(mem.id);
+        db.prepare(`UPDATE memories SET ${sets.join(", ")} WHERE id = ?`).run(...vals);
+        if (args.content !== undefined) {
+            const m = getMemoryById(mem.id);
+            if (m)
+                syncMemoryIndex(m.id, m.type, m.content);
+        }
+        return ok(`updated memory ${mem.id} in place`);
+    }
+    catch (e) {
+        return err(e instanceof Error ? e.message : String(e));
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "th-memory-mcp",
-  "version": "2.0.0",
+  "version": "2.1.0",
   "mcpName": "io.github.worakorn-prince/th-memory-mcp",
   "description": "Adaptive Memory MCP server - SQLite-backed memory for OpenCode",
   "author": "worakorn-prince",
@@ -17,7 +17,7 @@
     "dist",
     "README.md",
     "LICENSE",
-    "design.md",
+    "ARCHITECTURE_v2.md",
     "opencode.example.json",
     "AGENTS.memory.example.md"
   ],
@@ -26,7 +26,7 @@
     "prepublishOnly": "npm run build",
     "start": "node dist/index.js",
     "inspect": "npx @modelcontextprotocol/inspector node dist/index.js",
-    "test": "npm run build && node test/capture.test.mjs && node test/distill.test.mjs && node test/lifecycle.test.mjs && node test/temporal.test.mjs && node test/conflict.test.mjs && node test/retrieval.test.mjs && node test/graph.test.mjs && node test/context.test.mjs && node test/consolidation.test.mjs && node test/benchmark.test.mjs && node test/security.test.mjs && node test/smoke.mjs",
+    "test": "npm run build && node test/capture.test.mjs && node test/distill.test.mjs && node test/lifecycle.test.mjs && node test/temporal.test.mjs && node test/conflict.test.mjs && node test/retrieval.test.mjs && node test/graph.test.mjs && node test/context.test.mjs && node test/consolidation.test.mjs && node test/benchmark.test.mjs && node test/security.test.mjs && node test/tools_v21.test.mjs && node test/smoke.mjs",
     "distill": "node dist/distill.js",
     "quickstart": "npm run build && node scripts/quickstart.mjs"
   },

package/design.md

@@ -1,98 +0,0 @@
-# th-memory-mcp v2 — Implementation Plan (design.md)
-
-**Source of truth:** `ARCHITECTURE_v2.md` (on GitHub, baseline v1.2.2).
-This file is the working plan for the Building Agent — read it before continuing implementation.
-
-## Goal
-Evolve th-memory-mcp from a structured local memory MCP into a durable, temporal,
-conflict-aware, hybrid-retrieval memory engine. Local-first, offline, SQLite, no
-mandatory cloud/LLM. Keep v1 behavior working during the transition.
-
-## Current v1 state (summary)
-- 9 MCP tools: remember, recall, get_profile, save_lesson, search_history, forget, memory_stats, get_recent_interactions, export_memory.
-- Schema (inline `CREATE TABLE IF NOT EXISTS` in `src/db.ts`): `interactions`, `preferences`, `lessons`, `profile`, FTS5 `search_index`, `embeddings` (BLOB, 512-dim hashing-trick vectors).
-- No migration system; no schema version table.
-- Capture logic triplicated: `src/lib/capture-core.ts`, `src/plugin/learning-capture.ts` (Bun), `scripts/claude-capture.mjs`.
-- Semantic search = full in-memory linear scan over all embeddings every `recall`.
-- Version metadata inconsistent: `package.json` 1.2.2 vs `config.ts` VERSION 1.1.0 vs `smoke.mjs` assertion 1.1.0 (fix in Phase 10).
-
-## Decisions (Phase 1)
-- **Migrations are TS modules** (`src/db/migrations.ts`) exporting an ordered `MIGRATIONS` array + `runMigrations(db)`. Each `up(db)` is idempotent (`CREATE TABLE IF NOT EXISTS`) and tracked in `schema_meta`. This avoids `.sql` file-copy issues under `tsc` while keeping deterministic order (spec allows implementation differences).
-- **Reuse existing `search_index` + `embeddings`** for v2 `memories` (ref_table = `'memories'`). No new FTS table needed.
-- **Non-destructive:** v1 tables (`preferences`, `lessons`, `interactions`, `profile`) are preserved. v2 adds `memories`, `entities`, `relations`, `memory_links`, `schema_meta`.
-- **Backfill (M005):** map `preferences → memories(type=PREFERENCE)`, `lessons → memories(type=LESSON)`, sync FTS+embeddings. Guarded by `v1_backfilled` flag so it runs once. `recall` is unaffected because it filters by `ref_table IN ('preferences','lessons')`.
-- **No dual-write yet.** v1 tools keep writing only to v1 tables. v2 `memories` is seeded by backfill; new v2 tools (later phases) write to `memories`. Dedup/merge of backfilled vs new entries is Phase 4.
-- **Repository layer** (`src/db/repositories/memories.ts`) provides `createMemory`, `getMemoryById`, `setStatus`, `softDelete`, `syncMemoryIndex`, `searchMemories` (FTS + semantic blend, status/project filtering). Not yet wired to a public tool (that is Phase 7 `get_context`).
-
-## Phased roadmap
-See `ARCHITECTURE_v2.md` §35 for the canonical phase list. Status tracked in the session todo list.
-
-## This session (deliverables so far)
-
-### Phase 1 — Core abstraction (DONE)
-- [x] `src/memory/types.ts` — unified `MemoryType`, `SourceType`, `LifecycleState`, `Scope`, `LinkRelation`, `MemoryRecord`.
-- [x] `src/db/migrations.ts` — migration engine + 5 migrations (schema_meta, memories+indexes, entities/relations, memory_links, v1 backfill).
-- [x] `src/db/repositories/memories.ts` — core CRUD + index sync + `searchMemories` (hybrid FTS + semantic blend).
-- [x] `src/db/index.ts` — call `runMigrations(db)` after existing DDL (non-destructive).
-- [x] Build + full test suite green (capture/distill/smoke).
-
-### Phase 2 — Lifecycle engine (DONE)
-- [x] `src/memory/decay.ts` — `recencyFactor`, per-type `DECAY_LAMBDA_BY_TYPE` (policy classes, not constants).
-- [x] `src/memory/source-weights.ts` — `SOURCE_WEIGHTS` map (spec §8).
-- [x] `src/memory/scorer.ts` — `computeSalience` (weighted, configurable), `computeConfidence` (source weight + diminishing returns), `salienceForMemory`.
-- [x] `src/core/lifecycle-engine.ts` — `canTransition`, `transitionStatus`, `reinforce`, `touch`, `supersede` (sets old=superseded, new=active + `supersedes_id` + `memory_links`), `archive`, `softDelete`, `LifecycleError`.
-- [x] `test/lifecycle.test.mjs` — 17 checks (decay, scorer, transitions, supersession, archive). Added to `npm test`.
-
-### Phase 3 — Temporal model (DONE)
-- [x] `src/core/temporal-engine.ts` — `setValidity`, `memoriesValidAt` (point-in-time truth), `supersessionChain` (oldest→newest), `changesBetween` (change detection).
-- [x] `test/temporal.test.mjs` — 7 checks (validity intervals, historical retrieval, supersession chains, change detection). Added to `npm test`.
-
-### Phase 4 — Conflict & dedup (DONE)
-- [x] `src/memory/deduplicator.ts` — `normalizeText`, `findExactMatch`, `findSimilar`, `deduplicate` (spec §11).
-- [x] `src/memory/conflict-resolver.ts` — `isContradiction`, `classifyRelationship` (duplicate/update/contradiction/unrelated), `findRelated`, `resolveConflict` (merge duplicate / supersede update / link contradiction, preserving ambiguous evidence per §12).
-- [x] `test/conflict.test.mjs` — 14 checks. Added to `npm test`.
-- [x] **Bug fix (v1 too):** `src/lib/embed.ts` `serialize`/`deserialize` rewrote with `DataView` + explicit `byteOffset`. Old code used `Buffer.from(buf).buffer` which can carry a non-zero pool `byteOffset`, corrupting vectors (magnitude ~1e37). This silently broke v1 semantic search.
-
-### Phase 5 — Hybrid retrieval (DONE)
-- [x] `src/retrieval/fts.ts` — `ftsSearch` (FTS5 over `search_index`, status/project filters, `ORDER BY rank`).
-- [x] `src/retrieval/vector.ts` — `vectorSearch` (cosine over `embeddings`, floor 0.15, filters).
-- [x] `src/retrieval/fusion.ts` — `rrfFuse` (Reciprocal Rank Fusion, k=60).
-- [x] `src/retrieval/scorer.ts` — `finalScore` (RRF × confidence × importance × recency × scope) + `scopeFactorFor`.
-- [x] `src/core/retrieval-engine.ts` — `retrieve` (FTS + vector → RRF → scoring/rerank → filter → topK).
-- [x] `searchMemories` in repository now delegates to `retrieve` (hybrid). `buildFtsMatch` switched to OR for better recall.
-- [x] `test/retrieval.test.mjs` — 7 checks. Added to `npm test`.
-
-### Phase 6 — Graph engine (DONE)
-- [x] `src/core/graph-engine.ts` — `createEntity` (canonical dedup, aliases in metadata), `addRelation` (source_entity_id/relation/target_entity_id), `linkMemories`, `traverse` (bounded BFS over `memory_links`, maxDepth 1–5, relationFilter), `neighbors`.
-- [x] `test/graph.test.mjs` — 7 checks (linking, bounded traversal depth, relation filter, entity dedup, relation insert). Added to `npm test`.
-- [x] Note: `entities` columns are `(name, canonical_name, type, metadata)`; `relations` use `source_entity_id/relation/target_entity_id`; `memory_links` PK `(source_memory_id, relation, target_memory_id)`.
-
-### Phase 7 — Context engine (DONE)
-- [x] `src/core/context-engine.ts` — `getContext` (hybrid retrieve → optional graph expansion → temporal validity filter → token budgeting/truncation).
-- [x] `src/tools/context.ts` — `contextInput` (zod) + `contextHandler` (returns assembled context text).
-- [x] Wired `get_context` MCP tool into `index.ts` (now 10 tools total).
-- [x] `test/context.test.mjs` — 7 checks (assembly, graph expansion, token budget, temporal validity). Added to `npm test`.
-- [x] Updated `test/smoke.mjs` to expect 10 tools.
-
-### Phase 8 — Consolidation (DONE)
-- [x] `src/core/consolidation-engine.ts` — `clusterMemories` (embedding cosine + union-find), `createDerivedMemory` (type DERIVED, source consolidated, links `derived_from`), `getProvenance`.
-- [x] `src/tools/consolidate.ts` — `consolidateInput` + `consolidateHandler` (read-only cluster listing + optional `derive`).
-- [x] Wired `consolidate` MCP tool into `index.ts` (now 11 tools total).
-- [x] `test/consolidation.test.mjs` — 5 checks. Added to `npm test`.
-- [x] Added `DERIVED` to `MEMORY_TYPES`; added `DERIVED` lambda to `decay.ts`.
-
-### Phase 9 — Benchmark & security suite (DONE)
-- [x] `test/benchmark.test.mjs` — 2 checks (retrieve over 300 memories < 2000ms).
-- [x] `test/security.test.mjs` — 5 checks (FTS injection quoting, safe retrieve, malicious content stored verbatim, extreme budget, parameterized SQL).
-- [x] Both added to `npm test` (now 12 suites).
-
-### Phase 10 — v2 release (DOCS DONE; PUBLISH PENDING USER)
-- [x] `MIGRATION_v2.md` written (non-destructive upgrade guide, rollback notes).
-- [x] `README.md` updated to v2.0.0 (11 tools, v2 architecture, new test scripts).
-- [ ] Version bump to `2.0.0` + `npm publish --otp=CODE` (needs user OTP).
-- [ ] `git commit` + `git push` + GitHub Release v2.0.0 (needs user).
-- [ ] `.\mcp-publisher.exe publish` (Official MCP Registry; needs user GitHub OAuth + OTP).
-- [ ] Glama: claim ownership + sync from GitHub.
-
-## Next
-All v2 engine phases (0–9) complete and tested. Remaining: user-driven release steps above. After release, future work could include automatic entity extraction in consolidation and a periodic auto-consolidate scheduler.