Coding Memory MCP

Coding Memory MCP 是一个面向 Cursor、Claude Code、Codex、Qoder、Trae 等 AI 编程工具的本地长期记忆系统。它的目标不是简单保存聊天记录，而是把项目事实、用户偏好、工程决策、错误经验、文件关系和可复用工作流沉淀为一个可检索、可扩散、可反思的共享记忆层。

一句话目标：

给所有 AI 编程助手接入同一个本地记忆大脑，让它们跨会话、跨工具、跨项目地记住「发生过什么、为什么这么做、下次怎么做更好」。

当前版本：1.0.8（完整功能版 + Web 管理台 + 多 IDE 一行安装 / HTTP Leader 选举）

分层交付

阶段	目标	关键能力	状态
MVP-Core	可依赖的项目级笔记与检索	remember / search / recall_context / list / forget、FTS、scope 硬隔离、secret 防护、CLI	✅
MVP-Plus	可解释联想与可选沉淀	高置信实体图、2-hop 扩散、explain、reflect（默认 preview）	✅
完整版（1.0.0）	语义与技能	embedding（可选）、skills、MCP Resources、feedback、update/merge/link	✅
Web 管理台	本地可视化与配置	HTTP API（可嵌入静态）、记忆/Skill CRUD、LLM Provider、Reflect、检索实验室、Sessions、审计、图谱	✅

先保证写入、隔离、检索正确，再叠加图扩散、反思与向量。

文档导航

用户与架构（推荐阅读）

• 使用文档 — npm 安装、主流 AI IDE 接入、MCP Tools、Scope、FAQ
• 技术架构文档 — 分层架构、数据流、存储、检索、安全
• 功能模块文档 — 各模块职责、流程、代码路径
• Web 管理台与 LLM 接入方案 — HTTP API、管理台模块、分阶段计划
• 会话收集与多 IDE 自动化 — 收集原理、Hook、多 IDE
• 上下文压缩 — recall 档 A/B/C + tiktoken
• HTTP API OpenAPI 附录

设计与规范

• 需求方案
• 技术方案（归档；以 10/11 为准）
• MCP 接口设计
• 数据模型与数据库设计
• 激活扩散检索算法
• Agent 工作流与跨工具集成
• 实现路线图
• 测试、评估与安全

推荐实现顺序

1. SQLite（WAL）存储、repo 身份、基础 CRUD。
2. memory.remember / list / forget + secret redaction + 统一 {ok,data} 响应。
3. FTS5 搜索、scope 硬隔离、CLI。
4. memory.recall_context + 归一化 ranking + retrieval fixtures。
5. 安装各工具规则模板（集成契约）。
6. 高置信实体图、2-hop 扩散、memory.explain。
7. memory.reflect（mock / preview；远程 opt-in）。
8. 可选 embedding、skill、resources、feedback。

技术栈

• Runtime: Node.js 20+
• Language: TypeScript
• Protocol: Model Context Protocol
• Storage: SQLite（WAL）
• Full-text search: SQLite FTS5（trigram / n-gram 策略）
• Vector search: 内存 cosine（hash / OpenAI embedding，默认关闭）
• Embedding: hash 或 OpenAI，需 CODING_MEMORY_EMBEDDING_ENABLED=true
• Test: Vitest（92 条）
• Web Admin: React + Ant Design + Rsbuild（packages/admin）
• HTTP API: Hono（src/http，默认 127.0.0.1:3721；生产可嵌入 Admin 静态）
• Token 估算: js-tiktoken（cl100k_base）

中文检索说明

使用 trigram/n-gram 友好匹配，不是完整中文分词。对中文子串和中英混合通常可用，但不等价于 jieba 级分词。

建议：

• 重要记忆补充英文 tags / summary，提高跨语言可检索性。
• 用 CLI search / recall 验证实际召回。
• 开启 embedding 可改善语义相近但字面不同的召回。

集成契约

记忆系统依赖 agent 调用工具，并可选 Hook 兜底。推荐用一行脚本安装（见下方「快速开始」），或手工放入模板：

• templates/agents.md
• templates/cursor-user-rules.md（全局）+ templates/cursor-rules.md（项目）+ hooks/reflect-on-stop.sh
• templates/codex-instructions.md
• templates/claude-instructions.md
• templates/qoder-instructions.md
• templates/trae-instructions.md

会话收集原理（为何不自动读 IDE 聊天记录、推荐 Hook 全自动方案）：见 docs/13-session-collection-and-multi-ide-automation.md。

多工具必须指向同一个本地 DB（如 CODING_MEMORY_DB=~/.coding-memory/memory.db）。

快速开始（推荐：一行接入 IDE）

在业务项目根目录（无需先 clone 本仓库）：

# Cursor（MCP → 用户级；全局 Rules → ~/.cursor/rules/coding-memory-global.mdc；项目 Rules/Hooks → 当前项目）
# 也可用 --ide claude|codex|qoder|trae|all
curl -fsSL https://raw.githubusercontent.com/ChinaCarlos/coding-memory-mcp/main/scripts/remote-install.sh | bash -s -- --ide cursor

coding-memory ping
# Admin（任一 MCP 进程可作为 Leader 自动拉起）：http://127.0.0.1:3721/

仅装 CLI / 包：

npm install -g coding-memory-mcp
coding-memory ping
# MCP：coding-memory-mcp
# Admin：node "$(npm root -g)/coding-memory-mcp/dist/http/server.js"

包地址：https://www.npmjs.com/package/coding-memory-mcp

分 IDE 步骤：使用文档 §3.1 · §5。

从源码开发（可选）

pnpm install && pnpm build && pnpm test
pnpm cli ping
pnpm dev          # API :3721 + Admin :3722
pnpm start:http   # 生产一体 Admin :3721

npm 脚本一览（源码仓）

命令	说明
pnpm dev	一键开发：HTTP API + 管理台（concurrently）
pnpm build	一键构建：后端 tsc + 前端 Rsbuild
pnpm dev:http	仅 HTTP API（3721）
pnpm dev:admin	仅管理台 dev server（3722）
pnpm dev:mcp	仅 MCP stdio（给 Cursor 用）
pnpm build:server	仅编译后端
pnpm build:admin	仅构建管理台静态资源
pnpm start:http	生产：HTTP API + 嵌入式 Admin（:3721）
pnpm test	运行全部测试（92）

详见 Web 管理台方案。

若 better-sqlite3 原生模块未编译，见 使用文档 §3.4。

MCP 配置（主流 AI IDE）

一行安装（推荐，无需 clone）

# 在业务项目根目录
curl -fsSL https://raw.githubusercontent.com/ChinaCarlos/coding-memory-mcp/main/scripts/remote-install.sh | bash -s -- --ide cursor
curl -fsSL https://raw.githubusercontent.com/ChinaCarlos/coding-memory-mcp/main/scripts/remote-install.sh | bash -s -- --ide claude
curl -fsSL https://raw.githubusercontent.com/ChinaCarlos/coding-memory-mcp/main/scripts/remote-install.sh | bash -s -- --ide codex
curl -fsSL https://raw.githubusercontent.com/ChinaCarlos/coding-memory-mcp/main/scripts/remote-install.sh | bash -s -- --ide qoder
curl -fsSL https://raw.githubusercontent.com/ChinaCarlos/coding-memory-mcp/main/scripts/remote-install.sh | bash -s -- --ide trae
curl -fsSL https://raw.githubusercontent.com/ChinaCarlos/coding-memory-mcp/main/scripts/remote-install.sh | bash -s -- --ide all

# 卸载
curl -fsSL https://raw.githubusercontent.com/ChinaCarlos/coding-memory-mcp/main/scripts/remote-uninstall.sh | bash -s -- --ide all

多 IDE 同时开：MCP 无端口冲突（stdio + 共用 SQLite）；Admin 仅 Leader 占用 :3721，其余自动 Follower。详见 使用文档 §3.3。

本地 scripts 安装

npm i -g coding-memory-mcp
CM="$(npm root -g)/coding-memory-mcp/scripts"

# Cursor / Claude Code / Codex / Qoder / Trae
bash "$CM/install.sh" --project . --ide cursor
bash "$CM/install.sh" --project . --ide claude
bash "$CM/install.sh" --project . --ide codex
bash "$CM/install.sh" --project . --ide all          # 一次装齐
bash "$CM/uninstall.sh" --project . --ide cursor     # 卸载对应 IDE
bash "$CM/uninstall.sh" --project . --ide all        # 全卸（默认保留 DB）

各 IDE 落点与选项见 使用文档 §3.6。

手动 MCP 片段

{
  "mcpServers": {
    "coding-memory": {
      "command": "npx",
      "args": ["-y", "coding-memory-mcp"],
      "env": {
        "CODING_MEMORY_DB": "/Users/你的用户名/.coding-memory/memory.db"
      }
    }
  }
}

IDE	一键脚本	配置落点	规则模板
Cursor	--ide cursor	~/.cursor/mcp.json（用户级，默认）；可选 --project-mcp	coding-memory-global.mdc（用户）+ coding-memory.mdc（项目）+ Hooks
Claude Code	--ide claude	~/.claude.json（默认）；可选 --project-mcp	templates/claude-instructions.md
Codex	--ide codex	~/.codex/config.toml（默认）；可选 --project-mcp	templates/codex-instructions.md
Qoder	--ide qoder	~/.qoder/mcp.json（默认）；可选 --project-mcp	templates/qoder-instructions.md
Trae	--ide trae	~/.trae/mcp.json（默认）；可选 --project-mcp	templates/trae-instructions.md
其他 MCP 客户端	手动粘贴 JSON	各自 MCP 设置	templates/agents.md

全局安装后可将 command 改为 coding-memory-mcp（去掉 npx args）。

多工具必须共用同一 CODING_MEMORY_DB。完整步骤：docs/09-user-guide.md §5。

源码开发时可用：

{
  "mcpServers": {
    "coding-memory": {
      "command": "pnpm",
      "args": ["--dir", "/绝对路径/coding-memory-mcp", "dev:mcp"],
      "env": {
        "CODING_MEMORY_DB": "/Users/你的用户名/.coding-memory/memory.db"
      }
    }
  }
}

已实现的 MCP Tools（1.0.8）

Tool	说明
memory_ping	健康检查
memory_remember	写入记忆
memory_search	FTS + 可选向量/图排序
memory_recall_context	召回并压缩上下文
memory_list	列出记忆
memory_forget	归档/删除/脱敏
memory_update	更新已有记忆
memory_link	创建实体关系边
memory_explain	解释为何命中
memory_reflect	从 transcript 提取候选（默认 preview）
memory_merge	合并多条记忆
memory_feedback	召回质量反馈
memory_promote	将 procedure 提升为 skill
skill_list / skill_read / skill_upsert	Skill 管理

MCP Resources

URI	说明
memory://core/user	用户 global 核心记忆摘要（markdown）
memory://skills	Skill 列表（JSON）
memory://repo/{repoId}/summary	项目记忆摘要
memory://repo/{repoId}/decisions	项目决策列表

所有 tool 返回统一 JSON：{ "ok": true, "data": ... } 或 { "ok": false, "error": ... }。

可选环境变量（完整版）

变量	默认值	说明
CODING_MEMORY_EMBEDDING_ENABLED	false	开启向量检索
CODING_MEMORY_EMBEDDING_PROVIDER	hash	hash 或 openai
CODING_MEMORY_EMBEDDING_MODEL	text-embedding-3-small	OpenAI 模型
CODING_MEMORY_REFLECTION_REMOTE	false	允许远程 LLM 反思
CODING_MEMORY_MAX_HOPS	2	图扩散跳数
CODING_MEMORY_DECAY	0.65	图扩散衰减系数
CODING_MEMORY_HTTP_HOST	127.0.0.1	HTTP API 绑定地址
CODING_MEMORY_HTTP_PORT	3721	HTTP API 端口