th-memory-mcp 2.0.0 → 2.2.0

package/README.md

@@ -7,7 +7,7 @@
 
 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:** v2.0.0 — a temporal, conflict-aware, hybrid-retrieval memory engine. 11 MCP tools, 12 passing test suites. Non-destructive schema migration from v1 (all v1 data preserved). New in v2: lifecycle states, temporal validity, conflict/dedup resolution, hybrid FTS+vector retrieval (RRF), memory graph, `get_context` assembly, and periodic consolidation.
+**Status:** v2.2.0 — a temporal, conflict-aware, hybrid-retrieval memory engine. 16 MCP tools, 20 passing test suites. Non-destructive schema migration from v1 (all v1 data preserved). New in v2: 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`.
 
 ## Requirements
 
@@ -63,12 +63,12 @@ setx MEMORY_DB_PATH "$PWD/data/memory.db"
 ```
 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)  ── 11 tools read/write the same SQLite DB
+             └─ MCP th-memory-mcp (Node.js stdio)  ── 16 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.
+See [ARCHITECTURE_v2.md](ARCHITECTURE_v2.md) for the full architecture spec.
 
 ## Why th-memory-mcp?
 
@@ -78,7 +78,7 @@ LLMs don't remember you between sessions — every new chat starts blank. th-mem
 - **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, 11 documented tools, a rule-based distill, and an auto-capture plugin you can adapt.
+- **Open & extensible** — MIT licensed, 16 documented tools, a rule-based distill, and an auto-capture plugin you can adapt.
 
 ## Works with other harnesses
 
@@ -89,7 +89,7 @@ our hooks bridge; Codex and Cursor use the tools manually (no hook runtime yet).
 
 | Feature | OpenCode | Claude Code | Qwen Code | Codex | Cursor |
 |---|---|---|---|---|---|
-| 11 MCP tools | ✅ | ✅ | ✅ | ✅ | ✅ |
+| 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) |
@@ -136,7 +136,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, smoke |
+| `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 |
 | `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) |
@@ -148,9 +148,9 @@ anywhere is readable everywhere.
 | `node test/consolidation.test.mjs` | test clustering + derived memories |
 | `node test/benchmark.test.mjs` | latency benchmark over 300 memories |
 | `node test/security.test.mjs` | injection / safety checks |
-| `node test/smoke.mjs` | end-to-end smoke test over JSON-RPC (11 tools) |
+| `node test/smoke.mjs` | end-to-end smoke test over JSON-RPC (16 tools) |
 
-## Tools (11)
+## Tools (16)
 
 | Tool | Description |
 |------|-------------|
@@ -165,6 +165,11 @@ anywhere is readable everywhere.
 | `export_memory` | export memory to JSON under `data/exports/` only (filename auto-sanitized) |
 | `get_context` | assemble relevant memories for the current task via hybrid retrieval (+ optional graph expansion) with token budgeting |
 | `consolidate` | cluster similar memories via embedding similarity; optionally create derived/consolidated memories linked via `derived_from` |
+| `link_memory` | create a typed relationship between two memories in the graph (supports/contradicts/supersedes/derived_from/related_to/caused_by/depends_on) |
+| `merge_memory` | merge a duplicate/near-duplicate into a canonical memory (source becomes superseded, provenance in `metadata.merged_from`) |
+| `update_memory` | update mutable fields in place, or create a superseding memory when `content` changes (set `supersede=false` to edit in place) |
+| `import_memory` | import memories from JSON (validates type, dedupes against existing, never overwrites blindly); dry-run by default, `apply=true` to insert |
+| `extract_memories` | scan recent captured interactions for memory-intent phrases and propose memory candidates (deterministic, no LLM); dry-run by default, `apply=true` to create (source=captured) |
 
 ## Install with OpenCode
 

package/README.th.md

@@ -7,7 +7,7 @@
 
 MCP server ความจำระยะยาวสำหรับ OpenCode — เก็บ preferences, lessons, ประวัติการใช้งาน ลง SQLite ไฟล์เดียว (local 100%, ไม่มี external API) เพื่อให้ AI "จำและปรับตัว" กับผู้ใช้ผ่าน context-based learning
 
-**สถานะ:** v2.0.0 — engine ความจำแบบ temporal, conflict-aware, hybrid-retrieval 11 MCP tools, 12 ชุดเทสผ่าน อัปเกรด schema แบบ non-destructive จาก v1 (ข้อมูล v1 ทั้งหมดถูกเก็บรักษา) ฟีเจอร์ใหม่ใน v2: lifecycle states, temporal validity, การแก้ conflict/dedup, hybrid FTS+vector retrieval (RRF), memory graph, ประกอบ `get_context`, และ consolidation
+**สถานะ:** v2.2.0 — engine ความจำแบบ temporal, conflict-aware, hybrid-retrieval 16 MCP tools, 20 ชุดเทสผ่าน อัปเกรด schema แบบ non-destructive จาก v1 (ข้อมูล v1 ทั้งหมดถูกเก็บรักษา) ฟีเจอร์ใหม่ใน v2: 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`
 
 > English: [README.md](README.md)
 
@@ -65,12 +65,12 @@ setx MEMORY_DB_PATH "$PWD/data/memory.db"
 ```
 OpenCode ──┬─ Plugin learning-capture (Bun)  ── จับ prompt/tool/error ลง DB อัตโนมัติ
             │                                   └─ ฉีด profile กลับ context ตอน compaction
-             └─ MCP th-memory-mcp (Node.js stdio)  ── tools 11 ตัว อ่าน/เขียน SQLite เดียวกัน
+              └─ MCP th-memory-mcp (Node.js stdio)  ── tools 16 ตัว อ่าน/เขียน SQLite เดียวกัน
                                                       ▲
                                Global instructions (memory-protocol.md) สอน AI ใช้ tools
 ```
 
-รายละเอียดเต็มอยู่ใน [design.md](design.md) — คู่มืออัปเกรดจาก v1 ดูได้ที่ [MIGRATION_v2.md](MIGRATION_v2.md)
+รายละเอียดสถาปัตยกรรมเต็มอยู่ใน [ARCHITECTURE_v2.md](ARCHITECTURE_v2.md) — คู่มืออัปเกรดจาก v1 ดูได้ที่ [MIGRATION_v2.md](MIGRATION_v2.md)
 
 ## ทำไมต้องใช้ th-memory-mcp?
 
@@ -93,7 +93,7 @@ LLM ไม่ได้จำคุณข้าม session — แชทใหม
 | `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, smoke |
+| `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) |
@@ -107,7 +107,7 @@ LLM ไม่ได้จำคุณข้าม session — แชทใหม
 | `node test/security.test.mjs` | ตรวจการ injection / ความปลอดภัย |
 | `node test/smoke.mjs` | smoke test end-to-end ผ่าน JSON-RPC (11 tools) |
 
-## Tools (11)
+## Tools (16)
 
 | Tool | คำอธิบาย |
 |------|----------|
@@ -122,6 +122,11 @@ LLM ไม่ได้จำคุณข้าม session — แชทใหม
 | `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
 

package/design.md

@@ -1,98 +1,58 @@
-# th-memory-mcp v2 — Implementation Plan (design.md)
-
-**Source of truth:** `ARCHITECTURE_v2.md` (on GitHub, baseline v1.2.2).
-This file is the working plan for the Building Agent — read it before continuing implementation.
-
-## Goal
-Evolve th-memory-mcp from a structured local memory MCP into a durable, temporal,
-conflict-aware, hybrid-retrieval memory engine. Local-first, offline, SQLite, no
-mandatory cloud/LLM. Keep v1 behavior working during the transition.
-
-## Current v1 state (summary)
-- 9 MCP tools: remember, recall, get_profile, save_lesson, search_history, forget, memory_stats, get_recent_interactions, export_memory.
-- Schema (inline `CREATE TABLE IF NOT EXISTS` in `src/db.ts`): `interactions`, `preferences`, `lessons`, `profile`, FTS5 `search_index`, `embeddings` (BLOB, 512-dim hashing-trick vectors).
-- No migration system; no schema version table.
-- Capture logic triplicated: `src/lib/capture-core.ts`, `src/plugin/learning-capture.ts` (Bun), `scripts/claude-capture.mjs`.
-- Semantic search = full in-memory linear scan over all embeddings every `recall`.
-- Version metadata inconsistent: `package.json` 1.2.2 vs `config.ts` VERSION 1.1.0 vs `smoke.mjs` assertion 1.1.0 (fix in Phase 10).
-
-## Decisions (Phase 1)
-- **Migrations are TS modules** (`src/db/migrations.ts`) exporting an ordered `MIGRATIONS` array + `runMigrations(db)`. Each `up(db)` is idempotent (`CREATE TABLE IF NOT EXISTS`) and tracked in `schema_meta`. This avoids `.sql` file-copy issues under `tsc` while keeping deterministic order (spec allows implementation differences).
-- **Reuse existing `search_index` + `embeddings`** for v2 `memories` (ref_table = `'memories'`). No new FTS table needed.
-- **Non-destructive:** v1 tables (`preferences`, `lessons`, `interactions`, `profile`) are preserved. v2 adds `memories`, `entities`, `relations`, `memory_links`, `schema_meta`.
-- **Backfill (M005):** map `preferences → memories(type=PREFERENCE)`, `lessons → memories(type=LESSON)`, sync FTS+embeddings. Guarded by `v1_backfilled` flag so it runs once. `recall` is unaffected because it filters by `ref_table IN ('preferences','lessons')`.
-- **No dual-write yet.** v1 tools keep writing only to v1 tables. v2 `memories` is seeded by backfill; new v2 tools (later phases) write to `memories`. Dedup/merge of backfilled vs new entries is Phase 4.
-- **Repository layer** (`src/db/repositories/memories.ts`) provides `createMemory`, `getMemoryById`, `setStatus`, `softDelete`, `syncMemoryIndex`, `searchMemories` (FTS + semantic blend, status/project filtering). Not yet wired to a public tool (that is Phase 7 `get_context`).
-
-## Phased roadmap
-See `ARCHITECTURE_v2.md` §35 for the canonical phase list. Status tracked in the session todo list.
-
-## This session (deliverables so far)
-
-### Phase 1 — Core abstraction (DONE)
-- [x] `src/memory/types.ts` — unified `MemoryType`, `SourceType`, `LifecycleState`, `Scope`, `LinkRelation`, `MemoryRecord`.
-- [x] `src/db/migrations.ts` — migration engine + 5 migrations (schema_meta, memories+indexes, entities/relations, memory_links, v1 backfill).
-- [x] `src/db/repositories/memories.ts` — core CRUD + index sync + `searchMemories` (hybrid FTS + semantic blend).
-- [x] `src/db/index.ts` — call `runMigrations(db)` after existing DDL (non-destructive).
-- [x] Build + full test suite green (capture/distill/smoke).
-
-### Phase 2 — Lifecycle engine (DONE)
-- [x] `src/memory/decay.ts` — `recencyFactor`, per-type `DECAY_LAMBDA_BY_TYPE` (policy classes, not constants).
-- [x] `src/memory/source-weights.ts` — `SOURCE_WEIGHTS` map (spec §8).
-- [x] `src/memory/scorer.ts` — `computeSalience` (weighted, configurable), `computeConfidence` (source weight + diminishing returns), `salienceForMemory`.
-- [x] `src/core/lifecycle-engine.ts` — `canTransition`, `transitionStatus`, `reinforce`, `touch`, `supersede` (sets old=superseded, new=active + `supersedes_id` + `memory_links`), `archive`, `softDelete`, `LifecycleError`.
-- [x] `test/lifecycle.test.mjs` — 17 checks (decay, scorer, transitions, supersession, archive). Added to `npm test`.
-
-### Phase 3 — Temporal model (DONE)
-- [x] `src/core/temporal-engine.ts` — `setValidity`, `memoriesValidAt` (point-in-time truth), `supersessionChain` (oldest→newest), `changesBetween` (change detection).
-- [x] `test/temporal.test.mjs` — 7 checks (validity intervals, historical retrieval, supersession chains, change detection). Added to `npm test`.
-
-### Phase 4 — Conflict & dedup (DONE)
-- [x] `src/memory/deduplicator.ts` — `normalizeText`, `findExactMatch`, `findSimilar`, `deduplicate` (spec §11).
-- [x] `src/memory/conflict-resolver.ts` — `isContradiction`, `classifyRelationship` (duplicate/update/contradiction/unrelated), `findRelated`, `resolveConflict` (merge duplicate / supersede update / link contradiction, preserving ambiguous evidence per §12).
-- [x] `test/conflict.test.mjs` — 14 checks. Added to `npm test`.
-- [x] **Bug fix (v1 too):** `src/lib/embed.ts` `serialize`/`deserialize` rewrote with `DataView` + explicit `byteOffset`. Old code used `Buffer.from(buf).buffer` which can carry a non-zero pool `byteOffset`, corrupting vectors (magnitude ~1e37). This silently broke v1 semantic search.
-
-### Phase 5 — Hybrid retrieval (DONE)
-- [x] `src/retrieval/fts.ts` — `ftsSearch` (FTS5 over `search_index`, status/project filters, `ORDER BY rank`).
-- [x] `src/retrieval/vector.ts` — `vectorSearch` (cosine over `embeddings`, floor 0.15, filters).
-- [x] `src/retrieval/fusion.ts` — `rrfFuse` (Reciprocal Rank Fusion, k=60).
-- [x] `src/retrieval/scorer.ts` — `finalScore` (RRF × confidence × importance × recency × scope) + `scopeFactorFor`.
-- [x] `src/core/retrieval-engine.ts` — `retrieve` (FTS + vector → RRF → scoring/rerank → filter → topK).
-- [x] `searchMemories` in repository now delegates to `retrieve` (hybrid). `buildFtsMatch` switched to OR for better recall.
-- [x] `test/retrieval.test.mjs` — 7 checks. Added to `npm test`.
-
-### Phase 6 — Graph engine (DONE)
-- [x] `src/core/graph-engine.ts` — `createEntity` (canonical dedup, aliases in metadata), `addRelation` (source_entity_id/relation/target_entity_id), `linkMemories`, `traverse` (bounded BFS over `memory_links`, maxDepth 1–5, relationFilter), `neighbors`.
-- [x] `test/graph.test.mjs` — 7 checks (linking, bounded traversal depth, relation filter, entity dedup, relation insert). Added to `npm test`.
-- [x] Note: `entities` columns are `(name, canonical_name, type, metadata)`; `relations` use `source_entity_id/relation/target_entity_id`; `memory_links` PK `(source_memory_id, relation, target_memory_id)`.
-
-### Phase 7 — Context engine (DONE)
-- [x] `src/core/context-engine.ts` — `getContext` (hybrid retrieve → optional graph expansion → temporal validity filter → token budgeting/truncation).
-- [x] `src/tools/context.ts` — `contextInput` (zod) + `contextHandler` (returns assembled context text).
-- [x] Wired `get_context` MCP tool into `index.ts` (now 10 tools total).
-- [x] `test/context.test.mjs` — 7 checks (assembly, graph expansion, token budget, temporal validity). Added to `npm test`.
-- [x] Updated `test/smoke.mjs` to expect 10 tools.
-
-### Phase 8 — Consolidation (DONE)
-- [x] `src/core/consolidation-engine.ts` — `clusterMemories` (embedding cosine + union-find), `createDerivedMemory` (type DERIVED, source consolidated, links `derived_from`), `getProvenance`.
-- [x] `src/tools/consolidate.ts` — `consolidateInput` + `consolidateHandler` (read-only cluster listing + optional `derive`).
-- [x] Wired `consolidate` MCP tool into `index.ts` (now 11 tools total).
-- [x] `test/consolidation.test.mjs` — 5 checks. Added to `npm test`.
-- [x] Added `DERIVED` to `MEMORY_TYPES`; added `DERIVED` lambda to `decay.ts`.
-
-### Phase 9 — Benchmark & security suite (DONE)
-- [x] `test/benchmark.test.mjs` — 2 checks (retrieve over 300 memories < 2000ms).
-- [x] `test/security.test.mjs` — 5 checks (FTS injection quoting, safe retrieve, malicious content stored verbatim, extreme budget, parameterized SQL).
-- [x] Both added to `npm test` (now 12 suites).
-
-### Phase 10 — v2 release (DOCS DONE; PUBLISH PENDING USER)
-- [x] `MIGRATION_v2.md` written (non-destructive upgrade guide, rollback notes).
-- [x] `README.md` updated to v2.0.0 (11 tools, v2 architecture, new test scripts).
-- [ ] Version bump to `2.0.0` + `npm publish --otp=CODE` (needs user OTP).
-- [ ] `git commit` + `git push` + GitHub Release v2.0.0 (needs user).
-- [ ] `.\mcp-publisher.exe publish` (Official MCP Registry; needs user GitHub OAuth + OTP).
-- [ ] Glama: claim ownership + sync from GitHub.
-
-## Next
-All v2 engine phases (0–9) complete and tested. Remaining: user-driven release steps above. After release, future work could include automatic entity extraction in consolidation and a periodic auto-consolidate scheduler.
+# th-memory-mcp — Design Notes (ปัจจุบัน)
+
+เอกสารนี้อัปเดตล่าสุดสอดคล้องกับสถานะจริงของโค้ด (หลังจบแผนฟีเจอร์อนาคตทั้งหมด ยกเว้น AI-assisted extraction ที่ตัดออก)
+สเปคฉบับเต็มอยู่ที่ `ARCHITECTURE_v2.md` (canonical spec) ไฟล์นี้สรุปภาพรวมและสถานะปัจจุบันเพื่อความสะดวก
+
+## สถานะปัจจุบัน
+- **เวอร์ชัน:** `package.json` = `2.2.0`
+- **MCP tools:** 16 tools (`remember`, `recall`, `get_context`, `link_memory`, `merge_memory`, `update_memory`, `import_memory`, `extract_memories`, `consolidate`, `forget`, `history`, `recent_interactions`, `profile`, `lesson`, `memory_stats`, `export_memory`)
+- **ชุดเทสต์:** 20 suites ผ่านหมด (0 fail) — รันผ่าน `npm test` (มี CI บน GitHub Actions)
+
+## องค์ประกอบหลัก (src/)
+- `db/` — better-sqlite3 (WAL mode), migrations เชิงเส้น (M001–M007), repositories (`memories`, `users`, `preferences`, `lessons`)
+- `lib/embed.ts` — semantic vector แบบ hashing-trick (ไม่พึ่ง LLM/network)
+- `retrieval/` — FTS5 + vector → RRF fusion → scorer (confidence × importance × recency × scope)
+- `memory/` — types, lifecycle-engine (decay/source-weights), conflict-resolver, deduplicator
+- `core/` — retrieval-engine, context-engine, graph-engine, consolidation-engine, entity-extractor
+- `tools/` — 16 MCP tool handlers
+- `index.ts` — MCP stdio server
+
+## ฟีเจอร์ที่ทำเสร็จแล้ว
+- ✅ Temporal model — validity intervals, point-in-time retrieval, supersession chains, change detection
+- ✅ Conflict/dedup — normalize → exact → similar → classify (duplicate/update/contradiction/unrelated); ambiguous conflicts ถูกเก็บไว้ (link `contradicts`) ไม่เขียนทับเงียบๆ
+- ✅ Hybrid retrieval (FTS + vector, RRF)
+- ✅ Memory graph — entities/relations + bounded traversal (`link_memory`)
+- ✅ Context engine — `get_context` with token budgeting, temporal filter, graph expansion
+- ✅ Consolidation — clustering + derived memories (`derived_from` provenance)
+- ✅ Scope hierarchy — `USER` / `SESSION` / `PROJECT` / `GLOBAL` (migrations 006 + 007)
+  - `createMemory` อนุมาน scope ตามลำดับ SESSION > PROJECT > USER > GLOBAL
+  - `scopeFactorFor` boost ความจำที่เข้าข่ายบริบทปัจจุบัน (USER=1.0, PROJECT/SESSION ตามบริบท, GLOBAL เป็น base)
+- ✅ Profile auto-projection — `profile.ts` ดึงความจำสำคัญมาแทรกใน `[memories]`
+- ✅ Auto entity extraction — `entity-extractor.ts` สกัด entity แบบ heuristic (ไม่ใช้ LLM) ผูกเข้า graph ตอน consolidate
+- ✅ Benchmark in-repo:
+  - Retrieval quality (§26) — `test/retrieval_benchmark.test.mjs` (Recall@5=1.00, Precision@5=0.92, MRR=1.00)
+  - Perf (§29) — `test/benchmark.test.mjs` วัด latency ต่อ op ผ่าน CI
+  - Conflict quality (§27) — `test/conflict_benchmark.test.mjs` (100% บนชุด 14 เคส ครบ 7 หมวด)
+  - E2E transport — `test/e2e_transport.test.mjs` (spawn server ผ่าน StdioClientTransport)
+- ✅ CI pipeline — `.github/workflows/ci.yml` (ubuntu-latest, node 20, `npm ci`, `npm test`)
+
+## Scope model (รายละเอียด)
+| Scope | เงื่อนไข | พฤติกรรม |
+|-------|----------|----------|
+| SESSION | มี `sessionId` | ผูกกับ session นั้น |
+| PROJECT | มี `projectId` (ไม่มี session) | ผูกกับ project นั้น |
+| USER | มี `userId` (ไม่มี session/project) | ผูกกับ user นั้น (auto-create row ใน `users`) |
+| GLOBAL | ไม่มีอะไรเลย | ความจำร่วมกันทั้งระบบ |
+
+`userId` ที่รับจาก client เป็น external identity (string) — ระบบไม่มีการ authenticate; ตัวตัดความเป็นของ client ทั้งหมด
+`preferences` และ `lessons` ยังคงเป็น global (ไม่มี user column)
+
+## ข้อจำกัดที่รู้อยู่ (known limitations)
+- **Trust model:** ไม่มี user authentication — `userId` คือสิ่งที่ client แจ้งมา (client-declared) เหมาะกับการ deploy แบบ local single-user ที่ไฟล์ SQLite เป็นของเจ้าของคนเดียว หากต้องการแยกผู้ใช้หลายคน แนะนำแก้ที่ระดับไฟล์ DB (หนึ่ง DB ต่อผู้ใช้) ไม่ใช่เพิ่ม auth ลงใน engine
+- `preferences` / `lessons` ไม่ถูกแบ่งตาม user (ยังเป็น global) — ยอมรับได้สำหรับ single-user
+- Semantic embedding ใช้ hashing-trick (deterministic, offline) — ไม่ใช่ embedding ระดับ LLM จึงมีขีดจำกัดเรื่อง paraphrase ที่ห่างกันมาก
+- **AI-assisted extraction ไม่พัฒนาต่อ** — เจ้าของตัดสินใจตัดหัวข้อนี้ออก `extract_memories` จึงเป็น deterministic heuristic เท่านั้น (ไม่ใช้ LLM) ตามหลักการออกแบบที่ว่า core engine ต้องไม่พึ่งพา external LLM API
+
+## Release
+- v2.0.0 ปล่อยแล้ว (npm, GitHub Release, Official MCP Registry, Glama)
+- v2.2.0 — tag + GitHub Release สร้างโดย build agent; `npm` / Official MCP Registry / Glama publish รอเจ้าของ re-auth (publish token หมดอายุ)

package/dist/core/context-engine.js

@@ -17,6 +17,8 @@ export function getContext(opts = {}) {
     const seeds = retrieve(query, {
         limit,
         projectId: opts.projectId,
+        sessionId: opts.sessionId,
+        userId: opts.userId,
         includeArchived: opts.includeHistory,
     });
     const seedScores = new Map();

package/dist/core/entity-extractor.js

@@ -0,0 +1,83 @@
+import { db } from "../db/index.js";
+import { createEntity, addRelation, linkMemories } from "./graph-engine.js";
+import { STOPWORDS } from "../lib/distill-core.js";
+// Heuristic entity extraction (no LLM). Catches quoted strings, CamelCase /
+// PascalCase identifiers, capitalized proper nouns, kebab-case, file paths, URLs,
+// and generic technical tokens (length >= 4, non-stopword).
+export function extractEntities(text) {
+    const found = new Set();
+    if (!text)
+        return [];
+    const add = (s) => {
+        if (s && s.trim().length >= 2)
+            found.add(s.trim());
+    };
+    for (const m of text.matchAll(/"([^"]{2,60})"|'([^']{2,60})'/g))
+        add(m[1] ?? m[2]);
+    for (const m of text.matchAll(/[A-Z][a-z0-9]+(?:[A-Z][a-z0-9]+)+/g))
+        add(m[0]);
+    for (const m of text.matchAll(/\b[A-Z][a-z]{2,}\b/g))
+        add(m[0]);
+    for (const m of text.matchAll(/\b[a-z]+(?:-[a-z]+){1,}\b/g))
+        add(m[0]);
+    for (const m of text.matchAll(/\b[\w./-]+\.(ts|js|mjs|py|json|md|yaml|yml)\b/gi))
+        add(m[0]);
+    for (const m of text.matchAll(/\bhttps?:\/\/\S+/gi))
+        add(m[0]);
+    for (const m of text.matchAll(/\b[A-Za-z][A-Za-z0-9_-]*\b/g)) {
+        const t = m[0];
+        if (t.length >= 4 && !STOPWORDS.has(t.toLowerCase()))
+            add(t);
+    }
+    return [...found].filter((e) => e.length >= 2).slice(0, 12);
+}
+// Extract entities from a memory's content, persist them, and record
+// co-occurrence relations (sourced from this memory). Returns entity ids.
+export function linkEntitiesForMemory(memoryId, content) {
+    const names = extractEntities(content);
+    const ids = [];
+    for (const name of names) {
+        ids.push(createEntity({ name, type: "concept" }));
+    }
+    for (let i = 0; i < ids.length; i++) {
+        for (let j = i + 1; j < ids.length; j++) {
+            addRelation({
+                subjectId: ids[i],
+                predicate: "co_occurs",
+                objectId: ids[j],
+                confidence: 0.6,
+                sourceMemoryId: memoryId,
+            });
+        }
+    }
+    return ids;
+}
+// Link memories that share at least one extracted entity (item 5).
+export function linkMemoriesBySharedEntities(memoryIds) {
+    const memEntities = new Map();
+    for (const id of memoryIds) {
+        const rows = db
+            .prepare(`SELECT DISTINCT e FROM (
+           SELECT target_entity_id AS e FROM relations WHERE source_memory_id = ?
+           UNION
+           SELECT source_entity_id AS e FROM relations WHERE source_memory_id = ?
+         )`)
+            .all(id, id);
+        memEntities.set(id, new Set(rows.map((r) => r.e)));
+    }
+    for (let i = 0; i < memoryIds.length; i++) {
+        for (let j = i + 1; j < memoryIds.length; j++) {
+            const a = memEntities.get(memoryIds[i]);
+            const b = memEntities.get(memoryIds[j]);
+            let shared = false;
+            for (const e of a) {
+                if (b.has(e)) {
+                    shared = true;
+                    break;
+                }
+            }
+            if (shared)
+                linkMemories(memoryIds[i], memoryIds[j], "shares_entity");
+        }
+    }
+}

package/dist/core/retrieval-engine.js

@@ -4,6 +4,7 @@ import { vectorSearch } from "../retrieval/vector.js";
 import { rrfFuse } from "../retrieval/fusion.js";
 import { finalScore, scopeFactorFor } from "../retrieval/scorer.js";
 import { recencyFactorFor } from "../memory/decay.js";
+import { resolveUserId } from "../db/repositories/users.js";
 // Hybrid retrieval pipeline (spec §13): FTS + vector -> RRF fusion -> scoring/rerank -> filter -> topK
 export function retrieve(query, opts = {}) {
     const limit = Math.min(Math.max(opts.limit ?? 10, 1), 50);
@@ -26,7 +27,11 @@ export function retrieve(query, opts = {}) {
             (mem.status === "deleted" || mem.status === "archived"))
             continue;
         const recency = recencyFactorFor(mem.type, mem.updated_at, now);
-        const scope = scopeFactorFor(mem, opts.projectId);
+        const scope = scopeFactorFor(mem, {
+            projectId: opts.projectId,
+            sessionId: opts.sessionId,
+            userId: opts.userId ? resolveUserId(opts.userId) : null,
+        });
         const fs = finalScore({
             rrf,
             confidence: mem.confidence,

package/dist/db/migrations.js

@@ -136,12 +136,37 @@ const M005_backfill_v1 = {
         db.prepare("INSERT INTO schema_meta (key, value) VALUES ('v1_backfilled', '1') ON CONFLICT(key) DO UPDATE SET value = '1'").run();
     },
 };
+const M006_scope = {
+    id: "006_scope",
+    up(db) {
+        db.exec(`ALTER TABLE memories ADD COLUMN scope TEXT NOT NULL DEFAULT 'GLOBAL';`);
+        db.exec(`UPDATE memories SET scope = 'SESSION' WHERE session_id IS NOT NULL;`);
+        db.exec(`UPDATE memories SET scope = 'PROJECT' WHERE session_id IS NULL AND project_id IS NOT NULL;`);
+        db.exec(`CREATE INDEX IF NOT EXISTS idx_memories_scope ON memories(scope);`);
+    },
+};
+const M007_user = {
+    id: "007_user",
+    up(db) {
+        db.exec(`CREATE TABLE IF NOT EXISTS users (
+      id INTEGER PRIMARY KEY AUTOINCREMENT,
+      external_id TEXT NOT NULL UNIQUE,
+      name TEXT,
+      created_at TEXT NOT NULL
+    );`);
+        db.exec(`CREATE INDEX IF NOT EXISTS idx_users_external ON users(external_id);`);
+        db.exec(`ALTER TABLE memories ADD COLUMN user_id INTEGER REFERENCES users(id);`);
+        db.exec(`CREATE INDEX IF NOT EXISTS idx_memories_user ON memories(user_id);`);
+    },
+};
 export const MIGRATIONS = [
     M001_schema_meta,
     M002_memories,
     M003_entities_relations,
     M004_memory_links,
     M005_backfill_v1,
+    M006_scope,
+    M007_user,
 ];
 export function runMigrations(db) {
     db.exec(`CREATE TABLE IF NOT EXISTS schema_meta (key TEXT PRIMARY KEY, value TEXT NOT NULL);`);

package/dist/db/repositories/memories.js

@@ -1,15 +1,24 @@
 import { db, syncSearchIndex, removeSearchIndex, upsertEmbedding, removeEmbedding, nowISO, } from "../../db/index.js";
 import { embed } from "../../lib/embed.js";
 import { retrieve } from "../../core/retrieval-engine.js";
+import { ensureUser } from "./users.js";
 export function createMemory(input) {
     const ts = nowISO();
+    const uid = input.userId ? ensureUser(input.userId) : null;
+    const scope = input.sessionId
+        ? "SESSION"
+        : input.projectId
+            ? "PROJECT"
+            : uid
+                ? "USER"
+                : "GLOBAL";
     const info = db
         .prepare(`INSERT INTO memories
-       (type, content, summary, status, source, confidence, importance, salience,
-        project_id, session_id, created_at, updated_at, last_accessed_at, access_count,
-        valid_from, valid_until, metadata)
-       VALUES (@type, @content, @summary, @status, @source, @confidence, @importance, @salience,
-        @projectId, @sessionId, @ts, @ts, NULL, 0, @validFrom, @validUntil, @metadata)`)
+         (type, content, summary, status, source, confidence, importance, salience,
+          project_id, session_id, user_id, scope, created_at, updated_at, last_accessed_at, access_count,
+          valid_from, valid_until, metadata)
+         VALUES (@type, @content, @summary, @status, @source, @confidence, @importance, @salience,
+          @projectId, @sessionId, @userId, @scope, @ts, @ts, NULL, 0, @validFrom, @validUntil, @metadata)`)
         .run({
         type: input.type,
         content: input.content,
@@ -21,6 +30,8 @@ export function createMemory(input) {
         salience: input.salience ?? 0.5,
         projectId: input.projectId ?? null,
         sessionId: input.sessionId ?? null,
+        userId: uid,
+        scope,
         ts,
         validFrom: input.validFrom ?? null,
         validUntil: input.validUntil ?? null,

package/dist/db/repositories/users.js

@@ -0,0 +1,23 @@
+import { db, nowISO } from "../index.js";
+// Resolve or create a user by external identity (what clients pass as `userId`).
+// Returns the internal user id.
+export function ensureUser(externalId, name) {
+    const existing = db
+        .prepare("SELECT id FROM users WHERE external_id = ?")
+        .get(externalId);
+    if (existing)
+        return existing.id;
+    const res = db
+        .prepare("INSERT INTO users (external_id, name, created_at) VALUES (?, ?, ?)")
+        .run(externalId, name ?? null, nowISO());
+    return Number(res.lastInsertRowid);
+}
+// Map an external user id to its internal id, or null if unknown/absent.
+export function resolveUserId(externalId) {
+    if (!externalId)
+        return null;
+    const r = db
+        .prepare("SELECT id FROM users WHERE external_id = ?")
+        .get(externalId);
+    return r ? r.id : null;
+}

package/dist/index.js

@@ -12,6 +12,11 @@ import { recentInteractionsInput, getRecentInteractionsHandler, } from "./tools/
 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",
@@ -72,6 +77,31 @@ server.registerTool("consolidate", {
     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);