Th Memory MCP

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)

1. Merge this into ~/.config/opencode/opencode.json (replace 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", " /dist/index.js"], "enabled": true, "environment": { "MEMORY_DB_PATH": " /data/memory.db" } } } }

1. (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
2. 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- 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 ] [--json] [--plain] [options] — per-command help via th-memory --help. highlight/recall --highlight: matches underlined (ESC[4m) on a color TTY, else [mem]…[/mem] markers (piped, --plain, --json).

| export | `export [--include-int