th-memory-mcp

th-memory-mcp

需求

• Node.js 22.23.4+、24.22.1+ 或 26.12.1+ — 仅支持已修补的发行版；此服务使用仅限 Node.js 的 API（better-sqlite3 原生构建、import.meta.url）。Node.js 20 已结束生命周期（EOL），不受支持。CI 会测试每个受支持版本线（22/24/26）的最低修补版本。
• npm — 用于运行 npm install、npm run build、npm test。无需外部服务、账户或 API 密钥——所有数据都存储在单个本地 SQLite 文件中。
• OpenCode — 加载 MCP 服务和自动捕获插件的宿主（任何支持通过 stdio 使用 MCP 和插件的构建版本）。该插件在 OpenCode Desktop/Node 22.5+ 上使用 node:sqlite，在基于 Bun 的命令行中则回退到 bun:sqlite。
• 操作系统：Windows / macOS / Linux — 跨平台（Node）；Windows：使用 setx 设置 MEMORY_DB_PATH，macOS/Linux：在 shell 配置文件中使用 export。

安全： 使用已修补的 Node.js 发行版——运行 npx is-my-node-vulnerable 检查运行时。npm audit 仅检查 npm 依赖，不检查 Node.js 核心 CVE。

快速开始

最快方式： 克隆后运行 npm run quickstart，即可构建、配置 opencode.json、部署插件并设置 MEMORY_DB_PATH——以下步骤是手动完成这些操作的方法。npm 替代方式： 运行 npm install -g th-memory-mcp（或 npx th-memory-mcp），并将 mcp.command 指向 th-memory-mcp 而不是 dist/index.js（插件仍需从此仓库获取；不再托管于 GitHub Packages）。

# 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. 将以下内容合并到 ~/.config/opencode/opencode.json 中（将 <REPO> 替换为克隆目录的绝对路径；可直接使用 opencode.example.json 中的现成配置块）。服务和插件必须使用同一个 MEMORY_DB_PATH 文件——系统/用户级环境变量对两者都有效；下方的 environment 仅适用于服务。示例规则：AGENTS.memory.example.md（可在项目级附加）。

{ "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. （可选）自动捕获：将 src/plugin/learning-capture.ts 复制到 ~/.config/opencode/plugins/
5. 重启 OpenCode（配置只在启动时加载），然后试试：“记住，我偏好 pnpm” → 新会话 → “我偏好使用什么包管理器？”

如果启动时报告 Failed to load plugin ... Received protocol 'bun:'，说明你复制的是旧版插件。请重新复制当前的 src/plugin/learning-capture.ts；它会先加载 node:sqlite，仅在 Bun 环境下回退到 bun:sqlite。

架构

OpenCode 加载插件 learning-capture（Node/Bun）——自动将提示词、工具调用和错误捕获到数据库中，并在压缩时注入个人资料——以及 MCP 服务 th-memory-mcp（Node stdio），通过同一个 SQLite 数据库提供 16 个工具；全局规则（memory-protocol.md）指导 AI 使用这些工具。

为什么选择 th-memory-mcp？

• 基于上下文学习，而非微调——捕获你的偏好、纠正和习惯，并在下次会话中回忆；数据不会离开你的设备。
• 100% 本地且私密——使用一个 SQLite 文件，无云服务、无外部 API；存储前会过滤机密信息（api_key=、password:、token）。
• 开销低且可靠——工具调用设有上限（延迟 < 10 ms，输出有界），即使数据库不可用也能平稳降级。
• 开源且可扩展——采用 MIT 许可证；提供 16 个有文档说明的工具、基于规则的提炼和自动捕获插件；仅需 Node 和 better-sqlite3（无需其他原生扩展）。

亮点

• 结构化记忆——包含带置信度评分的偏好，以及 lesson 记录（情境 → 错误 → 纠正），而非只有零散事实。
• 具备生命周期、时间和冲突感知能力——状态（active/stale/superseded/archived）、置信度/重要性/显著性评分、按类型衰减、用于还原特定时间点事实的有效期，以及替代链；重复项/矛盾项的处理会保留模糊证据的双方。
• 混合检索——get_context 将 FTS5 关键词搜索与无需依赖的词法模糊匹配（哈希 n-gram 相似度，512 维 FNV-1a）通过 RRF 融合结合起来，然后组装带令牌预算的上下文，并可选择扩展记忆图谱。
• 整合——将相似记忆聚类为派生记忆，并保留完整来源信息（derived_from 链接）。
• 原生支持泰语 / i18n——提炼时使用适配泰语的分词；泰语和英语可互换使用。

兼容其他运行环境

标准 MCP 服务：只要支持 MCP-over-stdio，即可使用全部 16 个工具；所有运行环境都通过 MEMORY_DB_PATH 共用一个 SQLite 文件。自动捕获需要钩子运行时（OpenCode 内置支持，Claude Code 需通过桥接实现）。

功能	OpenCode	Claude Code	Qwen Code	Codex	Cursor
16 个 MCP 工具	✅	✅	✅	✅	✅
自动捕获（后台）	✅ 插件	✅ 钩子	⚠️ 适配器	❌ 手动	❌ 规则
个人资料注入	✅ 压缩时	✅ UserPromptSubmit	❌ get_profile	❌ get_profile	❌ get_profile
词法模糊匹配	✅（v2.0）	✅（v2.0）	✅（v2.0）	✅（v2.0）	✅（v2.0）

• Claude Code（CLAUDE_CODE_HOOKS.md）——可直接使用的钩子取代插件：在 UserPromptSubmit/PreCompact 时捕获并注入个人资料，在 SessionEnd 时提炼。Qwen Code（QWEN_SETUP.md）——完整支持 MCP；钩子需要一个小型 Gemini-CLI 适配器。Codex（CODEX_SETUP.md）· Cursor（CURSOR_SETUP.md）——手动使用工具。

脚本

命令	说明
npm run build	编译 TypeScript → dist/
npm start	从 dist/index.js 运行 MCP 服务（stdio）
npm run distill	将交互记录提炼为个人资料部分，并清理旧数据（RETENTION_DAYS，默认值为 30）
npm test	构建并运行完整测试套件（32 个文件，75 项测试）
node test/<name>.test.mjs	运行单个测试套件：capture、distill、lifecycle、temporal、conflict、retrieval、graph、context、consolidation、benchmark、security
node test/smoke.mjs	通过 JSON-RPC 对全部 16 个工具运行端到端冒烟测试

工具（16 个）

工具	描述
remember	更新或插入偏好设置（类别+键）；重新保存时置信度增加 0.1（上限为 1.0）
recall	搜索偏好设置 + 经验（FTS5）+ 最近的匹配交互 — 开始新任务前运行
get_profile	个人资料分区 + 主要偏好设置 + 最近 5 条经验
save_lesson	根据更正记录一条经验（情境 / 错误 / 更正）
search_history	按关键词搜索以往提示词（200 个字符的摘要）
forget	按 ID 删除一行（偏好设置/经验/交互）（+type 可避免跨表 ID 冲突）
memory_stats	按类别统计数量、数据库大小、最早/最新交互、个人资料分区
get_recent_interactions	最近的原始交互（按类别筛选）— Smart Distill 的原料
export_memory	仅导出为 data/exports/ 下的 JSON（文件名会自动清理）
get_context	通过混合检索（+ 图扩展）获取与任务相关的记忆，并按 token 预算筛选
consolidate	通过嵌入相似度聚类相似记忆；可选择创建通过 derived_from 关联的派生记忆
link_memory	在两条记忆之间建立类型化链接：支持/矛盾/取代/derived_from/related_to/caused_by/depends_on
merge_memory	将重复记忆合并到规范记忆中（来源记忆标记为已取代；来源信息记录在 metadata.merged_from 中）
update_memory	就地更新字段；或在 content 发生变化时创建一条取代原记忆的新记忆（supersede=false 时就地编辑）
import_memory	从 JSON 导入（验证类型、去重，绝不盲目覆盖）；默认试运行，设置 apply=true 后插入
extract_memories	扫描最近的交互，查找表达记忆意图的短语并提出候选内容（确定性，不使用 LLM）；默认试运行，设置 apply=true 后创建（source=captured）

CLI（th-memory）

二进制文件	入口	用途
th-memory-mcp	dist/index.js	MCP 服务（stdio）— 上述 16 个工具
th-memory	dist/cli.js	零依赖本地 CLI（通过 MEMORY_DB_PATH 使用同一数据库）

用法：th-memory [--db <path>] [--json] [--plain] <command> [options] — 使用 th-memory <command> --help 查看各命令的帮助。highlight/recall --highlight：在彩色 TTY 中为匹配项添加下划线（ESC[4m），否则使用 [mem]…[/mem] 标记（管道输入、--plain、--json）。

标志	效果
--db <path>	使用此 SQLite 文件（设置 MEMORY_DB_PATH）
--json	输出 JSON {ok,data}，而非纯文本
--plain / --no-color	禁用颜色
-h, --help / -V, --version	显示帮助 / 输出版本

命令	用法
remember	remember --category <c> --key <k> --value <v|-> — 保存偏好设置（--value - 会从 stdin 读取）
recall	recall <topic> [--limit <n>] [--highlight] — 搜索记忆
forget	forget <id> [--type <t>] — 按 ID 删除（t：memory|preference|lesson|interaction）
export	export [--include-interactions] [--filename <n>] — 导出到 data/exports/*.json
import	import (--file <p>|--json <s>) [--apply] [--user-id <id>] — 导入备份（默认试运行）
stats	stats — 记忆统计信息
profile	profile — 提炼后的用户资料
history	history [--query <q>] [--limit <n>] — 搜索以往提示词（不提供查询条件 = 最近的提示词）
recent	recent [--limit <n>] [--kind <k>] — 最近的交互（k：prompt|tool_call|error）
highlight	highlight [text...] -q <topic> [--limit <n>] — 高亮匹配主题的内容（文本为空 = 从 stdin 管道读取）

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

日常使用

AI 可交替使用泰语和英语；长期维护：npm run distill 会汇总统计数据并清理 30 天前的交互记录。

• “记住……” → remember — 保存偏好
• “总结记忆” / “提炼记忆” → Smart Distill — AI 读取 get_recent_interactions，发现模式并自行保存洞见
• “我的记忆怎么样？” / “记忆状态” → memory_stats
• “导出记忆” / “备份记忆” → export_memory
• “搜索历史……” → search_history · “忘掉……” → forget

data/ 结构

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

已知限制

• 静态数据未加密 — data/memory.db 是纯文本、未加密的 SQLite 数据库（WAL 模式，better-sqlite3）；“100% 本地且私密”表示不会向云端或网络传输数据，并不表示静态数据已加密——任何能访问文件系统的人都可以读取。对于敏感数据：使用操作系统全盘加密（BitLocker / FileVault / LUKS），或选择 SQLCipher 构建（需原生重新构建 + 密钥管理）；默认不会在代码中加密（src/db/index.ts 中有说明）。
• 单用户，无身份验证层（Batch B-3） — userId / sessionId / projectId 由调用方提供，服务内部不进行身份验证或授权检查；作用域隔离（检索、get_context、图谱、consolidate、link_memory、merge_memory）仅依据调用方传入的值，因此只要传入不同的 ID，就可以读写任何作用域。适用于单用户本地进程；若没有前置身份验证层来强制使用正确的 userId（projectId / sessionId），请勿让不受信任的用户共用同一服务/数据库。按设计，本项目不内置身份验证功能。

许可证

MIT © 2026 worakorn-prince — 完整文本请参阅 LICENSE。