th-memory-mcp
<img src="access/Banner.png" alt="th-memory-mcp Banner" width="100%" />
[](https://www.npmjs.com/package/th-memory-mcp) [](https://www.npmjs.com/package/th-memory-mcp) [](LICENSE) [](https://nodejs.org) [](https://github.com/worakorn-prince/th-memory-mcp/actions/workflows/ci.yml)
[](https://mcpservers.org/servers/worakorn-prince/th-memory-mcp) [](https://glama.ai/mcp/servers/worakorn-prince/th-memory-mcp) [](https://mcprush.com/to/th-memory-mcp?ref=badge) [](https://addonaudit.com/addon/io-github-worakorn-prince-th-memory-mcp/)
# th-memory-mcp
**Local-first memory for AI coding agents, over MCP.** One SQLite file remembers your
preferences, lessons, decisions and project context, then hands the right slice back to the
agent before each task. Hybrid FTS5 + local vectors, Thai/English aware, no cloud, no API keys.
## What you get
| | |
|---|---|
| ๐ง **16 MCP tools** | `remember`, `recall`, `get_context`, `get_profile`, `save_lesson`, `consolidate`, `link_memory`, `merge_memory`, `update_memory`, `forget`, `search_history`, `get_recent_interactions`, `memory_stats`, `export_memory`, `import_memory`, `extract_memories` |
| ๐ **Hybrid retrieval** | FTS5 (Thai word-segmented, tone-tolerant) fused with 512-dim local vectors via RRF, then rescored by confidence, importance, recency and scope |
| ๐ฐ **Temporal + conflict-aware** | validity windows, supersession chains, duplicate/contradiction classification; ambiguous evidence is preserved, never silently destroyed |
| ๐ **Works with your harness** | OpenCode plugin with background capture; Claude Code hooks; Codex, Cursor, Qwen Code, DeepSeek Harness via MCP |
| ๐ **Opt-in security** | RBAC over every tool, identity-derived scope isolation with grants, a content-free `audit_log`, whole-DB SQLCipher encryption with rotation/backups/drills, and per-user capture attribution |
| ๐ด **Offline by default** | no network calls, no accounts, no API keys โ the database is a single local file |
## Performance
Measured with the internal harness on one machine, seed 42; profile normal = 20,000 memories / 5,000 queries. Each cell shows the latest three runs, oldest โ newest.
| metric | 2.5.1 | 3.0.0 | 3.0.1 |
|---|---:|---:|---:|
| insert throughput (mem/s) | 352.6 / 331.9 / 320.5 | 331.7 / 277.4 / 361.5 | 348.0 / 337.4 / 352.9 |
| `retrieve` @20k (ms) | 103.9 / 106.2 / 90.3 | 75.8 / 87.2 / 82.2 | 76.7 / 74.4 / 73.5 |
| `get_context` @20k (ms) | 102.5 / 116.5 / 86.2 | 70.3 / 70.7 / 80.5 | 70.5 / 68.5 / 69.5 |
| `recall` p95 (ms) | 1.00 / 2.00 / 1.00 | 1.00 / 2.00 / 1.00 | 2.00 / 2.00 / 1.00 |
| DB size (MB) | 101.1 / 101.1 / 101.1 | 101.1 / 101.3 / 100.7 | 100.7 / 100.7 / 100.7 |
Observation: v3.0.x `retrieve` / `get_context` took ~68โ87 ms vs ~86โ116 ms for 2.5.1; peak RSS was higher (quick ~262โ306 MB vs ~110โ199 MB; normal ~432 MB vs ~113โ203 MB). The auth/encryption modules and native `better-sqlite3-multiple-ciphers` coincide with the increase, but these runs do not isolate which component consumed the extra memory.
[Full performance history, three-run tables, and quality gates โ `docs/PERFORMANCE.md`](docs/PERFORMANCE.md)
## Install in 60 seconds
```bash
git clone https://github.com/worakorn-prince/th-memory-mcp.git
cd th-memory-mcp && npm install && npm run build
# one DB shared by the server and the plugin
setx MEMORY_DB_PATH "%CD%\data\memory.db" # Windows
# export MEMORY_DB_PATH="$PWD/data/memory.db" # macOS/Linux (add to your shell profile)
```
Then register the MCP server with the ready-made block in
[`setup/opencode.example.json`](setup/opencode.example.json) (or run `npm run quickstart`).
Optional agent rules: [`setup/AGENTS.memory.example.md`](setup/AGENTS.memory.example.md).
## Documentation
| Topic | Where |
|---|---|
| **Full documentation** โ requirements, architecture, every tool, the CLI, daily usage | [`docs/Docs.md`](docs/Docs.md) |
| Full documentation (เนเธเธข) | [`docs/Docs.th.md`](docs/Docs.th.md) |
| Authentication, RBAC and scope isolation | [docs/Docs.md ยง Authentication](docs/Docs.md#authentication-opt-in) |
| Encryption at rest, key rotation, backup / verify / restore / drill | [docs/Docs.md ยง Encryption](docs/Docs.md#encryption-at-rest-phase-4-opt-in-requires-memory_encryptionon) |
| Threat model and residual risks | [`SECURITY.md`](SECURITY.md) |
| Upgrade from 2.x | [`MIGRATION_v3.md`](MIGRATION_v3.md) |
| Performance measurements | [`docs/PERFORMANCE.md`](docs/PERFORMANCE.md) |
| Thai search internals (reusable module) | [`docs/thai-fts.md`](docs/thai-fts.md) |
| Changelog | [`CHANGELOG.md`](CHANGELOG.md) |
## Harness setup
| Harness | Guide |
|---|---|
| OpenCode | [`setup/opencode.example.json`](setup/opencode.example.json) + `npm run quickstart` |
| Claude Code | [`setup/CLAUDE_CODE_HOOKS.md`](setup/CLAUDE_CODE_HOOKS.md) |
| Codex | [`setup/CODEX_SETUP.md`](setup/CODEX_SETUP.md) |
| Cursor | [`setup/CURSOR_SETUP.md`](setup/CURSOR_SETUP.md) |
| Qwen Code | [`setup/QWEN_SETUP.md`](setup/QWEN_SETUP.md) |
| DeepSeek Harness | [`setup/DSH_SETUP.md`](setup/DSH_SETUP.md) |
## Security in one paragraph
With no environment variables set, the server behaves exactly like 2.5.x: no auth, plaintext
database, no extra I/O. Security is opt-in and independent: `MEMORY_AUTH=on` adds a verified
identity, a single role gate over all 16 tools, identity-derived scope isolation with explicit
grants, and an `audit_log`; `MEMORY_ENCRYPTION=on` encrypts the whole database (SQLCipher via
`better-sqlite3-multiple-ciphers`) and adds `db rekey`, `db verify-backup`, `db restore` and
`db drill`. Details, threat model and residual risks: [`SECURITY.md`](SECURITY.md).
## License
[MIT](LICENSE) ยฉ 2026 worakorn-prince
TDQS
Scored across 16 tools
Most tools target distinct actions and memory types, but retrieval is split across recall, get_context, get_profile, and search_history, and remember vs update_memory has some conceptual overlap. The descriptions clarify these boundaries, but an agent may still hesitate over which retrieval tool to use first.
Most names follow a clear snake_case verb_noun pattern such as save_lesson, get_profile, link_memory, and update_memory. A few exceptions like remember, recall, forget, consolidate, and memory_stats deviate from that pattern but remain readable and predictable enough.
At 16 tools the set is slightly on the heavy side, but each tool covers a meaningful part of a sophisticated memory lifecycle: capture, retrieval, curation, graph operations, import/export, and stats. It does not feel padded, though a smaller surface could reduce cognitive load.
The tool surface covers the full memory lifecycle: creation via remember/save_lesson/extract/import, retrieval via recall/get_context/profile/history, updates, deletion, linking, merging, consolidation, export, and stats. No obvious CRUD or lifecycle gap remains for the stated memory-management purpose.