th-memory-mcp 2.2.4 → 2.2.7

package/ARCHITECTURE_v2.md

@@ -1,7 +1,7 @@
 # th-memory-mcp v2 — Architecture & Implementation Specification
 
 **Status:** ✅ Released — `th-memory-mcp v2.0.0` is published (npm + Official MCP Registry + Glama).  
-**Baseline:** v1.2.2 → **Current:** v2.0.0  
+**Baseline:** v1.2.2 → **Current:** v2.2.7  
 **Primary goal:** evolve th-memory-mcp from a structured local memory MCP into a durable, temporal, conflict-aware, hybrid-retrieval memory engine for AI agents.
 
 > **Audience guide:** End users should read [README.md](README.md) (install, tools, usage). This document is the **canonical architecture & agent-rules spec** for developers and AI coding agents — the single source of truth for structure and behavior. The former `design.md` build log has been folded into §40 Implementation Status.
@@ -16,7 +16,7 @@ The project must retain these v1 properties:
 
 - Local-first and offline by default.
 - SQLite as the primary persistence layer.
-- FTS5 and local semantic search.
+- FTS5 and lexical fuzzy matching (hashed n-gram similarity, 512-dim FNV-1a).
 - Thai/English support.
 - Auto-capture and cross-harness compatibility.
 - Secret filtering and safe export.
@@ -69,7 +69,7 @@ Core operations must work without an LLM:
 
 - persistence
 - FTS search
-- semantic search
+- lexical fuzzy matching (hashed n-gram similarity, 512-dim FNV-1a)
 - metadata filtering
 - scoring
 - RRF fusion
@@ -373,7 +373,9 @@ project_id
 
 The implementation may use a maintained FTS5 virtual table or separate indexes, but every mutation of searchable memory must keep indexes synchronized transactionally where possible.
 
-Local semantic search remains supported. The implementation must preserve the dependency-light/offline property of v1.
+Lexical fuzzy matching (hashed n-gram similarity, 512-dim FNV-1a) remains supported. The implementation must preserve the dependency-light/offline property of v1.
+
+> **Caveat — lexical fuzzy, not concept-level:** The vector signal is lexical fuzzy matching (hashed n-gram similarity, 512-dim FNV-1a) — hashed word tokens + character 3-grams via FNV-1a into 512 dimensions — not transformer / concept-level semantic search. It tolerates minor lexical variation (typos, small edits) but paraphrases that share no token or 3-gram overlap will not be linked by the vector signal (FTS also requires token overlap). Distant paraphrases may therefore remain `unrelated` rather than being classified as `duplicate`/`contradiction`.
 
 ---
 
@@ -591,6 +593,8 @@ final_score =
 
 The exact formula must be benchmarked.
 
+> **Caveat — lexical fuzzy, not concept-level:** The vector signal in this hybrid pipeline is lexical fuzzy matching (hashed n-gram similarity, 512-dim FNV-1a) — hashed word tokens + character 3-grams via FNV-1a into 512 dimensions — not transformer / concept-level semantic search. It tolerates minor lexical variation (typos, small edits) but paraphrases that share no token or 3-gram overlap will not be linked by the vector signal (FTS also requires token overlap), so RRF cannot recover concept-level matches from the vector side alone. The `conflict-resolver` similarity threshold also operates on this lexical signal, so distant paraphrases may be classified as `unrelated` rather than `duplicate`/`contradiction`.
+
 ---
 
 # 14. Graph Retrieval
@@ -705,7 +709,7 @@ Do not expand to dozens of tools. v2.1.0 ships **16 tools** (the original spec t
 
 ### Core / compatibility (carried from v1)
 1. `remember` — store a memory using the unified model (type + metadata)
-2. `recall` — hybrid FTS + semantic search (v1 behavior preserved)
+2. `recall` — hybrid FTS + lexical fuzzy matching (hashed n-gram similarity, 512-dim FNV-1a) (v1 behavior preserved)
 3. `forget` — soft delete by default
 4. `get_profile` — compact profile projection/cache
 5. `search_history` — search raw interactions
@@ -1593,5 +1597,11 @@ All previously-deferred future features are implemented. AI-assisted extraction
 - v2.1.0: implemented and tested locally; publish skipped (superseded by v2.2.0).
 - v2.2.0: fully released — tag + GitHub Release, **npm published** (`th-memory-mcp@2.2.0`), Official MCP Registry auto-ingested from npm (manual `mcp-publisher publish` is redundant and errors `duplicate version`), Glama synced. Only `npm publish` + Glama Sync are required.
 - v2.2.1: Glama quality fix (server failed to start — better-sqlite3 native binding missing under pnpm 10 on Node 24). Added `pnpm.onlyBuiltDependencies: ["better-sqlite3"]` so pnpm runs the install script that downloads the Node 24 prebuild; bumped better-sqlite3 to `^12.9.0`; added `ip-address@^10.2.0` overrides (npm + pnpm) to clear transitive XSS via `@modelcontextprotocol/sdk`. No code changes. Pending `npm publish` + Glama re-test.
+- v2.2.2: baseline for benchmark spec v1.0 (retrieval quality harness initial).
+- v2.2.3: security + performance hardening per `report_checkup.md` (scope-enforced retrieval, graph scope isolation, export/import round-trip, realpath symlink protection, strict import validation, N+1 elimination, cold/ablation benchmark, `MEMORY_RETRIEVAL_MODE` switch — 25/25 tests).
+- v2.2.4: docs — tidy README badge layout.
+- v2.2.5: docs — sync README/design/ARCHITECTURE/PUBLISH to project (lexical fuzzy matching, 25 suites, benchmark viewer, result versioning) + SECURITY.md.
+- v2.2.6: docs — translate all docs to English except `README.th.md` (benchmark/README, METHODOLOGY, repro/README, viewer HTML, PUBLISH checklist).
+- v2.2.7: bugfix — synced secret filter (6-pattern redact) between Claude hook (`scripts/claude-capture.mjs`) and `capture-core.ts`, fixed `err()` to return `isError:true` per MCP spec (`src/db/index.ts`), fixed backup rotation to backup only when migrations pending + prune to 5 (`src/db/migrations.ts`), added `data/hook-errors.log` logging for SessionEnd distill failures; benchmark — upgraded to v2.3 spec draft (semantic-hard 8 categories, enhanced scope contamination, graph effectiveness, token efficiency @128 budget, scalability profiles quick→extreme up to 10M with resumable generation, ablation with scope+graph, reliability suite).
 
 **Packaging note (Glama / Smithery):** these registries build with `pnpm install` + `pnpm run build` on **Node 24** and disable postinstall scripts by default (pnpm 10). Any native dependency (e.g. `better-sqlite3`) MUST be listed in `pnpm.onlyBuiltDependencies` in `package.json`, otherwise its native binary is never fetched and the server crashes at startup with `Could not locate the bindings file`.

package/README.md

@@ -4,12 +4,14 @@
 [![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)
+[![CI](https://github.com/worakorn-prince/th-memory-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/worakorn-prince/th-memory-mcp/actions/workflows/ci.yml)
+[![Version Sync](https://github.com/worakorn-prince/th-memory-mcp/actions/workflows/version-sync.yml/badge.svg)](https://github.com/worakorn-prince/th-memory-mcp/actions/workflows/version-sync.yml)
 [![Listed on mcpservers.org](https://mcpservers.org/badge.svg)](https://mcpservers.org/servers/worakorn-prince/th-memory-mcp)
 
 [![th-memory-mcp MCP server](https://glama.ai/mcp/servers/worakorn-prince/th-memory-mcp/badges/card.svg)](https://glama.ai/mcp/servers/worakorn-prince/th-memory-mcp)
 
 
-**Status:** v2.2.4 — a temporal, conflict-aware, hybrid-retrieval memory engine. 16 MCP tools, 25 passing test suites. Non-destructive schema migration from v1 (all v1 data preserved). New in v2.2: lifecycle states, temporal validity, conflict/dedup resolution with USER/SESSION/PROJECT/GLOBAL scope, hybrid FTS+vector retrieval (RRF), memory graph, `get_context` assembly, periodic consolidation, and `link_memory` / `merge_memory` / `update_memory` / `import_memory` / `extract_memories`. New in v2.2.3: scope-enforced retrieval, graph scope isolation, export/import round-trip, hardened import path (realpath), strict import validation, N+1 query elimination, cold/ablation benchmark, and `MEMORY_RETRIEVAL_MODE` switch.
+**Status:** v2.2.7 — a temporal, conflict-aware, hybrid-retrieval memory engine. 16 MCP tools, 25 passing test suites. Non-destructive schema migration from v1 (all v1 data preserved). New in v2.2: lifecycle states, temporal validity, conflict/dedup resolution with USER/SESSION/PROJECT/GLOBAL scope, hybrid FTS+vector retrieval (RRF), memory graph, `get_context` assembly, periodic consolidation, and `link_memory` / `merge_memory` / `update_memory` / `import_memory` / `extract_memories`. New in v2.2.3: scope-enforced retrieval, graph scope isolation, export/import round-trip, hardened import path (realpath), strict import validation, N+1 query elimination, cold/ablation benchmark, and `MEMORY_RETRIEVAL_MODE` switch. New in v2.2.7: synced secret filter between Claude hook and capture-core (6-pattern redact instead of line-drop), fixed `err()` to return `isError:true` per MCP spec, fixed backup rotation (backup only when migrations pending + prune to 5 files), and added hook error logging for SessionEnd distill.
 
 ## Requirements
 
@@ -94,7 +96,7 @@ our hooks bridge; Codex and Cursor use the tools manually (no hook runtime yet).
 | 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) |
+| Lexical fuzzy matching | ✅ (v2.0) | ✅ (v2.0) | ✅ (v2.0) | ✅ (v2.0) | ✅ (v2.0) |
 
 - **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`).
 - **Qwen Code:** see [QWEN_SETUP.md](QWEN_SETUP.md) — MCP works fully; hooks use the Gemini-CLI schema so auto-capture needs a small adapter.
@@ -117,7 +119,7 @@ anywhere is readable everywhere.
   update/supersession resolution preserve both sides of ambiguous evidence
   instead of silently overwriting.
 - **Hybrid retrieval** — `get_context` blends FTS5 keyword search with a
-  dependency-free local vector embedding (RRF fusion + scoring), then assembles
+  dependency-free lexical fuzzy matching (hashed n-gram similarity, 512-dim FNV-1a) (RRF fusion + scoring), then assembles
   a token-budgeted context with optional memory-graph expansion.
 - **Consolidation** — periodic clustering of similar memories into derived
   memories with full provenance (`derived_from` links).
@@ -138,7 +140,7 @@ anywhere is readable everywhere.
 | `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` | full suite: capture, distill, lifecycle, temporal, conflict, retrieval, graph, context, consolidation, benchmark, security, tools_v21, smoke, e2e_transport, retrieval_benchmark, recall_regression, scope, profile, entity_extraction, conflict_benchmark |
+| `npm test` | full suite: capture, distill, lifecycle, temporal, conflict, retrieval, graph, context, consolidation, benchmark, security, tools_v21, smoke, e2e_transport, retrieval_benchmark, recall_regression, scope, profile, entity_extraction, conflict_benchmark, security_regression, export_import_roundtrip |
 | `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) |
 | `node test/lifecycle.test.mjs` | test lifecycle engine (states, decay, supersession) |
@@ -215,6 +217,52 @@ data/
 - DB path can be overridden via the `MEMORY_DB_PATH` env var
 - everything in `data/` is git-ignored
 
+## Benchmark — internal self-reported (not third-party)
+
+> **⚠️ Internal self-reported benchmark — not third-party benchmark**
+> - **internal small-N**: **180 records/30 topics** (B.retrieval: 30 topics × 5 relevant + 30 distractors = 180; full run also uses small-N storage/temporal/context subsets)
+> - **single-machine self-run**: single developer machine, single OS/Node/better-sqlite3 build — not cross-machine, not independently verified
+> - **not third-party benchmark**: self-reported, not independently verified; do not compare as if from an external evaluator
+> - Dataset and harness are in `repro/` (commitable) and `benchmark/` (full framework, see `TH_MEMORY_MCP_BENCHMARK_SPEC.md` and `benchmark/README.md`).
+
+**Two modes**
+
+| Mode | Command | Data | Suites | Use case |
+|------|---------|------|--------|----------|
+| Normal | `npm run benchmark` | 180 records / 30 topics | retrieval | quick check (<5s) |
+| Heavy | `npm run benchmark:heavy` | 600 records / 100 topics + 2k scale | all (storage/retrieval/temporal/context/performance/scalability/cold/ablation) | stress / regression |
+
+Reproduce:
+
+```powershell
+npm run build
+# Normal — quick
+npm run benchmark
+npm run benchmark -- --k 10
+npm run benchmark -- --out repro/results
+
+# Heavy — full framework, more data
+npm run benchmark:heavy
+# or custom:
+node benchmark/run.mjs --suite all --topics 100 --distractors 100 --scale 2000 --out benchmark/results
+```
+
+**Viewer — compare last 3 versions (table + charts)**
+
+```powershell
+npm run benchmark:viewer
+# or: npx serve . -l 3000
+# open http://localhost:3000/benchmark/viewer/  or  http://localhost:3000/result/viewer.html
+```
+
+The viewer loads `benchmark/results/history.jsonl`, groups by version, takes the **latest run of the 3 most recent versions** (e.g. 2.2.2 / 2.2.3 / 2.2.4) and shows a highlighted table (1 row per version) + bar charts for `Recall@5 / MRR / NDCG@5` and `Latency p95`. Results are also saved per version in `result/v*_benchmark_result.md` and `benchmark/results/versions/<ver>/`.
+
+Last internal run (v2.2.4, warm, same dataset — not third-party): Recall@5=0.92, Precision@5=0.92, MRR=1.00, NDCG@5=0.94 over 30 topics/180 records. See `result/v2.2.4_benchmark_result.md` and `repro/README.md` for details and caveats (internal small-N, single-machine self-run).
+
+## Known Limitations
+
+- **No encryption at rest (plaintext-at-rest)** — `data/memory.db` (WAL mode, `better-sqlite3`) is a plain, unencrypted SQLite file. `100% local & private` means no cloud or network exfiltration — it does **not** mean encrypted at rest. Anyone with filesystem access (shared machine, backup, malware, stolen device) can read preferences/lessons/interactions in plaintext. For sensitive data, use OS-level full-disk encryption (BitLocker / FileVault / LUKS) or an opt-in SQLCipher build (requires native rebuild and key management). No SQLCipher/in-code encryption is applied by default and `src/db/index.ts` documents this explicitly.
+
 ## License
 
 [MIT](LICENSE) © 2026 worakorn-prince

package/README.th.md

@@ -1,177 +1,177 @@
-# 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
-
-**สถานะ:** v2.2.4 — engine ความจำแบบ temporal, conflict-aware, hybrid-retrieval 16 MCP tools, 25 ชุดเทสผ่าน อัปเกรด schema แบบ non-destructive จาก v1 (ข้อมูล v1 ทั้งหมดถูกเก็บรักษา) ฟีเจอร์ใหม่ใน v2.2: lifecycle states, temporal validity, การแก้ conflict/dedup พร้อม scope USER/SESSION/PROJECT/GLOBAL, hybrid FTS+vector retrieval (RRF), memory graph, ประกอบ `get_context`, consolidation, และ `link_memory` / `merge_memory` / `update_memory` / `import_memory` / `extract_memories` ใหม่ใน v2.2.3: บังคับ scope ใน retrieval, แยก scope ใน graph, export/import แบบ round-trip, ป้องกัน symlink ด้วย realpath, ตรวจ import เข้มงวด, เลิก N+1 query, benchmark cold/ablation และสวิตช์ `MEMORY_RETRIEVAL_MODE`
-
-> 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` ให้ในคำสั่งเดียว ขั้นตอนด้านล่างคือสิ่งที่สคริปต์ทำ (ใช้ได้หากอยากควบคุมเองทีละขั้น)
-
-**ติดตั้งผ่าน 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
-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 16 ตัว อ่าน/เขียน SQLite เดียวกัน
-                                                      ▲
-                               Global instructions (memory-protocol.md) สอน AI ใช้ tools
-```
-
-รายละเอียดสถาปัตยกรรมเต็มอยู่ใน [ARCHITECTURE_v2.md](ARCHITECTURE_v2.md) — คู่มืออัปเกรดจาก v1 ดูได้ที่ [MIGRATION_v2.md](MIGRATION_v2.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 ก็ทำงานต่อได้แทนที่จะพัง
-- **Lifecycle & temporal** — ทุกความจำมี lifecycle state (active/stale/superseded/archived), คะแนน confidence/importance/salience, decay ต่อ type, และ validity intervals ให้ AI เหตุผลเรื่อง point-in-time truth และ supersession chains ได้
-- **Conflict-aware** — ตรวจจับ duplicate / contradiction และแก้ด้วย update/supersession โดยเก็บทั้งสองฝ่ายของหลักฐานที่ขัดแย้งแทนการเขียนทับเงียบๆ
-- **Hybrid retrieval** — `get_context` ผสาน FTS5 + local vector embedding (RRF fusion + scoring) แล้วประกอบ context แบบมี token budget พร้อมขยายผ่าน memory graph
-- **Consolidation** — จัดคลัสเตอร์ความจำที่คล้ายกันเป็น derived memory พร้อม provenance (`derived_from` links)
-- **เปิดกว้างและต่อยอดได้** — MIT license, 11 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` | ชุดเทสครบ: capture, distill, lifecycle, temporal, conflict, retrieval, graph, context, consolidation, benchmark, security, tools_v21, smoke, e2e_transport, retrieval_benchmark, recall_regression, scope, profile, entity_extraction, conflict_benchmark |
-| `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) |
-| `node test/lifecycle.test.mjs` | ทดสอบ lifecycle engine (states, decay, supersession) |
-| `node test/temporal.test.mjs` | ทดสอบ temporal model (validity, historical retrieval) |
-| `node test/conflict.test.mjs` | ทดสอบ conflict & dedup resolution |
-| `node test/retrieval.test.mjs` | ทดสอบ hybrid FTS+vector+RRF retrieval |
-| `node test/graph.test.mjs` | ทดสอบ memory graph (entities, relations, traversal) |
-| `node test/context.test.mjs` | ทดสอบ context assembly + token budgeting |
-| `node test/consolidation.test.mjs` | ทดสอบ clustering + derived memories |
-| `node test/benchmark.test.mjs` | เทสความเร็วบนความจำ 300 รายการ |
-| `node test/security.test.mjs` | ตรวจการ injection / ความปลอดภัย |
-| `node test/smoke.mjs` | smoke test end-to-end ผ่าน JSON-RPC (11 tools) |
-
-## Tools (16)
-
-| 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 ให้เอง) |
-| `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
-
-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
-
-## License
-
-[MIT](LICENSE) © 2026 worakorn-prince
-
-โปรเจกต์นี้เผยแพร่ภายใต้สัญญาอนุญาต MIT — อ่านข้อความฉบับเต็มได้ในไฟล์ [LICENSE](LICENSE)
+# 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
+
+**สถานะ:** v2.2.7 — engine ความจำแบบ temporal, conflict-aware, hybrid-retrieval 16 MCP tools, 25 ชุดเทสผ่าน อัปเกรด schema แบบ non-destructive จาก v1 (ข้อมูล v1 ทั้งหมดถูกเก็บรักษา) ฟีเจอร์ใหม่ใน v2.2: lifecycle states, temporal validity, การแก้ conflict/dedup พร้อม scope USER/SESSION/PROJECT/GLOBAL, hybrid FTS+vector retrieval (RRF), memory graph, ประกอบ `get_context`, consolidation, และ `link_memory` / `merge_memory` / `update_memory` / `import_memory` / `extract_memories` ใหม่ใน v2.2.3: บังคับ scope ใน retrieval, แยก scope ใน graph, export/import แบบ round-trip, ป้องกัน symlink ด้วย realpath, ตรวจ import เข้มงวด, เลิก N+1 query, benchmark cold/ablation และสวิตช์ `MEMORY_RETRIEVAL_MODE` ใหม่ใน v2.2.7: ซิงค์ secret filter ระหว่าง Claude hook กับ capture-core (redact 6 patterns แทนทิ้งบรรทัด), แก้ `err()` ให้ส่ง `isError:true` ตาม MCP spec, แก้ backup rotation (backup เฉพาะเมื่อมี migration pending + prune เก็บ 5 ไฟล์ล่าสุด) และเพิ่ม hook error logging สำหรับ SessionEnd distill
+
+> 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` ให้ในคำสั่งเดียว ขั้นตอนด้านล่างคือสิ่งที่สคริปต์ทำ (ใช้ได้หากอยากควบคุมเองทีละขั้น)
+
+**ติดตั้งผ่าน 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
+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 16 ตัว อ่าน/เขียน SQLite เดียวกัน
+                                                      ▲
+                               Global instructions (memory-protocol.md) สอน AI ใช้ tools
+```
+
+รายละเอียดสถาปัตยกรรมเต็มอยู่ใน [ARCHITECTURE_v2.md](ARCHITECTURE_v2.md) — คู่มืออัปเกรดจาก v1 ดูได้ที่ [MIGRATION_v2.md](MIGRATION_v2.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 ก็ทำงานต่อได้แทนที่จะพัง
+- **Lifecycle & temporal** — ทุกความจำมี lifecycle state (active/stale/superseded/archived), คะแนน confidence/importance/salience, decay ต่อ type, และ validity intervals ให้ AI เหตุผลเรื่อง point-in-time truth และ supersession chains ได้
+- **Conflict-aware** — ตรวจจับ duplicate / contradiction และแก้ด้วย update/supersession โดยเก็บทั้งสองฝ่ายของหลักฐานที่ขัดแย้งแทนการเขียนทับเงียบๆ
+- **Hybrid retrieval** — `get_context` ผสาน FTS5 + local vector embedding (RRF fusion + scoring) แล้วประกอบ context แบบมี token budget พร้อมขยายผ่าน memory graph
+- **Consolidation** — จัดคลัสเตอร์ความจำที่คล้ายกันเป็น derived memory พร้อม provenance (`derived_from` links)
+- **เปิดกว้างและต่อยอดได้** — MIT license, 11 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` | ชุดเทสครบ: capture, distill, lifecycle, temporal, conflict, retrieval, graph, context, consolidation, benchmark, security, tools_v21, smoke, e2e_transport, retrieval_benchmark, recall_regression, scope, profile, entity_extraction, conflict_benchmark |
+| `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) |
+| `node test/lifecycle.test.mjs` | ทดสอบ lifecycle engine (states, decay, supersession) |
+| `node test/temporal.test.mjs` | ทดสอบ temporal model (validity, historical retrieval) |
+| `node test/conflict.test.mjs` | ทดสอบ conflict & dedup resolution |
+| `node test/retrieval.test.mjs` | ทดสอบ hybrid FTS+vector+RRF retrieval |
+| `node test/graph.test.mjs` | ทดสอบ memory graph (entities, relations, traversal) |
+| `node test/context.test.mjs` | ทดสอบ context assembly + token budgeting |
+| `node test/consolidation.test.mjs` | ทดสอบ clustering + derived memories |
+| `node test/benchmark.test.mjs` | เทสความเร็วบนความจำ 300 รายการ |
+| `node test/security.test.mjs` | ตรวจการ injection / ความปลอดภัย |
+| `node test/smoke.mjs` | smoke test end-to-end ผ่าน JSON-RPC (11 tools) |
+
+## Tools (16)
+
+| 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 ให้เอง) |
+| `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
+
+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
+
+## License
+
+[MIT](LICENSE) © 2026 worakorn-prince
+
+โปรเจกต์นี้เผยแพร่ภายใต้สัญญาอนุญาต MIT — อ่านข้อความฉบับเต็มได้ในไฟล์ [LICENSE](LICENSE)

package/SECURITY.md

@@ -0,0 +1,40 @@
+# Security Policy
+
+## Supported Versions
+
+| Version | Supported          |
+| ------- | ------------------ |
+| 2.2.x   | :white_check_mark: |
+| < 2.2   | :x:                |
+
+We support the latest `2.2.x` release line. Older major/minor lines receive no security updates.
+
+## Reporting a Vulnerability
+
+**Please do not open a public issue for security reports.**
+
+Use one of these private channels:
+
+1. **GitHub Security Advisories (preferred):** https://github.com/worakorn-prince/th-memory-mcp/security/advisories/new
+2. **Email:** open a draft advisory and we will triage within 72 hours.
+
+### What to include
+
+- Affected version / commit
+- Steps to reproduce (minimal PoC)
+- Impact assessment (data loss, leak, DoS, scope bypass, etc.)
+- Suggested fix if you have one
+
+### What to expect
+
+- Acknowledgement within 72 hours
+- Triage and severity assessment using the same legend as `HealthCheck_Final.md` (Critical / High / Medium / Low)
+- Fix in a patch release and credit in release notes if desired
+
+## Scope
+
+This policy covers the MCP server (`src/`), SQLite store (`data/memory.db`), and the auto-capture plugin (`src/plugin/learning-capture.ts`). The benchmark harness (`benchmark/`, `repro/`) and result files (`result/`) are out of scope.
+
+## Disclosure
+
+We follow coordinated disclosure. Please give us reasonable time to release a fix before public disclosure. We will publish a GitHub Release and update `SECURITY.md` with the fix version.