Th Memory MCP README

th-memory-mcp

Requirements

• Node.js 22.23.4+, 24.22.1+, or 26.12.1+ — patched releases only; the server uses Node-only APIs (better-sqlite3 native build, import.meta.url). Node.js 20 is EOL and unsupported. CI tests the minimum patched version of each supported line (22/24/26).
• npm — for npm install, npm run build, npm test. No external services, accounts, or API keys — everything lives in a single local SQLite file.
• OpenCode — the host that loads the MCP server and the auto-capture plugin (any build with MCP over stdio + plugins). The plugin uses node:sqlite on OpenCode Desktop/Node 22.5+ and falls back to bun:sqlite on the Bun-based CLI.
• OS: Windows / macOS / Linux — cross-platform (Node); Windows: set MEMORY_DB_PATH with setx, macOS/Linux: export in your shell profile.

Security: Use a patched Node.js release — check your runtime with npx is-my-node-vulnerable. npm audit covers npm dependencies only, not Node.js core CVEs.

Audit: Independently smoke-tested by AddonAudit on v2.4.1 — an automated test, not a security guarantee; the one high advisory it found was fixed in 2.4.2, and fresh installs from 2.4.3 onward report 0 critical/high advisories.

Quick Start

Fastest path: npm run quickstart (after cloning) builds, wires opencode.json/opencode.jsonc, deploys the plugin, and sets MEMORY_DB_PATH — the steps below are the manual equivalent. npm alternative: npm install -g th-memory-mcp (or npx th-memory-mcp) and point mcp.command to th-memory-mcp instead of dist/index.js (plugin still from this repo; not on GitHub Packages anymore).

# 1. Clone and build
git clone https://github.com/worakorn-prince/th-memory-mcp.git
cd th-memory-mcp && npm install && npm run build
# 2. Share one DB between the server and the plugin
setx MEMORY_DB_PATH "$PWD/data/memory.db"      # Windows (PowerShell)
# export MEMORY_DB_PATH="$PWD/data/memory.db"  # macOS/Linux — add to your shell profile (~/.zshrc)

3. Merge this into ~/.config/opencode/opencode.json (replace <REPO> with the absolute clone path; ready-made block in opencode.example.json). MEMORY_DB_PATH must be the SAME file for server and plugin — a system/user-level env var covers both; environment below covers the server only. Example rules: AGENTS.memory.example.md (attachable at project level).

{ "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: deploy the dual-mode plugin to a directory (OpenCode V2 only auto-discovers local plugins from a folder) — src/plugin/learning-capture.ts → ~/.config/opencode/plugins/learning-capture/index.ts
5. Restart OpenCode (config loads at startup only), then try: "Remember that I prefer pnpm" → new session → "What package manager do I prefer?"

The plugin works in both modes: OpenCode V2 calls the default export's id + setup(ctx) (domain hooks for prompt/tool/compaction/failure events), while V1 (1.18.29+) calls the same default export's server(), which returns the legacy hook object. One file, no runtime import of @opencode/plugin (types only), so it loads under both Node and Bun.

If startup reports Failed to load plugin ... Received protocol 'bun:' or the plugin is silently ignored on V2, you are on an older install layout. Re-deploy the current src/plugin/learning-capture.ts to ~/.config/opencode/plugins/learning-capture/index.ts; a legacy ~/.config/opencode/plugins/learning-capture.ts is renamed to .bak-<timestamp> by npm run quickstart (never deleted). It loads node:sqlite first and only falls back to bun:sqlite under Bun.

Architecture

OpenCode loads the plugin learning-capture (dual-mode V1/V2, Node/Bun) — auto-captures prompt/tool/error into the DB, injects the profile on compaction — and the MCP server th-memory-mcp (Node stdio) exposing the 16 tools on that same SQLite DB; global rules (memory-protocol.md) teach the AI to use them.

Why th-memory-mcp?

• Context-based learning, not fine-tuning — captures your preferences, corrections, and habits, then recalls them next session; no data leaves your machine.
• 100% local & private — one SQLite file, no cloud, no external API; secrets (api_key=, password:, token) filtered before storage.
• Low overhead & resilient — tool calls are capped (latency < 10 ms, bounded output) and degrade gracefully if the DB is unavailable.
• Open & extensible — MIT licensed; 16 documented tools, rule-based distill, auto-capture plugin; Node + better-sqlite3 only (no extra native extensions).

Highlights

• Structured memory — preferences with confidence scoring plus lesson records (situation → mistake → correction), not just flat facts.
• Lifecycle, temporal & conflict-aware — states (active/stale/superseded/archived), confidence/importance/salience scoring, per-type decay, validity intervals for point-in-time truth and supersession chains; duplicate/contradiction resolution keeps both sides of ambiguous evidence.
• Hybrid retrieval — get_context blends FTS5 keyword search with dependency-free lexical fuzzy matching (hashed n-gram similarity, 512-dim FNV-1a) via RRF fusion, then assembles a token-budgeted context with optional memory-graph expansion.
• Consolidation — clusters similar memories into derived ones with full provenance (derived_from links).
• First-class Thai / i18n — Thai-aware tokenization in distill; Thai and English accepted interchangeably.

Works with other harnesses

A standard MCP server: 16 tools anywhere MCP-over-stdio works; all harnesses share one SQLite file via MEMORY_DB_PATH. Auto-capture needs a hook runtime (built into OpenCode, bridged for Claude Code).

• Claude Code (CLAUDE_CODE_HOOKS.md) — drop-in hooks replace the plugin: capture + profile injection on UserPromptSubmit/PreCompact, distill on SessionEnd. Qwen Code (QWEN_SETUP.md) — MCP fully; hooks need a small Gemini-CLI adapter. Codex (CODEX_SETUP.md) · Cursor (CURSOR_SETUP.md) — manual tools.

Scripts

Tools (16)

CLI (th-memory)

Usage: th-memory [--db <path>] [--json] [--plain] <command> [options] — per-command help via th-memory <command> --help. highlight/recall --highlight: matches underlined (ESC[4m) on a color TTY, else [mem]…[/mem] markers (piped, --plain, --json).

th-memory remember --category coding_pref --key package_manager --value pnpm
th-memory recall pnpm --limit 5
echo "I prefer pnpm for installs" | th-memory highlight -q pnpm

Daily usage

The AI accepts Thai and English interchangeably; long-term care: npm run distill summarizes stats and prunes interactions older than 30 days.

• "Remember that..." → remember — save a preference
• "Summarize memory" / "distill memory" → Smart Distill — AI reads get_recent_interactions, finds patterns, saves insights itself
• "How is my memory?" / "memory status" → memory_stats
• "Export memory" / "backup memory" → export_memory
• "Search history..." → search_history · "Forget..." → forget

data/ structure

data/
├── memory.db          # SQLite (WAL mode) — main DB (+ .db-wal, .db-shm); path overridable via MEMORY_DB_PATH
└── exports/           # JSON files from export_memory (writeable only in this dir)
# everything in data/ is git-ignored

Known Limitations

• No encryption at rest — data/memory.db is plain, unencrypted SQLite (WAL mode, better-sqlite3); "100% local & private" means no cloud/network exfiltration, not encrypted at rest — anyone with filesystem access can read it. For sensitive data: OS full-disk encryption (BitLocker / FileVault / LUKS) or an opt-in SQLCipher build (native rebuild + key management); no in-code encryption by default (src/db/index.ts documents this).
• Single-user, no auth layer (Batch B-3) — userId / sessionId / projectId are caller-supplied with no authentication or authorization check inside the server; scope isolation (retrieval, get_context, graph, consolidate, link_memory, merge_memory) binds only to caller-sent values, so any scope is readable/writable by passing a different id. Suitable for a single-user local process; do not share one server/DB across untrusted users without an auth layer in front enforcing the correct userId (projectId / sessionId). No auth is built in by design.

License

MIT © 2026 worakorn-prince — see LICENSE for the full text.