th-memory-mcp
Summary: This server gives AI coding agents local-first, persistent memory over MCP, backed by a single SQLite file with hybrid full-text/vector retrieval.
Store and update user preferences by category/key.
Recall relevant preferences, lessons, and recent interactions before tasks.
Retrieve a distilled user profile and assembled task context with token budgeting.
Save lessons learned from corrections.
Search past prompts and inspect recent captured interactions.
Update, forget, merge, link, and consolidate memory entries.
Export or import memories as JSON, with dry-run/apply modes.
Extract memory candidates from recent interactions.
Get memory statistics and audit history.
Optionally enable RBAC/scope isolation and database encryption; works offline with no cloud or API keys.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@th-memory-mcp remember that I prefer pnpm over npm"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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 |
|
๐ 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 |
๐ด Offline by default | no network calls, no accounts, no API keys โ the database is a single local file |
Related MCP server: MCP Vector Memory
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 |
| 103.9 / 106.2 / 90.3 | 75.8 / 87.2 / 82.2 | 76.7 / 74.4 / 73.5 |
| 102.5 / 116.5 / 86.2 | 70.3 / 70.7 / 80.5 | 70.5 / 68.5 / 69.5 |
| 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
Install in 60 seconds
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 (or run npm run quickstart).
Optional agent rules: setup/AGENTS.memory.example.md.
Documentation
Topic | Where |
Full documentation โ requirements, architecture, every tool, the CLI, daily usage | |
Full documentation (เนเธเธข) | |
Authentication, RBAC and scope isolation | |
Encryption at rest, key rotation, backup / verify / restore / drill | |
Threat model and residual risks | |
Upgrade from 2.x | |
Performance measurements | |
Thai search internals (reusable module) | |
Changelog |
Harness setup
Harness | Guide |
OpenCode |
|
Claude Code | |
Codex | |
Cursor | |
Qwen Code | |
DeepSeek Harness |
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.
License
MIT ยฉ 2026 worakorn-prince
Available Tools
16 toolsconsolidateConsolidate memoriesA
Cluster similar memories via embedding similarity and optionally create derived/consolidated memories linked via 'derived_from'. Use during periodic consolidation.
Inputs: derive, userId, projectId, sessionId, +2 more.
export_memoryExport memory to JSONA
Export preferences, lessons, profile (and optionally raw interactions) to a JSON file under data/exports/. Only writes inside that directory. Returns the file path, size in bytes and a JSON preview.
Inputs: filename, includeInteractions.
extract_memoriesExtract memories from interactionsA
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).
Inputs: kind, apply, limit, userId, +1 more.
forgetForget a memory entryA
Delete one memory row (preference, lesson or interaction) by id and sync the search index. Pass type when you know it (ids from remember are preference ids, from save_lesson are lesson ids).
Inputs: target_id (required), type.
get_contextGet assembled contextB
Assemble relevant memories for the current task via hybrid retrieval (+ optional memory-graph expansion), with token budgeting. Use to load memory into context before a task.
Inputs: limit, query, userId, maxTokens, +4 more.
get_profileGet user profileA
Get the distilled user profile: profile sections, top preferences by confidence (max 15), and the 5 most recent lessons. Optional userId/sessionId/projectId scope the auto-projected memories; without them only GLOBAL memories are included.
Inputs: userId, projectId, sessionId.
get_recent_interactionsRecent interactionsA
List recently captured raw interactions (newest first) as [id] ts [kind] content lines. Optionally filter by kind. Use for auditing history or before distilling memory.
Inputs: kind, limit, sessionId.
import_memoryImport memoriesA
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.
Inputs: file, json, apply, userId, +1 more.
link_memoryLink two memoriesC
Create a typed relationship between two memories in the graph (supports/contradicts/supersedes/derived_from/related_to/caused_by/depends_on).
Inputs: relation (required), sourceId (required), targetId (required).
memory_statsMemory statisticsA
Summarize memory usage: interaction counts by kind, preference/lesson totals, DB file size, oldest/newest interaction timestamps, and profile sections.
Inputs: no named parameters.
merge_memoryMerge memoriesA
Merge a duplicate/near-duplicate memory into a canonical one. The source becomes superseded and provenance is recorded in metadata.merged_from.
Inputs: sourceId (required), targetId (required).
recallRecall memoryA
Search preferences + lessons via full-text index, plus recent matching interactions. Use before starting a new task.
Inputs: topic (required), limit.
rememberRemember preferenceA
Save or update a user preference (category+key upsert). Re-saving the same key increases confidence by 0.1 (cap 1.0). Returns the row id for forget().
Inputs: key (required), value (required), category (required).
save_lessonSave lessonA
Record a lesson learned from a correction: what situation, what mistake, what is the correct way. Call immediately after the user corrects your work.
Inputs: mistake (required), situation (required), correction (required).
search_historySearch prompt historyA
Search past user prompts (kind='prompt') by keyword. Returns timestamped snippets truncated to 200 chars each.
Inputs: query (required), limit, sessionId.
update_memoryUpdate a memoryA
Update mutable fields (summary/importance/confidence/valid_from/valid_until/metadata) in place. If content changes, a superseding memory is created by default (set supersede=false to edit in place).
Inputs: id (required), content, summary, metadata, +5 more.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelogโฆ
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.
Maintenance
Related MCP Connectors
Persistent memory for Claude Code and Cursor. Stop re-explaining your project every session.
Persistent cross-session memory shared by Codex, Claude Code, ChatGPT, and other AI agents.
Shared memory for coding agents. Stop re-explaining your codebase every session.
Long-term memory for AI assistants. Isolated per-user storage, recall across conversations.
Related MCP Servers
- -licenseNot gradedqualityNot gradedmaintenanceProvides persistent local memory functionality for AI assistants, enabling them to store, retrieve, and search contextual information across conversations with SQLite-based full-text search. All data stays private on your machine while dramatically improving context retention and personalized assistance.3-
- AlicenseNot gradedqualityNot gradedmaintenanceProvides AI coding agents with persistent, long-term memory through local semantic search and SQLite storage. It enables agents to save and retrieve architectural decisions or project context across different conversation sessions without requiring cloud services.MIT
- AlicenseAqualityDmaintenanceProvides persistent cross-session memory and full-text search for AI coding assistants, storing project context, decisions, and preferences while enabling searchable access to conversation history via local SQLite.81MIT
- AlicenseAqualityBmaintenanceProvides AI coding assistants with persistent memory storage using a local SQLite database. Enables tools to remember project details, notes, and relationships across sessions to maintain context and reduce repetitive explanations.174MIT