th-memory-mcp 1.1.0

package/AGENTS.memory.example.md

@@ -0,0 +1,41 @@
+# AGENTS.md — Memory Protocol
+
+This project ships an MCP server `th-memory-mcp` that provides long-term memory (local SQLite). Use this protocol every session:
+
+```markdown
+## Memory Protocol
+- Before starting a new/complex task: always call get_profile() and recall("<topic>") first
+- When the user corrects your work or points out a mistake: call save_lesson(situation, mistake, correction) immediately
+- When the user states a fixed preference/requirement: call remember(category, key, value)
+- Never guess the user's preference — if recall finds nothing, ask, then remember it
+- Accept memory commands in both Thai and English (the user may switch languages anytime without warning)
+```
+
+## Tools
+
+| Tool | Use when |
+|------|---------|
+| `remember(category, key, value)` | user states a preference/requirement (category: work_style / coding_pref / language / domain / other) |
+| `recall(topic, limit?)` | before a new task — search preferences + lessons + recent interactions |
+| `get_profile()` | need a user overview (sections + top preferences + recent lessons) |
+| `save_lesson(situation, mistake, correction)` | corrected/called out — record the lesson immediately |
+| `search_history(query, limit?)` | want context from the user's past prompts |
+| `memory_stats()` | need memory stats (counts by kind, DB size, oldest/newest, profile sections) |
+| `get_recent_interactions(limit?, kind?)` | view raw recent interactions (before distill / audit) |
+| `export_memory(includeInteractions?, filename?)` | export all memory to a JSON file under data/exports/ |
+| `forget(target_id)` | delete wrong/stale memory (id from remember/save_lesson output) |
+
+## Smart Distill
+
+When the user asks "summarize memory / distill memory / summarize memory":
+
+1. call `get_recent_interactions(limit=50)`
+2. analyze real patterns — repeated preferences, lessons from corrections, working style
+3. record clear patterns via `remember(category, key, value)` / `save_lesson(...)`
+4. briefly summarize findings to the user
+
+## Setup
+
+1. Copy config from `opencode.example.json` and merge into your `opencode.json`
+2. Restart OpenCode
+3. Test: "Remember that I prefer pnpm" → in a new session ask which package manager you prefer

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 worakorn-prince
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,143 @@
+# th-memory-mcp
+
+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)
+
+## Requirements
+
+- **Node.js >= 20** — the server uses Node-only APIs (the `better-sqlite3` native build and `import.meta.url` resolution) and the MCP SDK requires a modern runtime. CI tests on Node 20.x and 22.x.
+- **npm** — to install dependencies and run the build/test scripts (`npm install`, `npm run build`, `npm test`).
+- **OpenCode** — the host that loads this MCP server and the auto-capture plugin. Any build supporting MCP over stdio + plugins works; the plugin runs on OpenCode's bundled Bun runtime.
+- **OS: Windows / macOS / Linux** — the server is cross-platform (Node). The auto-capture plugin runs wherever OpenCode's Bun runtime runs. Windows note: `MEMORY_DB_PATH` is easiest to set with `setx`; on macOS/Linux use `export` in your shell profile.
+
+No external services, accounts, or API keys are required — everything lives in a single local SQLite file.
+
+## Quick Start
+
+**Fastest path:** after cloning, run `npm run quickstart` — it builds, wires `opencode.json`, deploys the plugin, and sets `MEMORY_DB_PATH` for you in one command. The steps below show exactly what it does (use them if you prefer manual control).
+
+**Install via npm (alternative):** install the server globally with `npm install -g th-memory-mcp` (or run it on demand with `npx th-memory-mcp`), then point the `mcp` `command` in `opencode.json` to `th-memory-mcp` instead of the built `dist/index.js`. The auto-capture plugin still comes from this repo (copy `src/plugin/learning-capture.ts` as described in step 4 below).
+
+```bash
+# 1. Clone and build
+git clone https://github.com/worakorn-prince/th-memory-mcp.git
+cd th-memory-mcp
+npm install
+npm run build
+
+# 2. Share one DB between the server and the plugin
+#    Windows (PowerShell):
+setx MEMORY_DB_PATH "$PWD/data/memory.db"
+#    macOS / Linux (add to your shell profile, e.g. ~/.zshrc):
+# export MEMORY_DB_PATH="$PWD/data/memory.db"
+```
+
+3. Merge this into your `~/.config/opencode/opencode.json` (replace `<REPO>` with the absolute clone path):
+
+```json
+{
+  "instructions": ["<REPO>/AGENTS.memory.example.md"],
+  "mcp": {
+    "memory": {
+      "type": "local",
+      "command": ["node", "<REPO>/dist/index.js"],
+      "enabled": true,
+      "environment": { "MEMORY_DB_PATH": "<REPO>/data/memory.db" }
+    }
+  }
+}
+```
+
+4. (Optional) Auto-capture: copy `src/plugin/learning-capture.ts` → `~/.config/opencode/plugins/`
+5. **Restart OpenCode**
+6. Try it: *"Remember that I prefer pnpm"* → new session → *"What package manager do I prefer?"*
+
+## Architecture
+
+```
+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)  ── 9 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.
+
+## Why th-memory-mcp?
+
+LLMs don't remember you between sessions — every new chat starts blank. th-memory-mcp gives your AI a private, local long-term memory:
+
+- **Context-based learning, not fine-tuning** — it captures your preferences, corrections, and habits, then recalls them into context next time. Same mechanism as the memory features of leading AI products, without sending any data off your machine.
+- **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, 9 documented tools, a rule-based distill, and an auto-capture plugin you can adapt.
+
+## Scripts
+
+| Command | Description |
+|---------|-------------|
+| `npm run build` | compile TypeScript → `dist/` |
+| `npm start` | run the MCP server (stdio) from `dist/index.js` |
+| `npm run distill` | rule-based distill: interactions → profile sections + prune old data (env `RETENTION_DAYS` default 30) |
+| `npm test` | end-to-end smoke test over JSON-RPC (`node test/smoke.mjs`) |
+| `node test/capture.test.mjs` | test capture-core (filter secrets, dedupe, truncate, insert SQL) |
+| `node test/distill.test.mjs` | test distill-core (Thai tokenize, stats, profile sections, prune) |
+
+## Tools (9)
+
+| Tool | Description |
+|------|-------------|
+| `remember` | upsert preference (category+key) — re-saving the same key increases confidence by 0.1 (cap 1.0) |
+| `recall` | search preferences + lessons (FTS5) + recent matching interactions. Use before starting a new task |
+| `get_profile` | user profile overview: profile sections + top preferences + 5 most recent lessons |
+| `save_lesson` | record a lesson learned from a correction (situation / mistake / correction) |
+| `search_history` | search past user prompts by keyword (200-char snippets per row) |
+| `forget` | delete one memory row (preference/lesson/interaction) by id (+type prevents cross-table id clash) |
+| `memory_stats` | memory statistics: counts by kind, DB size, oldest/newest interaction, profile sections |
+| `get_recent_interactions` | list recent raw interactions (filter by kind) — feedstock for Smart Distill |
+| `export_memory` | export memory to JSON under `data/exports/` only (filename auto-sanitized) |
+
+## Install with OpenCode
+
+1. Merge the `mcp` section from [`opencode.example.json`](opencode.example.json) into your `opencode.json` (global or project-level)
+   - **Important:** set `MEMORY_DB_PATH` to the SAME database file for both the server and the plugin (the example uses `<ABSOLUTE_PATH>/th-memory-mcp/data/memory.db`), otherwise the auto-capture plugin writes to a different DB than the one the AI reads
+   - How to set it (pick one):
+     - define it in the mcp `environment` (see example) — covers the MCP server only
+     - **or** set it as a system/user-level environment variable (e.g. `setx MEMORY_DB_PATH "D:/path/to/memory.db"` on Windows) — covers both server and plugin, since the plugin runs in the same process as OpenCode
+2. Attach the global memory rules — add to `opencode.json`:
+   ```json
+   "instructions": ["C:/Users/<user>/.config/opencode/memory-protocol.md"]
+   ```
+   (example rule content is in [`AGENTS.memory.example.md`](AGENTS.memory.example.md) — can be attached at project level instead)
+3. (Optional) Deploy the auto-capture plugin: copy `src/plugin/learning-capture.ts` → `~/.config/opencode/plugins/learning-capture.ts`
+4. **Restart OpenCode** (config loads at startup only)
+5. Test: *"Remember that I prefer pnpm"* → open a new session and ask back
+
+## Daily usage
+
+The AI accepts both Thai and English interchangeably — you can switch languages at any time without warning.
+
+| Example command | Tool / effect |
+|-----------------|---------------|
+| "Remember that..." | `remember` — save a preference |
+| "Summarize memory" / "distill memory" | **Smart Distill** — AI reads `get_recent_interactions`, finds patterns, and saves insights itself |
+| "How is my memory?" / "memory status" | `memory_stats` |
+| "Export memory" / "backup memory" | `export_memory` |
+| "Search history..." | `search_history` |
+| "Forget..." | `forget` |
+
+Long-term care: run `npm run distill` occasionally to summarize stats and prune interactions older than 30 days.
+
+## data/ structure
+
+```
+data/
+├── memory.db          # SQLite (WAL mode) — main DB (+ .db-wal, .db-shm)
+└── exports/           # JSON files from export_memory (writeable only in this dir)
+```
+
+- DB path can be overridden via the `MEMORY_DB_PATH` env var
+- everything in `data/` is git-ignored

package/README.th.md

@@ -0,0 +1,143 @@
+# th-memory-mcp
+
+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)
+
+> English: [README.md](README.md)
+
+## Requirements (ความต้องการระบบ)
+
+- **Node.js >= 20** — server ใช้ API ของ Node โดยเฉพาะ (better-sqlite3 แบบ native build และการหา path ด้วย `import.meta.url`) และ MCP SDK ต้องการ runtime สมัยใหม่ CI ของเราทดสอบบน Node 20.x และ 22.x
+- **npm** — สำหรับติดตั้ง dependencies และรัน build/test (`npm install`, `npm run build`, `npm test`)
+- **OpenCode** — โปรแกรมหลักที่โหลด MCP server นี้และ plugin auto-capture ใช้ OpenCode รุ่นที่รองรับ MCP (stdio) + plugins (plugin รันบน Bun ที่มากับ OpenCode)
+- **OS: Windows / macOS / Linux** — server ข้ามแพลตฟอร์มได้ (Node) plugin auto-capture รันได้ทุกที่ที่มี Bun ของ OpenCode หมายเหตุสำหรับ Windows: ตั้ง `MEMORY_DB_PATH` ง่ายสุดด้วย `setx` ส่วน macOS/Linux ใช้ `export` ใน shell profile
+
+ไม่ต้องมีบริการภายนอก บัญชี หรือ API key — ทุกอย่างอยู่ในไฟล์ SQLite ภายในเครื่อง
+
+## Quick Start (เริ่มใช้งานไว)
+
+**ทางที่เร็วที่สุด:** หลัง clone ให้รัน `npm run quickstart` — มันจะ build, ต่อไฟล์ `opencode.json`, วาง plugin และตั้ง `MEMORY_DB_PATH` ให้ในคำสั่งเดียว ขั้นตอนด้านล่างคือสิ่งที่สคริปต์ทำ (ใช้ได้หากอยากควบคุมเองทีละขั้น)
+
+```bash
+# 1. Clone และ build
+git clone https://github.com/worakorn-prince/th-memory-mcp.git
+cd th-memory-mcp
+npm install
+npm run build
+
+# 2. ให้ server และ plugin ใช้ DB เดียวกัน
+#    Windows (PowerShell):
+setx MEMORY_DB_PATH "$PWD/data/memory.db"
+#    macOS / Linux (เพิ่มใน shell profile เช่น ~/.zshrc):
+# export MEMORY_DB_PATH="$PWD/data/memory.db"
+```
+
+3. นำไป merge ใน `~/.config/opencode/opencode.json` (แทน `<REPO>` ด้วย path เต็มของโฟลเดอร์ที่ clone):
+
+```json
+{
+  "instructions": ["<REPO>/AGENTS.memory.example.md"],
+  "mcp": {
+    "memory": {
+      "type": "local",
+      "command": ["node", "<REPO>/dist/index.js"],
+      "enabled": true,
+      "environment": { "MEMORY_DB_PATH": "<REPO>/data/memory.db" }
+    }
+  }
+}
+```
+
+4. (Optional) เปิด auto-capture: คัดลอก `src/plugin/learning-capture.ts` → `~/.config/opencode/plugins/`
+5. **Restart OpenCode**
+6. ลองใช้: *"จำไว้ว่าฉันชอบใช้ pnpm"* → เปิด session ใหม่ → *"ฉันชอบ package manager อะไร?"*
+
+## สถาปัตยกรรม
+
+```
+OpenCode ──┬─ Plugin learning-capture (Bun)  ── จับ prompt/tool/error ลง DB อัตโนมัติ
+            │                                   └─ ฉีด profile กลับ context ตอน compaction
+            └─ MCP th-memory-mcp (Node.js stdio)  ── tools 9 ตัว อ่าน/เขียน SQLite เดียวกัน
+                                                      ▲
+                               Global instructions (memory-protocol.md) สอน AI ใช้ tools
+```
+
+รายละเอียดเต็มอยู่ใน [design.md](design.md)
+
+## ทำไมต้องใช้ th-memory-mcp?
+
+LLM ไม่ได้จำคุณข้าม session — แชทใหม่ทุกครั้งเริ่มจากศูนย์ th-memory-mcp มอบความจำระยะยาวแบบส่วนตัว ภายในเครื่อง ให้ AI ของคุณ:
+
+- **เรียนรู้แบบ context-based ไม่ใช่ fine-tuning** — จับความชอบ/การถูกแก้/พฤติกรรม ของคุณ แล้วเรียกกลับเข้า context ครั้งหน้า กลไกเดียวกับฟีเจอร์ความจำของ AI ชั้นนำ โดยไม่ส่งข้อมูลออกนอกเครื่อง
+- **local 100% และเป็นส่วนตัว** — ไฟล์ SQLite เดียว ไม่มีคลาวด์ ไม่มี external API มีการกรอง secret ก่อนบันทึกเสมอ
+- **โอเวอร์เฮดต่ำ** — ทุก tool call มีเพดาน (latency < 10 ms, ขนาด output จำกัด) และ AI ค้นความจำเฉพาะตอนจำเป็น จึงไม่บวม context
+- **ทนทาน** — ทุก tool ทำ graceful degradation ถ้า DB ไม่ได้เปิด AI ก็ทำงานต่อได้แทนที่จะพัง
+- **เปิดกว้างและต่อยอดได้** — MIT license, 9 tools ที่อธิบายครบ, มี rule-based distill และ plugin auto-capture ที่คุณปรับแต่งได้
+
+## Scripts
+
+| Command | คำอธิบาย |
+|---------|----------|
+| `npm run build` | compile TypeScript → `dist/` |
+| `npm start` | รัน MCP server (stdio) จาก `dist/index.js` |
+| `npm run distill` | rule-based distill: interactions → profile sections + prune ข้อมูลเก่า (env `RETENTION_DAYS` default 30) |
+| `npm test` | smoke test end-to-end ผ่าน JSON-RPC (`node test/smoke.mjs`) |
+| `node test/capture.test.mjs` | ทดสอบ capture-core (filter secrets, dedupe, truncate, insert SQL) |
+| `node test/distill.test.mjs` | ทดสอบ distill-core (tokenize ไทย, stats, profile sections, prune) |
+
+## Tools (9)
+
+| Tool | คำอธิบาย |
+|------|----------|
+| `remember` | upsert preference (category+key) — ยืนยันซ้ำ confidence +0.1 (cap 1.0) |
+| `recall` | ค้น preferences + lessons (FTS5) + interactions ล่าสุดที่ match ตาม topic |
+| `get_profile` | ภาพรวมผู้ใช้: profile sections + top preferences + lessons ล่าสุด 5 รายการ |
+| `save_lesson` | บันทึกบทเรียนจากการถูกแก้ (situation / mistake / correction) |
+| `search_history` | ค้น prompt เก่าด้วย keyword (snippet 200 chars/รายการ) |
+| `forget` | ลบ row เดียว (preference/lesson/interaction) ตาม id (+type กัน id ชนข้ามตาราง) |
+| `memory_stats` | สถิติความจำ: counts แยก kind, ขนาด DB, oldest/newest interaction, profile sections |
+| `get_recent_interactions` | ดึง interactions ล่าสุดแบบดิบ (กรองตาม kind ได้) — วัตถุดิบของ Smart Distill |
+| `export_memory` | export ความจำเป็น JSON ลง `data/exports/` เท่านั้น (sanitize filename ให้เอง) |
+
+## ติดตั้งกับ OpenCode
+
+1. Merge `mcp` section จาก [`opencode.example.json`](opencode.example.json) เข้า `opencode.json` (global หรือ project-level)
+   - **สำคัญ:** ตั้ง `MEMORY_DB_PATH` ให้ชี้ที่ไฟล์ DB เดียวกันทั้ง server และ plugin (ในตัวอย่างคือ `<ABSOLUTE_PATH>/th-memory-mcp/data/memory.db`) มิฉะนั้น auto-capture plugin จะเขียนลง DB คนละไฟล์กับที่ AI อ่าน
+   - วิธีตั้ง (เลือกหนึ่ง):
+     - กำหนดใน `environment` ของ mcp (ดูตัวอย่าง) — ครอบคลุมเฉพาะ MCP server
+     - **หรือ** กำหนดเป็น environment variable ระดับระบบ/ผู้ใช้ (เช่น `setx MEMORY_DB_PATH "D:/path/to/memory.db"` บน Windows) — ครอบคลุมทั้ง server และ plugin เพราะ plugin รันใน process เดียวกับ OpenCode
+2. ผูกกฎความจำระดับ global — เพิ่มใน `opencode.json`:
+   ```json
+   "instructions": ["C:/Users/<user>/.config/opencode/memory-protocol.md"]
+   ```
+   (ตัวอย่างเนื้อหากฎอยู่ใน [`AGENTS.memory.example.md`](AGENTS.memory.example.md) — ใช้แนบระดับโปรเจกต์แทนได้)
+3. (Optional) Deploy plugin auto-capture: copy `src/plugin/learning-capture.ts` → `~/.config/opencode/plugins/learning-capture.ts`
+4. **Restart OpenCode** (config โหลดตอน start เท่านั้น)
+5. ทดสอบ: *"จำไว้ว่าฉันชอบใช้ pnpm"* → เปิด session ใหม่ถามกลับ
+
+## การใช้งานประจำวัน
+
+AI รองรับสองภาษา (ไทย/อังกฤษ) สลับกันได้ตลอด โดยไม่ต้องแจ้งล่วงหน้า
+
+| ไทย | English | สิ่งที่เกิด |
+|------|---------|-----------|
+| "จำไว้ว่า..." | "Remember that..." | `remember` — บันทึกความชอบ |
+| "สรุปความจำ" / "distill memory" | "Summarize memory" / "distill memory" | **Smart Distill** — AI อ่าน `get_recent_interactions` วิเคราะห์ pattern แล้วบันทึก insight เอง |
+| "ระบบความจำเป็นไงบ้าง" | "How is my memory?" / "memory status" | `memory_stats` |
+| "สำรองความจำ" | "Export memory" / "backup memory" | `export_memory` |
+| "ค้นประวัติ..." | "Search history..." | `search_history` |
+| "ลืม..." | "Forget..." | `forget` |
+
+ดูแลระยะยาว: รัน `npm run distill` เป็นครั้งคราวเพื่อสรุปสถิติ + ลบ interactions เก่าเกิน 30 วัน
+
+## โครงสร้าง data/
+
+```
+data/
+├── memory.db          # SQLite (WAL mode) — DB หลัก (+ .db-wal, .db-shm)
+└── exports/           # ไฟล์ JSON จาก tool export_memory (เขียนได้เฉพาะ dir นี้)
+```
+
+- path ของ DB override ได้ผ่าน env `MEMORY_DB_PATH`
+- ทุกอย่างใน `data/` ถูก git ignore