th-memory-mcp 1.2.2 → 2.1.0

package/dist/index.js

@@ -10,6 +10,13 @@ import { forgetInput, forgetHandler } from "./tools/forget.js";
 import { memoryStatsHandler } from "./tools/memory_stats.js";
 import { recentInteractionsInput, getRecentInteractionsHandler, } from "./tools/recent_interactions.js";
 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",
@@ -60,6 +67,41 @@ server.registerTool("export_memory", {
     description: "Export preferences, lessons, profile (and optionally raw interactions) to a JSON file under data/exports/. Only writes inside that directory. Returns the file path, size in bytes and a JSON preview.",
     inputSchema: exportMemoryInput,
 }, (args) => exportMemoryHandler(args));
+server.registerTool("get_context", {
+    title: "Get assembled context",
+    description: "Assemble relevant memories for the current task via hybrid retrieval (+ optional memory-graph expansion), with token budgeting. Use to load memory into context before a task.",
+    inputSchema: contextInput,
+}, (args) => contextHandler(args));
+server.registerTool("consolidate", {
+    title: "Consolidate memories",
+    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/lib/embed.js

@@ -53,13 +53,16 @@ export function cosine(a, b) {
     return dot;
 }
 export function serialize(vec) {
-    const copy = new Float32Array(EMBED_DIM);
-    copy.set(vec);
-    return Buffer.from(copy.buffer);
+    const buf = Buffer.alloc(EMBED_DIM * 4);
+    const dv = new DataView(buf.buffer, buf.byteOffset, buf.byteLength);
+    for (let i = 0; i < EMBED_DIM; i++)
+        dv.setFloat32(i * 4, vec[i] ?? 0, true);
+    return buf;
 }
 export function deserialize(buf) {
     const out = new Float32Array(EMBED_DIM);
-    const ab = Buffer.from(buf).buffer.slice(0, EMBED_DIM * 4);
-    out.set(new Float32Array(ab));
+    const view = new DataView(buf.buffer, buf.byteOffset, Math.min(EMBED_DIM * 4, buf.byteLength));
+    for (let i = 0; i < EMBED_DIM; i++)
+        out[i] = view.getFloat32(i * 4, true);
     return out;
 }

package/dist/memory/conflict-resolver.js

@@ -0,0 +1,125 @@
+import { db, nowISO } from "../db/index.js";
+import { getMemoryById } from "../db/repositories/memories.js";
+import { supersede, reinforce, softDelete } from "../core/lifecycle-engine.js";
+import { embed, cosine, deserialize } from "../lib/embed.js";
+const SIM_DUP = 0.9;
+const SIM_UPDATE = 0.45;
+const SIM_CONTRA = 0.35;
+const RELATED_THRESHOLD = 0.35;
+const NEGATION = [
+    /\bnot\b/i,
+    /\bnever\b/i,
+    /\bno longer\b/i,
+    /\bstop\b/i,
+    /\bavoid\b/i,
+    /\bdon'?t\b/i,
+    /\binstead\b/i,
+    /\bbut\b/i,
+    /\bhowever\b/i,
+    /ไม่/i,
+    /ห้าม/i,
+    /เลิก/i,
+    /อย่า/i,
+];
+export function isContradiction(a, b) {
+    const na = NEGATION.some((re) => re.test(a));
+    const nb = NEGATION.some((re) => re.test(b));
+    if (na === nb)
+        return false; // both or neither negated -> not a simple contradiction
+    const ta = tokenSet(a);
+    const tb = tokenSet(b);
+    let overlap = 0;
+    for (const t of ta)
+        if (tb.has(t))
+            overlap++;
+    return overlap >= 2;
+}
+function tokenSet(s) {
+    return new Set(s.toLowerCase().match(/[a-z0-9ก-์]+/gi) ?? []);
+}
+export function classifyRelationship(candidate, relatedId) {
+    const rel = getMemoryById(relatedId);
+    if (!rel)
+        return "unrelated";
+    const relVecRow = db
+        .prepare("SELECT vec FROM embeddings WHERE ref_table='memories' AND ref_id=?")
+        .get(relatedId);
+    if (!relVecRow)
+        return "unrelated";
+    const score = cosine(embed(candidate.content), deserialize(relVecRow.vec));
+    if (score >= SIM_DUP)
+        return "duplicate";
+    if (isContradiction(candidate.content, rel.content) && score >= SIM_CONTRA) {
+        return "contradiction";
+    }
+    if (score >= SIM_UPDATE)
+        return "update";
+    return "unrelated";
+}
+// Find best related active/non-archived memory of the same type for a candidate.
+export function findRelated(candidate, threshold = RELATED_THRESHOLD) {
+    const vec = embed(candidate.content);
+    const rows = db
+        .prepare("SELECT ref_id, vec FROM embeddings WHERE ref_table = 'memories'")
+        .all();
+    let best;
+    for (const r of rows) {
+        if (candidate.id && r.ref_id === candidate.id)
+            continue;
+        const m = getMemoryById(r.ref_id);
+        if (!m ||
+            m.type !== candidate.type ||
+            m.status === "deleted" ||
+            m.status === "archived")
+            continue;
+        const score = cosine(vec, deserialize(r.vec));
+        if (score >= threshold && (!best || score > best.score)) {
+            best = { id: r.ref_id, score };
+        }
+    }
+    return best;
+}
+// Resolve a candidate against existing memories. If candidate.id is set (memory
+// already created), it will be reconciled (superseded / linked / merged).
+export function resolveConflict(candidate) {
+    const related = findRelated(candidate);
+    if (!related)
+        return { relation: "unrelated", score: 0, action: "none" };
+    const relation = classifyRelationship(candidate, related.id);
+    if (relation === "duplicate" && candidate.id !== undefined) {
+        reinforce(related.id);
+        softDelete(candidate.id);
+        return {
+            relation,
+            relatedId: related.id,
+            score: related.score,
+            action: "merged",
+        };
+    }
+    if (relation === "update" && candidate.id !== undefined) {
+        supersede(related.id, candidate.id);
+        return {
+            relation,
+            relatedId: related.id,
+            score: related.score,
+            action: "superseded",
+        };
+    }
+    if (relation === "contradiction" && candidate.id !== undefined) {
+        db.prepare(`INSERT INTO memory_links (source_memory_id, relation, target_memory_id, confidence, created_at)
+       VALUES (?, 'contradicts', ?, 0.8, ?)
+       ON CONFLICT(source_memory_id, relation, target_memory_id) DO UPDATE SET confidence = 0.8`).run(candidate.id, related.id, nowISO());
+        return {
+            relation,
+            relatedId: related.id,
+            score: related.score,
+            action: "linked_contradiction",
+        };
+    }
+    return {
+        relation,
+        relatedId: related.id,
+        score: related.score,
+        action: "none",
+    };
+}

package/dist/memory/decay.js

@@ -0,0 +1,30 @@
+// Per-type decay rate (lambda) for recency = exp(-lambda * age_days).
+// Lower lambda => slower decay (more durable). Policy classes, not fixed constants.
+export const DECAY_LAMBDA_BY_TYPE = {
+    CONSTRAINT: 0.0005,
+    DECISION: 0.001,
+    LESSON: 0.001,
+    PREFERENCE: 0.001,
+    FACT: 0.005,
+    GOAL: 0.01,
+    PROCEDURE: 0.005,
+    EPISODE: 0.01,
+    RELATION: 0.005,
+    PROFILE: 0.0,
+    DERIVED: 0.002,
+};
+export function decayLambdaFor(type) {
+    return DECAY_LAMBDA_BY_TYPE[type] ?? 0.005;
+}
+export function ageInDays(isoTs, now = new Date()) {
+    const t = new Date(isoTs).getTime();
+    if (Number.isNaN(t))
+        return 0;
+    return Math.max(0, (now.getTime() - t) / 86_400_000);
+}
+export function recencyFactor(isoTs, lambda, now = new Date()) {
+    return Math.exp(-lambda * ageInDays(isoTs, now));
+}
+export function recencyFactorFor(type, isoTs, now = new Date()) {
+    return recencyFactor(isoTs, decayLambdaFor(type), now);
+}

package/dist/memory/deduplicator.js

@@ -0,0 +1,51 @@
+import { embed, cosine, deserialize } from "../lib/embed.js";
+import { db } from "../db/index.js";
+export function normalizeText(text) {
+    return text
+        .toLowerCase()
+        .normalize("NFKC")
+        .replace(/\s+/g, " ")
+        .replace(/[^\p{L}\p{N}\s]/gu, "")
+        .trim();
+}
+// Exact / normalized match on content within the same type.
+export function findExactMatch(type, content) {
+    const norm = normalizeText(content);
+    const rows = db
+        .prepare("SELECT id, content FROM memories WHERE type = ? AND status != 'deleted'")
+        .all(type);
+    for (const r of rows) {
+        if (normalizeText(r.content) === norm)
+            return r.id;
+    }
+    return undefined;
+}
+// Semantic similarity against existing memories of the same type.
+export function findSimilar(type, content, threshold = 0.82) {
+    const vec = embed(content);
+    const rows = db
+        .prepare("SELECT ref_id, vec FROM embeddings WHERE ref_table = 'memories'")
+        .all();
+    let best;
+    for (const r of rows) {
+        const m = db
+            .prepare("SELECT type, status FROM memories WHERE id = ?")
+            .get(r.ref_id);
+        if (!m || m.type !== type || m.status === "deleted")
+            continue;
+        const score = cosine(vec, deserialize(r.vec));
+        if (score >= threshold && (!best || score > best.score)) {
+            best = { id: r.ref_id, score };
+        }
+    }
+    return best;
+}
+export function deduplicate(type, content) {
+    const exact = findExactMatch(type, content);
+    if (exact !== undefined)
+        return { verdict: "duplicate", existingId: exact, score: 1 };
+    const sim = findSimilar(type, content);
+    if (sim)
+        return { verdict: "duplicate", existingId: sim.id, score: sim.score };
+    return { verdict: "distinct", score: 0 };
+}

package/dist/memory/scorer.js

@@ -0,0 +1,44 @@
+import { sourceWeight } from "./source-weights.js";
+import { recencyFactorFor } from "./decay.js";
+export const DEFAULT_SALIENCE_WEIGHTS = {
+    semanticRelevance: 0.3,
+    importance: 0.2,
+    confidence: 0.15,
+    recency: 0.15,
+    accessFrequency: 0.1,
+    projectRelevance: 0.1,
+};
+export function clamp01(x) {
+    if (Number.isNaN(x))
+        return 0;
+    return Math.min(1, Math.max(0, x));
+}
+export function computeSalience(input) {
+    const w = { ...DEFAULT_SALIENCE_WEIGHTS, ...(input.weights ?? {}) };
+    const raw = w.semanticRelevance * clamp01(input.relevance) +
+        w.importance * clamp01(input.importance) +
+        w.confidence * clamp01(input.confidence) +
+        w.recency * clamp01(input.recency) +
+        w.accessFrequency * clamp01(input.accessFrequency) +
+        w.projectRelevance * clamp01(input.projectRelevance);
+    return clamp01(raw);
+}
+export function computeConfidence(input) {
+    const w = sourceWeight(input.source);
+    const n = Math.max(0, input.confirmations);
+    const next = w + (1 - w) * (1 - 1 / (1 + n));
+    return clamp01(next);
+}
+// Convenience: build salience from a memory record + query relevance.
+export function salienceForMemory(params) {
+    const recency = recencyFactorFor(params.type, params.updatedAt);
+    const accessFrequency = clamp01(params.accessCount / (params.maxAccess ?? 10));
+    return computeSalience({
+        relevance: params.relevance,
+        importance: params.importance,
+        confidence: params.confidence,
+        recency,
+        accessFrequency,
+        projectRelevance: params.projectRelevance ?? 0.5,
+    });
+}

package/dist/memory/source-weights.js

@@ -0,0 +1,13 @@
+// Recommended source weights for confidence (spec §8). Defaults, not immutable constants.
+export const SOURCE_WEIGHTS = {
+    explicit: 1.0,
+    corrected: 0.95,
+    system: 0.8,
+    consolidated: 0.75,
+    imported: 0.7,
+    inferred: 0.5,
+    captured: 0.3,
+};
+export function sourceWeight(source) {
+    return SOURCE_WEIGHTS[source] ?? 0.5;
+}

package/dist/memory/types.js

@@ -0,0 +1,41 @@
+export const MEMORY_TYPES = [
+    "FACT",
+    "PREFERENCE",
+    "GOAL",
+    "DECISION",
+    "CONSTRAINT",
+    "LESSON",
+    "PROCEDURE",
+    "EPISODE",
+    "RELATION",
+    "PROFILE",
+    "DERIVED",
+];
+export const SOURCE_TYPES = [
+    "explicit",
+    "corrected",
+    "inferred",
+    "captured",
+    "consolidated",
+    "imported",
+    "system",
+];
+export const LIFECYCLE_STATES = [
+    "new",
+    "active",
+    "reinforced",
+    "stale",
+    "superseded",
+    "archived",
+    "deleted",
+];
+export const SCOPES = ["GLOBAL", "USER", "PROJECT", "SESSION"];
+export const LINK_RELATIONS = [
+    "supports",
+    "contradicts",
+    "supersedes",
+    "derived_from",
+    "related_to",
+    "caused_by",
+    "depends_on",
+];

package/dist/retrieval/fts.js

@@ -0,0 +1,22 @@
+import { db, buildFtsMatch } from "../db/index.js";
+export function ftsSearch(query, opts = {}) {
+    const limit = Math.min(Math.max(opts.limit ?? 50, 1), 200);
+    const statusClause = opts.includeArchived
+        ? ""
+        : "AND m.status NOT IN ('deleted','archived')";
+    const projectClause = opts.projectId
+        ? "AND (m.project_id = @projectId OR m.project_id IS NULL)"
+        : "";
+    const rows = db
+        .prepare(`SELECT m.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} ${projectClause}
+       ORDER BY rank
+       LIMIT @limit`)
+        .all({
+        match: buildFtsMatch(query),
+        limit,
+        projectId: opts.projectId,
+    });
+    return rows.map((r, i) => ({ id: r.id, rank: i + 1 }));
+}

package/dist/retrieval/fusion.js

@@ -0,0 +1,11 @@
+// Reciprocal Rank Fusion (spec §13.1): RRF(m) = Σ 1 / (k + rank_i(m))
+export function rrfFuse(lists, k = 60) {
+    const scores = new Map();
+    for (const list of lists) {
+        for (const item of list) {
+            const rrf = 1 / (k + item.rank);
+            scores.set(item.id, (scores.get(item.id) ?? 0) + rrf);
+        }
+    }
+    return scores;
+}

package/dist/retrieval/scorer.js

@@ -0,0 +1,19 @@
+import { clamp01 } from "../memory/scorer.js";
+// spec §13.1: final_score = RRF * confidence * importance_factor * recency_factor * scope_factor
+export function finalScore(input) {
+    const importanceFactor = 0.5 + 0.5 * clamp01(input.importance); // 0.5..1.0
+    return (input.rrf *
+        clamp01(input.confidence) *
+        importanceFactor *
+        clamp01(input.recency) *
+        clamp01(input.scopeFactor));
+}
+export function scopeFactorFor(mem, projectId) {
+    if (!projectId)
+        return 0.8; // global query: project-scoped memories slightly favored
+    if (mem.project_id === projectId)
+        return 1.0;
+    if (mem.project_id === null)
+        return 0.7;
+    return 0.3; // different project
+}

package/dist/retrieval/vector.js

@@ -0,0 +1,29 @@
+import { db } from "../db/index.js";
+import { embed, cosine, deserialize } from "../lib/embed.js";
+export function vectorSearch(query, opts = {}) {
+    const limit = Math.min(Math.max(opts.limit ?? 50, 1), 200);
+    const floor = opts.floor ?? 0.15;
+    const topicVec = embed(query);
+    const rows = db
+        .prepare("SELECT ref_id, vec FROM embeddings WHERE ref_table = 'memories'")
+        .all();
+    const statusOk = (id) => {
+        const m = db
+            .prepare("SELECT status, project_id FROM memories WHERE id = ?")
+            .get(id);
+        if (!m)
+            return false;
+        if (!opts.includeArchived &&
+            (m.status === "deleted" || m.status === "archived"))
+            return false;
+        if (opts.projectId &&
+            !(m.project_id === opts.projectId || m.project_id === null))
+            return false;
+        return true;
+    };
+    return rows
+        .map((r) => ({ id: r.ref_id, score: cosine(topicVec, deserialize(r.vec)) }))
+        .filter((r) => r.score >= floor && statusOk(r.id))
+        .sort((a, b) => b.score - a.score)
+        .slice(0, limit);
+}

package/dist/tools/consolidate.js

@@ -0,0 +1,63 @@
+import { z } from "zod";
+import { clusterMemories, createDerivedMemory, } from "../core/consolidation-engine.js";
+import { db, ok } from "../db/index.js";
+export const consolidateInput = {
+    threshold: z
+        .number()
+        .min(0)
+        .max(1)
+        .optional()
+        .describe("Cosine similarity threshold for clustering (default 0.7)"),
+    projectId: z.string().nullable().optional().describe("Scope to a project"),
+    minClusterSize: z
+        .number()
+        .int()
+        .min(2)
+        .max(20)
+        .optional()
+        .describe("Minimum members to report a cluster (default 2)"),
+    derive: z
+        .boolean()
+        .optional()
+        .describe("Create a derived memory for each cluster"),
+};
+export function consolidateHandler(args) {
+    const clusters = clusterMemories({
+        threshold: typeof args.threshold === "number" ? args.threshold : undefined,
+        projectId: typeof args.projectId === "string" ? args.projectId : null,
+        minClusterSize: typeof args.minClusterSize === "number"
+            ? args.minClusterSize
+            : undefined,
+    });
+    const lines = [];
+    const derivedIds = [];
+    for (const c of clusters) {
+        const contents = c.map((id) => {
+            const m = db
+                .prepare("SELECT content FROM memories WHERE id = ?")
+                .get(id);
+            return `  - [${id}] ${m?.content ?? "?"}`;
+        });
+        lines.push(`Cluster (${c.length}):\n${contents.join("\n")}`);
+        if (args.derive === true) {
+            const summary = c
+                .map((id) => {
+                const m = db
+                    .prepare("SELECT content FROM memories WHERE id = ?")
+                    .get(id);
+                return m?.content ?? "";
+            })
+                .join(" | ");
+            const did = createDerivedMemory({
+                content: `Consolidated: ${summary}`,
+                sourceIds: c,
+            });
+            derivedIds.push(did);
+            lines.push(`  => derived memory id=${did}`);
+        }
+    }
+    const header = `Found ${clusters.length} cluster(s)${args.derive === true
+        ? `, created ${derivedIds.length} derived memories`
+        : ""}`;
+    return ok(header + "\n\n" + (lines.join("\n\n") || "(no clusters)"));
+}

package/dist/tools/context.js

@@ -0,0 +1,55 @@
+import { z } from "zod";
+import { getContext } from "../core/context-engine.js";
+import { ok } from "../db/index.js";
+export const contextInput = {
+    query: z
+        .string()
+        .optional()
+        .describe("Optional focus query to seed hybrid retrieval"),
+    projectId: z
+        .string()
+        .nullable()
+        .optional()
+        .describe("Scope context to a project"),
+    sessionId: z.string().nullable().optional(),
+    limit: z
+        .number()
+        .int()
+        .min(1)
+        .max(50)
+        .optional()
+        .describe("Number of seed memories (default 10)"),
+    maxTokens: z
+        .number()
+        .int()
+        .min(100)
+        .max(8000)
+        .optional()
+        .describe("Token budget for assembled context (default 2000)"),
+    includeHistory: z
+        .boolean()
+        .optional()
+        .describe("Include superseded/archived memories"),
+    includeGraph: z
+        .boolean()
+        .optional()
+        .describe("Expand seeds with memory-graph neighbors"),
+};
+export function contextHandler(args) {
+    const res = getContext({
+        query: typeof args.query === "string" ? args.query : "",
+        projectId: typeof args.projectId === "string" ? args.projectId : null,
+        sessionId: typeof args.sessionId === "string" ? args.sessionId : null,
+        limit: typeof args.limit === "number" ? args.limit : undefined,
+        maxTokens: typeof args.maxTokens === "number" ? args.maxTokens : undefined,
+        includeHistory: args.includeHistory === true,
+        includeGraph: args.includeGraph === true,
+    });
+    const lines = res.memories.map((m) => {
+        const meta = m.metadata ? ` meta=${m.metadata}` : "";
+        const tag = m.viaGraph ? " [graph]" : "";
+        return `[${m.id}] (${m.type}/${m.status})${tag} ${m.content}${meta}`;
+    });
+    const header = `Context for "${res.query || "<no query>"}" — ${res.memories.length} memories, ~${res.tokenEstimate} tokens${res.truncated ? " (truncated to budget)" : ""}`;
+    return ok(header + "\n\n" + (lines.join("\n") || "(no memories)"));
+}

package/dist/tools/export_memory.js

@@ -1,7 +1,7 @@
 import { mkdirSync, writeFileSync, statSync } from "node:fs";
 import { join, dirname } from "node:path";
 import { z } from "zod";
-import { db, DB_PATH, nowISO, truncate, ok, err, } from "../db.js";
+import { db, DB_PATH, nowISO, truncate, ok, err, } from "../db/index.js";
 import { VERSION, EXPORTS_DIRNAME } from "../lib/config.js";
 export const exportMemoryInput = {
     includeInteractions: z