# Coding Memory MCP

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

一句话目标：

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

**当前版本：1.0.9**（完整功能版 + 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、审计、图谱 | ✅ |

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

## 文档导航

### 用户与架构（推荐阅读）

- [使用文档](./docs/09-user-guide.md) — **npm 安装、主流 AI IDE 接入**、MCP Tools、Scope、FAQ
- [技术架构文档](./docs/10-technical-architecture.md) — 分层架构、数据流、存储、检索、安全
- [功能模块文档](./docs/11-feature-modules.md) — 各模块职责、流程、代码路径
- [Web 管理台与 LLM 接入方案](./docs/12-web-admin-and-llm-providers.md) — HTTP API、管理台模块、分阶段计划
- [会话收集与多 IDE 自动化](./docs/13-session-collection-and-multi-ide-automation.md) — 收集原理、Hook、多 IDE
- [上下文压缩](./docs/14-context-compression.md) — recall 档 A/B/C + tiktoken
- [HTTP API OpenAPI 附录](./docs/15-http-api-openapi.md)

### 设计与规范

- [需求方案](./docs/01-product-requirements.md)
- [技术方案](./docs/02-technical-design.md)（归档；以 10/11 为准）
- [MCP 接口设计](./docs/03-mcp-api-spec.md)
- [数据模型与数据库设计](./docs/04-data-model.md)
- [激活扩散检索算法](./docs/05-spreading-activation.md)
- [Agent 工作流与跨工具集成](./docs/06-agent-workflows.md)
- [实现路线图](./docs/07-implementation-roadmap.md)
- [测试、评估与安全](./docs/08-testing-evaluation-security.md)

## 推荐实现顺序

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/agents.md)
- [templates/cursor-user-rules.md](./templates/cursor-user-rules.md)（全局）+ [templates/cursor-rules.md](./templates/cursor-rules.md)（项目）+ [hooks/reflect-on-stop.sh](./templates/hooks/reflect-on-stop.sh)
- [templates/codex-instructions.md](./templates/codex-instructions.md)
- [templates/claude-instructions.md](./templates/claude-instructions.md)
- [templates/qoder-instructions.md](./templates/qoder-instructions.md)
- [templates/trae-instructions.md](./templates/trae-instructions.md)

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

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

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

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

```bash
# 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 / 包：

```bash
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](./docs/09-user-guide.md) · [§5](./docs/09-user-guide.md#5-在主流-ai-ide--agent-中使用)。

### 从源码开发（可选）

```bash
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 管理台方案](./docs/12-web-admin-and-llm-providers.md)。

若 `better-sqlite3` 原生模块未编译，见 [使用文档 §3.4](./docs/09-user-guide.md)。

## MCP 配置（主流 AI IDE）

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

```bash
# 在业务项目根目录
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](./docs/09-user-guide.md)。

### 本地 scripts 安装

```bash
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](./docs/09-user-guide.md)。

### 手动 MCP 片段

```json
{
  "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` + **auto-recall（用户 hooks）/ stop（项目）** |
| **Claude Code** | `--ide claude` | **`~/.claude.json`（默认）**；可选 `--project-mcp` | `templates/claude-instructions.md` + **settings.json auto-recall** |
| **Codex** | `--ide codex` | **`~/.codex/config.toml`（默认）**；可选 `--project-mcp` | `templates/codex-instructions.md` + **hooks.json auto-recall** |
| **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](./docs/09-user-guide.md#5-在主流-ai-ide--agent-中使用)。

源码开发时可用：

```json
{
  "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.9）

| Tool | 说明 |
|------|------|
| `memory_ping` | 健康检查 |
| `memory_current_repo` | 检测当前仓库身份（path / git / `.coding-memory/config.json`） |
| `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 端口 |