th-memory-mcp 1.2.2 → 2.1.0

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/forget.js

@@ -1,5 +1,5 @@
 import { z } from "zod";
-import { db, removeSearchIndex, removeEmbedding, ok, err, } from "../db.js";
+import { db, removeSearchIndex, removeEmbedding, ok, err, } from "../db/index.js";
 export const forgetInput = {
     target_id: z
         .number()

package/dist/tools/history.js

@@ -1,5 +1,5 @@
 import { z } from "zod";
-import { db, escapeLike, truncate, ok, err, } from "../db.js";
+import { db, escapeLike, truncate, ok, err, } from "../db/index.js";
 export const searchHistoryInput = {
     query: z.string().min(1).max(500).describe("Text to search in past prompts"),
     limit: z

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/lesson.js

@@ -1,5 +1,5 @@
 import { z } from "zod";
-import { db, nowISO, syncSearchIndex, upsertEmbedding, ok, err, } from "../db.js";
+import { db, nowISO, syncSearchIndex, upsertEmbedding, ok, err, } from "../db/index.js";
 import { embed } from "../lib/embed.js";
 export const saveLessonInput = {
     situation: z.string().min(1).max(1000).describe("The original situation/context"),

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/memory_stats.js

@@ -1,5 +1,5 @@
 import { statSync } from "node:fs";
-import { db, DB_PATH, truncate, ok, err, } from "../db.js";
+import { db, DB_PATH, truncate, ok, err, } from "../db/index.js";
 import { CAPTURE_KINDS } from "../lib/capture-core.js";
 export const STATS_BUDGET = 1500;
 const kindCounts = db.prepare("SELECT kind, COUNT(*) AS n FROM interactions GROUP BY kind");

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/profile.js

@@ -1,4 +1,4 @@
-import { db, truncate, ok, err, } from "../db.js";
+import { db, truncate, ok, err, } from "../db/index.js";
 export const PROFILE_BUDGET = 3000;
 const PROFILE_SECTION_MAX = 400;
 const PREF_CATEGORY_MAX = 30;

package/dist/tools/recall.js

@@ -1,5 +1,5 @@
 import { z } from "zod";
-import { db, buildFtsMatch, escapeLike, truncate, getAllEmbeddings, ok, err, } from "../db.js";
+import { db, buildFtsMatch, escapeLike, truncate, getAllEmbeddings, ok, err, } from "../db/index.js";
 import { embed, cosine, deserialize } from "../lib/embed.js";
 export const recallInput = {
     topic: z.string().min(1).max(500).describe("Topic to recall from memory"),

package/dist/tools/recent_interactions.js

@@ -1,5 +1,5 @@
 import { z } from "zod";
-import { db, truncate, ok, err } from "../db.js";
+import { db, truncate, ok, err } from "../db/index.js";
 import { CAPTURE_KINDS, } from "../lib/capture-core.js";
 export const recentInteractionsInput = {
     limit: z

package/dist/tools/remember.js

@@ -1,5 +1,5 @@
 import { z } from "zod";
-import { db, nowISO, syncSearchIndex, upsertEmbedding, ok, err, } from "../db.js";
+import { db, nowISO, syncSearchIndex, upsertEmbedding, ok, err, } from "../db/index.js";
 import { embed } from "../lib/embed.js";
 export const rememberInput = {
     category: z

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,46 +1,46 @@
-{
-  "name": "th-memory-mcp",
-  "version": "1.2.2",
-  "mcpName": "io.github.worakorn-prince/th-memory-mcp",
-  "description": "Adaptive Memory MCP server - SQLite-backed memory for OpenCode",
-  "author": "worakorn-prince",
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/worakorn-prince/th-memory-mcp.git"
-  },
-  "type": "module",
-  "main": "dist/index.js",
-  "bin": {
-    "th-memory-mcp": "dist/index.js"
-  },
-  "files": [
-    "dist",
-    "README.md",
-    "LICENSE",
-    "design.md",
-    "opencode.example.json",
-    "AGENTS.memory.example.md"
-  ],
-  "scripts": {
-    "build": "tsc",
-    "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/smoke.mjs",
-    "distill": "node dist/distill.js",
-    "quickstart": "npm run build && node scripts/quickstart.mjs"
-  },
-  "engines": {
-    "node": ">=20"
-  },
-  "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.0.0",
-    "better-sqlite3": "^12.0.0",
-    "zod": "^3.25.0"
-  },
-  "devDependencies": {
-    "@types/better-sqlite3": "^7.6.0",
-    "@types/node": "^22.0.0",
-    "typescript": "^5.6.0"
-  }
-}
+{
+  "name": "th-memory-mcp",
+  "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",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/worakorn-prince/th-memory-mcp.git"
+  },
+  "type": "module",
+  "main": "dist/index.js",
+  "bin": {
+    "th-memory-mcp": "dist/index.js"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE",
+    "ARCHITECTURE_v2.md",
+    "opencode.example.json",
+    "AGENTS.memory.example.md"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "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/tools_v21.test.mjs && node test/smoke.mjs",
+    "distill": "node dist/distill.js",
+    "quickstart": "npm run build && node scripts/quickstart.mjs"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0",
+    "better-sqlite3": "^12.0.0",
+    "zod": "^3.25.0"
+  },
+  "devDependencies": {
+    "@types/better-sqlite3": "^7.6.0",
+    "@types/node": "^22.0.0",
+    "typescript": "^5.6.0"
+  }
+}