th-memory-mcp 1.1.0 → 1.2.0

package/README.md

@@ -1,8 +1,13 @@
 # th-memory-mcp
 
+[![npm version](https://img.shields.io/npm/v/th-memory-mcp.svg)](https://www.npmjs.com/package/th-memory-mcp)
+[![npm downloads](https://img.shields.io/npm/dm/th-memory-mcp.svg)](https://www.npmjs.com/package/th-memory-mcp)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+[![Node](https://img.shields.io/badge/node-%3E%3D20-brightgreen.svg)](https://nodejs.org)
+
 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:** v1.1.0 — all 4 phases implemented, tests passing 70/70 assertions (smoke 53 + capture 8 + distill 9)
+**Status:** v1.2.0 — all 4 phases implemented, tests passing 70/70 assertions (smoke 53 + capture 8 + distill 9). New: local semantic/vector search blended into `recall`, and full auto-capture on Claude Code (hooks) plus ready configs for Codex & Cursor.
 
 ## Requirements
 
@@ -75,6 +80,48 @@ LLMs don't remember you between sessions — every new chat starts blank. th-mem
 - **Resilient** — every tool degrades gracefully; if the DB is unavailable the AI keeps working instead of crashing.
 - **Open & extensible** — MIT licensed, 9 documented tools, a rule-based distill, and an auto-capture plugin you can adapt.
 
+## Works with other harnesses
+
+th-memory-mcp is a standard MCP server, so the 9 tools run anywhere MCP-over-stdio
+is supported. Full **auto-capture** (background prompt/tool/error capture + profile
+injection) needs a hook runtime — OpenCode has it built in; Claude Code gets it via
+our hooks bridge; Codex and Cursor use the tools manually (no hook runtime yet).
+
+| Feature | OpenCode | Claude Code | Codex | Cursor |
+|---|---|---|---|---|
+| 9 MCP tools | ✅ | ✅ | ✅ | ✅ |
+| Auto-capture (background) | ✅ plugin | ✅ [hooks](CLAUDE_CODE_HOOKS.md) | ❌ manual | ❌ Rules |
+| Profile injection | ✅ compaction | ✅ UserPromptSubmit | ❌ `get_profile` | ❌ `get_profile` |
+| Local semantic search | ✅ (v1.2) | ✅ (v1.2) | ✅ (v1.2) | ✅ (v1.2) |
+
+- **Claude Code:** see [CLAUDE_CODE_HOOKS.md](CLAUDE_CODE_HOOKS.md) — drop-in hooks replicate the OpenCode plugin (capture + profile injection on `UserPromptSubmit`/`PreCompact`, rule-based distill on `SessionEnd`).
+- **Codex:** see [CODEX_SETUP.md](CODEX_SETUP.md)
+- **Cursor:** see [CURSOR_SETUP.md](CURSOR_SETUP.md)
+
+All harnesses share one SQLite file via `MEMORY_DB_PATH`, so memory captured
+anywhere is readable everywhere.
+
+## Comparison with rekal
+
+[rekal](https://github.com/janbjorge/rekal) is the closest alternative (Python,
+single SQLite file, hybrid search). How th-memory-mcp differs:
+
+| | th-memory-mcp | rekal |
+|---|---|---|
+| Runtime | Node ≥20 (`better-sqlite3`) | Python 3.11+ |
+| Search | FTS5 keyword + **local vector blend** (v1.2, no model download) | BM25 + vector (384-dim local) + recency |
+| Memory model | `preference` (confidence) / `lesson` (situation→mistake→correction) / `profile` / `interactions` | flat `fact` |
+| Auto-capture | OpenCode plugin + Claude hooks (capture + `PreCompact` + `SessionEnd` distill) | Claude plugin (SessionStart/UserPromptSubmit/`PreCompact`/`SessionEnd`) |
+| Harness coverage | OpenCode, Claude Code, Codex, Cursor | Claude Code, Codex, OpenCode, Cursor |
+| Thai / i18n | ✅ Thai tokenization in distill | English-centric |
+| Secret filter | ✅ built-in | not specified |
+| Weight | lightweight, zero native extras | needs embedding model (local) |
+
+th-memory-mcp's edge: structured **lessons** for corrections, confidence scoring,
+first-class **Thai** support, secret filtering, and a dependency-free local vector
+search that stays 100% offline. rekal's edge: transformer-grade semantic embeddings
+and a one-command plugin marketplace install.
+
 ## Scripts
 
 | Command | Description |

package/README.th.md

@@ -1,5 +1,10 @@
 # th-memory-mcp
 
+[![npm version](https://img.shields.io/npm/v/th-memory-mcp.svg)](https://www.npmjs.com/package/th-memory-mcp)
+[![npm downloads](https://img.shields.io/npm/dm/th-memory-mcp.svg)](https://www.npmjs.com/package/th-memory-mcp)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+[![Node](https://img.shields.io/badge/node-%3E%3D20-brightgreen.svg)](https://nodejs.org)
+
 MCP server ความจำระยะยาวสำหรับ OpenCode — เก็บ preferences, lessons, ประวัติการใช้งาน ลง SQLite ไฟล์เดียว (local 100%, ไม่มี external API) เพื่อให้ AI "จำและปรับตัว" กับผู้ใช้ผ่าน context-based learning
 
 **สถานะ:** v1.1.0 — อิมพลีเมนต์ครบ 4 Phase, tests ผ่าน 70/70 assertions (smoke 53 + capture 8 + distill 9)
@@ -19,6 +24,8 @@ MCP server ความจำระยะยาวสำหรับ OpenCode
 
 **ทางที่เร็วที่สุด:** หลัง clone ให้รัน `npm run quickstart` — มันจะ build, ต่อไฟล์ `opencode.json`, วาง plugin และตั้ง `MEMORY_DB_PATH` ให้ในคำสั่งเดียว ขั้นตอนด้านล่างคือสิ่งที่สคริปต์ทำ (ใช้ได้หากอยากควบคุมเองทีละขั้น)
 
+**ติดตั้งผ่าน npm (อีกทางเลือก):** ติดตั้ง server แบบ global ด้วย `npm install -g th-memory-mcp` (หรือรันทันทีด้วย `npx th-memory-mcp`) แล้วชี้ `command` ของ `mcp` ใน `opencode.json` ไปที่ `th-memory-mcp` แทน `dist/index.js` ที่ build แล้ว plugin auto-capture ยังคงมาจาก repo นี้ (คัดลอก `src/plugin/learning-capture.ts` ตามขั้นตอน 4 ด้านล่าง)
+
 ```bash
 # 1. Clone และ build
 git clone https://github.com/worakorn-prince/th-memory-mcp.git

package/dist/db.js

@@ -2,6 +2,7 @@ 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";
 export const DB_PATH = process.env.MEMORY_DB_PATH ?? DEFAULT_DB_PATH;
 function initDb() {
@@ -56,6 +57,13 @@ CREATE TABLE IF NOT EXISTS profile (
 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)
+);
 `);
 export function nowISO() {
     return new Date().toISOString();
@@ -78,6 +86,20 @@ export function syncSearchIndex(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 }] };
 }

package/dist/lib/embed.js

@@ -0,0 +1,69 @@
+export const EMBED_DIM = 512;
+const THAI = /[ก-์]/;
+function fnv1a(str) {
+    let h = 0x811c9dc5;
+    for (let i = 0; i < str.length; i++) {
+        h ^= str.charCodeAt(i);
+        h = Math.imul(h, 0x01000193);
+    }
+    return h >>> 0;
+}
+function hashToken(token) {
+    return fnv1a(token) % EMBED_DIM;
+}
+function tokenize(text) {
+    const lower = text.toLowerCase();
+    const tokens = [];
+    const matches = lower.match(/[a-z0-9ก-์]+/gi);
+    if (matches) {
+        for (const m of matches)
+            tokens.push(m);
+    }
+    const chars = Array.from(lower.replace(/\s+/g, ""));
+    if (chars.length >= 3) {
+        for (let i = 0; i < chars.length - 2; i++) {
+            tokens.push("g:" + chars.slice(i, i + 3).join(""));
+        }
+    }
+    else if (chars.length > 0) {
+        tokens.push("g:" + chars.join(""));
+    }
+    return tokens;
+}
+export function embed(text) {
+    const vec = new Float32Array(EMBED_DIM);
+    const tokens = tokenize(text || "");
+    if (tokens.length === 0)
+        return vec;
+    for (const t of tokens) {
+        const idx = hashToken(t);
+        vec[idx] = (vec[idx] ?? 0) + 1;
+    }
+    let norm = 0;
+    for (let i = 0; i < EMBED_DIM; i++)
+        norm += (vec[i] ?? 0) * (vec[i] ?? 0);
+    norm = Math.sqrt(norm) || 1;
+    for (let i = 0; i < EMBED_DIM; i++)
+        vec[i] = (vec[i] ?? 0) / norm;
+    return vec;
+}
+export function cosine(a, b) {
+    let dot = 0;
+    for (let i = 0; i < EMBED_DIM; i++)
+        dot += (a[i] ?? 0) * (b[i] ?? 0);
+    return dot;
+}
+export function serialize(vec) {
+    const copy = new Float32Array(EMBED_DIM);
+    copy.set(vec);
+    return Buffer.from(copy.buffer);
+}
+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));
+    return out;
+}
+export function hasThai(text) {
+    return THAI.test(text);
+}

package/dist/tools/forget.js

@@ -1,5 +1,5 @@
 import { z } from "zod";
-import { db, removeSearchIndex, ok, err } from "../db.js";
+import { db, removeSearchIndex, removeEmbedding, ok, err, } from "../db.js";
 export const forgetInput = {
     target_id: z
         .number()
@@ -61,11 +61,13 @@ export async function forgetHandler(args) {
                 if (kind === "preferences") {
                     delPreference.run(id);
                     removeSearchIndex("preferences", id);
+                    removeEmbedding("preferences", id);
                     removed.push(`preference #${id}`);
                 }
                 else if (kind === "lessons") {
                     delLesson.run(id);
                     removeSearchIndex("lessons", id);
+                    removeEmbedding("lessons", id);
                     removed.push(`lesson #${id}`);
                 }
                 else {

package/dist/tools/lesson.js

@@ -1,5 +1,6 @@
 import { z } from "zod";
-import { db, nowISO, syncSearchIndex, ok, err, } from "../db.js";
+import { db, nowISO, syncSearchIndex, upsertEmbedding, ok, err, } from "../db.js";
+import { embed } from "../lib/embed.js";
 export const saveLessonInput = {
     situation: z.string().min(1).max(1000).describe("The original situation/context"),
     mistake: z.string().min(1).max(1000).describe("What was done wrong"),
@@ -12,6 +13,7 @@ export async function saveLessonHandler(args) {
         const res = insertLesson.run(args.situation, args.mistake, args.correction, nowISO());
         const id = Number(res.lastInsertRowid);
         syncSearchIndex("lessons", id, args.situation.slice(0, LESSON_TITLE_MAX), `${args.situation} | mistake: ${args.mistake} -> correction: ${args.correction}`);
+        upsertEmbedding("lessons", id, embed(`${args.situation} ${args.mistake} ${args.correction}`));
         return ok(`lesson saved (lesson id=${id})`);
     }
     catch (e) {

package/dist/tools/recall.js

@@ -1,5 +1,6 @@
 import { z } from "zod";
-import { db, buildFtsMatch, escapeLike, truncate, ok, err, } from "../db.js";
+import { db, buildFtsMatch, escapeLike, truncate, getAllEmbeddings, ok, err, } from "../db.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"),
     limit: z
@@ -12,22 +13,46 @@ export const recallInput = {
 };
 const RECALL_BUDGET = 2000;
 const RECENT_INTERACTIONS_LIMIT = 20;
+const SEMANTIC_FLOOR = 0.15;
 const searchIndexed = db.prepare("SELECT ref_table, ref_id, title, body FROM search_index WHERE search_index MATCH ? AND ref_table IN ('preferences','lessons') LIMIT ?");
 const recentInteractions = db.prepare(`SELECT ts, kind, content FROM interactions WHERE content LIKE ? ESCAPE '\\' ORDER BY ts DESC LIMIT ${RECENT_INTERACTIONS_LIMIT}`);
+const prefById = db.prepare("SELECT category, key, value FROM preferences WHERE id = ?");
+const lessonById = db.prepare("SELECT situation, mistake, correction FROM lessons WHERE id = ?");
+function prefLine(id) {
+    const r = prefById.get(id);
+    if (!r)
+        return null;
+    return `- ${truncate(`${r.category}/${r.key}`, 120)} | ${truncate(`${r.key}: ${r.value}`, 200)}`;
+}
+function lessonLine(id) {
+    const r = lessonById.get(id);
+    if (!r)
+        return null;
+    return `- ${truncate(r.situation, 120)} | ${truncate(`mistake: ${r.mistake} -> correction: ${r.correction}`, 300)}`;
+}
 export async function recallHandler(args) {
     try {
         const limit = args.limit;
         const parts = [];
+        const seen = new Set();
         let prefLines = "";
         let lessonLines = "";
         try {
             const rows = searchIndexed.all(buildFtsMatch(args.topic), limit);
             for (const r of rows) {
                 if (r.ref_table === "preferences") {
-                    prefLines += `- ${truncate(r.title, 120)} | ${truncate(r.body, 200)}\n`;
+                    const line = prefLine(r.ref_id);
+                    if (line) {
+                        prefLines += line + "\n";
+                        seen.add(`p:${r.ref_id}`);
+                    }
                 }
                 else if (r.ref_table === "lessons") {
-                    lessonLines += `- ${truncate(r.title, 120)} | ${truncate(r.body, 300)}\n`;
+                    const line = lessonLine(r.ref_id);
+                    if (line) {
+                        lessonLines += line + "\n";
+                        seen.add(`l:${r.ref_id}`);
+                    }
                 }
             }
         }
@@ -37,6 +62,43 @@ export async function recallHandler(args) {
             prefLines = "";
             lessonLines = "";
         }
+        // Semantic blend: surface vector neighbors missed by keyword search.
+        try {
+            const topicVec = embed(args.topic);
+            const all = getAllEmbeddings();
+            const scored = all
+                .map((row) => ({
+                table: row.ref_table,
+                id: row.ref_id,
+                score: cosine(topicVec, deserialize(row.vec)),
+            }))
+                .filter((x) => x.score >= SEMANTIC_FLOOR)
+                .sort((a, b) => b.score - a.score)
+                .slice(0, limit);
+            for (const x of scored) {
+                const key = `${x.table[0]}:${x.id}`;
+                if (seen.has(key))
+                    continue;
+                if (x.table === "preferences") {
+                    const line = prefLine(x.id);
+                    if (line) {
+                        prefLines += line + "\n";
+                        seen.add(key);
+                    }
+                }
+                else if (x.table === "lessons") {
+                    const line = lessonLine(x.id);
+                    if (line) {
+                        lessonLines += line + "\n";
+                        seen.add(key);
+                    }
+                }
+            }
+        }
+        catch (e) {
+            const msg = e instanceof Error ? e.message : String(e);
+            console.error("[recall] semantic search failed:", msg);
+        }
         let interactionLines = "";
         try {
             const like = `%${escapeLike(args.topic)}%`;

package/dist/tools/remember.js

@@ -1,5 +1,6 @@
 import { z } from "zod";
-import { db, nowISO, syncSearchIndex, ok, err, } from "../db.js";
+import { db, nowISO, syncSearchIndex, upsertEmbedding, ok, err, } from "../db.js";
+import { embed } from "../lib/embed.js";
 export const rememberInput = {
     category: z
         .enum(["work_style", "coding_pref", "language", "domain", "other"])
@@ -29,6 +30,7 @@ export async function rememberHandler(args) {
             confidence = CONFIDENCE_INITIAL;
         }
         syncSearchIndex("preferences", id, `${args.category}/${args.key}`, `${args.key}: ${args.value}`);
+        upsertEmbedding("preferences", id, embed(`${args.category} ${args.key} ${args.value}`));
         return ok(`remembered [${args.category}] ${args.key} = ${args.value} (preference id=${id}, confidence=${confidence.toFixed(2)})`);
     }
     catch (e) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "th-memory-mcp",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "description": "Adaptive Memory MCP server - SQLite-backed memory for OpenCode",
   "author": "worakorn-prince",
   "repository": {