th-memory-mcp

Status: v2.2.8 — a temporal, conflict-aware, hybrid-retrieval memory engine. 16 MCP tools, 25 passing test suites. Non-destructive schema migration from v1 (all v1 data preserved). New in v2.2: 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. New in v2.2.3: scope-enforced retrieval, graph scope isolation, export/import round-trip, hardened import path (realpath), strict import validation, N+1 query elimination, cold/ablation benchmark, and MEMORY_RETRIEVAL_MODE switch. New in v2.2.7: synced secret filter between Claude hook and capture-core (6-pattern redact instead of line-drop), fixed err() to return isError:true per MCP spec, fixed backup rotation (backup only when migrations pending + prune to 5 files), and added hook error logging for SessionEnd distill. New in v2.2.8: fixed scope contamination 0.75→0 (critical) and conflict false 0→1 (GLOBAL leak), fixed graph hop1 0.52→1.0 via includeGraph, and rescaled benchmark profiles to 5K/20K/100K/500K/1M (pre-commit now quick 5K + normal 20K only).

Requirements

• Node.js >= 20 — the server uses Node-only APIs (the better-sqlite3 native build and import.meta.url resolution) and the MCP SDK requires a modern runtime. CI tests on Node 20.x and 22.x.
• npm — to install dependencies and run the build/test scripts (npm install, npm run build, npm test).
• OpenCode — the host that loads this MCP server and the auto-capture plugin. Any build supporting MCP over stdio + plugins works; the plugin runs on OpenCode's bundled Bun runtime.
• OS: Windows / macOS / Linux — the server is cross-platform (Node). The auto-capture plugin runs wherever OpenCode's Bun runtime runs. Windows note: MEMORY_DB_PATH is easiest to set with setx; on macOS/Linux use export in your shell profile.

No external services, accounts, or API keys are required — everything lives in a single local SQLite file.

Quick Start

Fastest path: after cloning, run npm run quickstart — it builds, wires opencode.json, deploys the plugin, and sets MEMORY_DB_PATH for you in one command. The steps below show exactly what it does (use them if you prefer manual control).

Install via npm (alternative): install the server globally with npm install -g th-memory-mcp (or run it on demand with npx th-memory-mcp), then point the mcp command in opencode.json to th-memory-mcp instead of the built dist/index.js. The auto-capture plugin still comes from this repo (copy src/plugin/learning-capture.ts as described in step 4 below).

# 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
#    Windows (PowerShell):
setx MEMORY_DB_PATH "$PWD/data/memory.db"
#    macOS / Linux (add to your shell profile, e.g. ~/.zshrc):
# export MEMORY_DB_PATH="$PWD/data/memory.db"

3. Merge this into your ~/.config/opencode/opencode.json (replace <REPO> with the absolute clone path):

{
  "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: copy src/plugin/learning-capture.ts → ~/.config/opencode/plugins/
5. Restart OpenCode
6. Try it: "Remember that I prefer pnpm" → new session → "What package manager do I prefer?"

Architecture

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)  ── 16 tools read/write the same SQLite DB
                                                      ▲
                               Global instructions (memory-protocol.md) teach the AI to use the tools

See ARCHITECTURE_v2.md for the full architecture spec.

Why th-memory-mcp?

LLMs don't remember you between sessions — every new chat starts blank. th-memory-mcp gives your AI a private, local long-term memory:

• Context-based learning, not fine-tuning — it captures your preferences, corrections, and habits, then recalls them into context next time. Same mechanism as the memory features of leading AI products, without sending any data off your machine.
• 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, 16 documented tools, a rule-based distill, and an auto-capture plugin you can adapt.

Works with other harnesses

th-memory-mcp is a standard MCP server, so the 9 tools run anywhere MCP-over-stdio is supported. Full auto-capture (background prompt/tool/error capture + profile injection) needs a hook runtime — OpenCode has it built in; Claude Code gets it via our hooks bridge; Codex and Cursor use the tools manually (no hook runtime yet).

• Claude Code: see CLAUDE_CODE_HOOKS.md — drop-in hooks replicate the OpenCode plugin (capture + profile injection on UserPromptSubmit/PreCompact, rule-based distill on SessionEnd).
• Qwen Code: see QWEN_SETUP.md — MCP works fully; hooks use the Gemini-CLI schema so auto-capture needs a small adapter.
• Codex: see CODEX_SETUP.md
• Cursor: see CURSOR_SETUP.md

All harnesses share one SQLite file via MEMORY_DB_PATH, so memory captured anywhere is readable everywhere.

Highlights

• Structured memory — preferences with confidence scoring plus dedicated lesson records (situation → mistake → correction) for capturing corrections, not just flat facts.
• Lifecycle & temporal — every memory has a lifecycle state (active/stale/superseded/archived), confidence/importance/salience scoring, per-type decay, and validity intervals so the AI can reason about point-in-time truth and supersession chains.
• Conflict-aware — duplicate detection, contradiction detection, and update/supersession resolution preserve both sides of ambiguous evidence instead of silently overwriting.
• Hybrid retrieval — get_context blends FTS5 keyword search with a dependency-free lexical fuzzy matching (hashed n-gram similarity, 512-dim FNV-1a) (RRF fusion + scoring), then assembles a token-budgeted context with optional memory-graph expansion.
• Consolidation — periodic clustering of similar memories into derived memories with full provenance (derived_from links).
• First-class Thai / i18n — Thai-aware tokenization in distill; the AI accepts Thai and English interchangeably.
• Private by default — a single local SQLite file, no cloud, no API keys, with secret lines (api_key=, password:, token) filtered before storage.
• Cross-harness — runs on OpenCode, Claude Code, Codex, and Cursor sharing one DB; auto-capture + profile injection via OpenCode plugin or Claude hooks.
• Lightweight & resilient — Node + better-sqlite3, no extra native extensions; every tool degrades gracefully so the AI keeps working if the DB is unavailable.

Scripts