内容
# 内存 MCP
一个为 AI 编程代理提供持久、不断演化的代码库知识的模型上下文协议（MCP）服务器。代理不再需要从零开始，而是可以存储和检索有关架构、约定、陷阱和最近工作上下文的观察结果。
## 工具
| 工具 | 描述 |
|------|-------------|
| `memory_context` | 会话启动和任务前查找。调用时不带参数，用于用户 + 首选项 + 过时提示；调用时带 `context`，用于任务特定知识 |
| `memory_query` | 结构化搜索，支持简短/标准/完整详细程度和 AND/OR/NOT 过滤语法。作用域默认为 `"*"`（所有主题） |
| `memory_store` | 存储知识条目，检测重复，展现首选项，自动检测脑叶，并为可能短暂的内容设置审查门槛 |
| `memory_correct` | 修正、更新或删除现有条目（建议存储为首选项） |
| `memory_bootstrap` | 首次使用扫描，从存储库结构、README 和构建文件初始化知识 |
> **隐藏工具**（仍然可调用，不在目录中 — 代理通过提示/错误学习它们）：`memory_list_lobes`（脑叶路径和统计信息）、`memory_stats`（条目计数、新鲜度、存储）、`memory_diagnose`（服务器健康状况、崩溃历史、恢复步骤）
## 知识主题
| 主题 | 目的 | 全局？ | 过期？ | 默认信任 |
|-------|---------|---------|----------|---------------|
| `user` | 个人信息（姓名、角色、沟通风格） | 是 | 永不 | `user` |
| `preferences` | 修正、意见、编码规则 | 是 | 永不 | `user` |
| `gotchas` | 陷阱和已知问题 | 否 | 永不 | `user` |
| `architecture` | 系统设计、模式、模块结构 | 否 | 30 天 | `agent-inferred` |
| `conventions` | 代码风格、命名、模式 | 否 | 30 天 | `agent-inferred` |
| `modules/<name>` | 每个模块的知识 | 否 | 30 天 | `agent-inferred` |
| `recent-work` | 当前任务上下文（分支范围） | 否 | 30 天 | `agent-inferred` |
**全局主题**（`user`、`preferences`）存储在 `~/.memory-mcp/global/` 的共享全局存储中，可从所有脑叶访问。这意味着您的身份和编码偏好在不同存储库中无需重复。
### 智能展现
- **重复检测**：存储条目时，响应显示同一主题中类似的现有条目（>35% 关键词重叠），并提供合并说明
- **偏好展现**：存储非偏好条目时，显示可能冲突的相关偏好
- **短暂审查门槛**：默认情况下，可能短暂的内容在持久化前被阻止。仅当您故意要保留时，才重新运行 `memory_store(..., durabilityDecision: "store-anyway")`
- **搭载提示**：`memory_correct` 建议将修正存储为可重用的偏好
- **`memory_context`**：用自然语言描述任务，并在所有主题中获取具有主题增强的排名结果（偏好 1.8 倍，陷阱 1.5 倍）
### 智能过滤语法
`memory_query` 支持用于精确搜索的过滤微语言：
| 语法 | 含义 | 示例 |
|--------|---------|---------|
| `A B` | AND（两者都需要） | `reducer sealed` |
| `A\|B` | OR（任一匹配） | `MVI\|MVVM` |
| `-A` | NOT（排除） | `-deprecated` |
| 组合 | 自由混合 | `kotlin sealed\|swift protocol -deprecated` |
过滤器使用词干匹配，因此 `reducers` 匹配 `reducer`，`exceptions` 匹配 `exception`。
## 快速入门
```bash
# 安装依赖
npm install
# 构建
npm run build
# 运行测试
npm test
```
## 配置
### 配置文件（推荐）
在内存 MCP 服务器旁边创建 `memory-config.json` 文件：
```json
{
"lobes": {
"workspace-mcp": {
"root": "$HOME/git/personal/workspace-mcp",
"budgetMB": 2
},
"workrail": {
"root": "$HOME/git/personal/workrail",
"budgetMB": 2
}
}
}
```
> **注意：** `memoryDir` 是可选的。如果省略，存储会自动检测到 `.git/memory/` 以获取 git 存储库。
**什么是“脑叶”？** 每个存储库都有自己的内存脑叶 — 一个专用的知识范围。可以将其视为大脑区域：“workrail 脑叶”存储有关 workrail 的知识，“workspace-mcp 脑叶”存储有关 workspace-mcp 的知识。
**好处：**
- 便携（ `$HOME` 和 `~` 扩展在不同机器上有效）
- 可发现（使用 `memory_list_lobes` 查看已配置的内容）
- 易于扩展（只需添加新的脑叶条目）
### 环境变量（备用）
如果未找到 `memory-config.json`，服务器将退回到环境变量：
| 变量 | 默认值 | 描述 |
|----------|---------|-------------|
| `MEMORY_MCP_WORKSPACES` | -- | JSON 映射工作区名称到存储库路径（多存储库模式） |
| `MEMORY_MCP_REPO_ROOT` | `process.cwd()` | 备用：单个存储库路径（如果未设置 `WORKSPACES`） |
| `MEMORY_MCP_DIR` | *(自动检测)* | 重写存储目录（相对于存储库根目录或绝对路径）。禁用 git 原生自动检测。 |
| `MEMORY_MCP_BUDGET` | `2097152`（2MB） | 每个工作区的存储预算（以字节为单位） |
### 添加新脑叶
1. **编辑 `memory-config.json`** （如果不存在，则创建）
2. **添加脑叶条目：**
```json
{
"my-project": {
"root": "$HOME/git/my-project",
"budgetMB": 2
}
}
```
3. **重启内存 MCP 服务器**
4. **验证：** 使用 `memory_list_lobes` 确认已加载
代理将在工具描述中看到新脑叶，并可以立即使用 `memory_store(lobe: "my-project", ...)` 使用它。
## MCP 客户端注册
使用 `memory-config.json`（推荐）：
```json
{
"mcpServers": {
"memory": {
"command": "node",
"args": ["/path/to/memory-mcp/dist/index.js"]
}
}
}
```
服务器会自动读取 `memory-config.json` — 无需环境变量。
### 环境变量模式
```json
{
"mcpServers": {
"memory": {
"command": "node",
"args": ["/path/to/memory-mcp/dist/index.js"],
"env": {
"MEMORY_MCP_WORKSPACES": "{\"android\":\"/path/to/android\",\"ios\":\"/path/to/ios\"}"
}
}
}
}
```
## 存储位置
知识存储为人类可读的 Markdown 文件 — **每个条目一个文件**。存储位置通过以下优先级自动检测：
1. **显式 `memoryDir` 配置** — 如果在 `memory-config.json` 或 `MEMORY_MCP_DIR` 中设置，则使用该路径
2. **Git 原生**（默认）— `<git-common-dir>/memory/` 使用 `git rev-parse --git-common-dir`。这确保：
- **对 git 隐藏** — `.git/` 内容从未被跟踪，无需 `.gitignore`
- **跨工作树共享** — 相同存储库的所有工作树共享一个内存存储
- **工作树/子模块安全** — 解析为公共 `.git/` 目录，无论如何
3. **中心备用** — `~/.memory-mcp/<lobe-name>/` 用于非 git 目录
使用 `memory_stats` 或 `memory_list_lobes` 查看每个脑叶的存储位置。
### 文件结构
每个条目都有自己的文件。最近的工作条目按分支范围划分。
```
.git/memory/
architecture/
arch-e8d4f012.md # 每个文件一个条目
conventions/
conv-a1b2c3d4.md
gotchas/
gotcha-7k3m9p2q.md
recent-work/
main/ # 分支范围
recent-f5e6d7c8.md
feature-messaging-refactor/ # 消毒分支名称
recent-9i0j1k2l.md
modules/
messaging/
mod-4d5e6f7g.md
~/.memory-mcp/global/ # 全局存储（跨所有脑叶共享）
user/
user-3f7a2b1c.md # 个人信息
preferences/
pref-5c9b7e3d.md # 编码意见和修正
```
### 并发安全性
每个条目都是一个带有随机十六进制 ID 的文件。两个 MCP 进程（例如，Firebender + Cursor）写入不同条目到同一个存储库 **永远不会冲突** — 它们写入不同的文件。存储在每次读取前都会从磁盘重新加载，以获取其他进程的更改。
### 分支范围近期工作
近期工作条目会自动标记为当前 git 分支，并存储在按分支命名的子目录中。`memory_query` 默认情况下会过滤近期工作到当前分支。使用 `branch: "*"` 可以查看所有分支的近期工作。
### 条目格式
```markdown
# 构建系统和语言
- **id**: arch-3f7a2b1c
- **topic**: architecture
- **confidence**: 0.70
- **trust**: agent-inferred
- **created**: 2026-02-18T12:00:00.000Z
- **lastAccessed**: 2026-02-18T12:00:00.000Z
检测到：Node.js/TypeScript 项目（npm）
```
## 信任级别
| 级别 | 置信度 | 含义 |
|-------|-----------|---------|
| `user` | 1.0 | 人类提供或人类修正的知识 |
| `agent-confirmed` | 0.85 | 代理观察并验证代码 |
| `agent-inferred` | 0.70 | 代理观察，尚未验证 |
## 恢复能力
服务器使用 **降级梯度** 在出现问题时保持有用：
- **运行中** — 所有脑叶健康，功能齐全
- **降级** — 一些脑叶初始化失败，但健康的脑叶继续工作。失败的脑叶通过 `memory_diagnose` 报告特定的恢复步骤。
- **安全模式** — 所有脑叶都失败了。只有 `memory_diagnose` 和 `memory_list_lobes` 工作，提供足够的信息来解决问题。
**崩溃日志**：在未捕获的异常时，服务器会将结构化的崩溃报告写入 `~/.memory-mcp/crashes/`，然后退出。 下次启动时，崩溃会在 `memory_context()`（简介模式）中显示，并带有恢复步骤。 使用 `memory_diagnose(showCrashHistory: true)` 查看完整的历史记录。
### 参数标准化
代理经常猜测错误的参数名称。 服务器静默地解析常见的别名，以避免浪费往返：
| 别名 | 解析为 |
|-------|-------------|
| `key`, `name` | `title` |
| `value`, `body`, `text` | `content` |
| `query`, `search` | `filter` |
| `workspace`, `repo` | `lobe` |
通配符作用域别名（`all`, `everything`, `global`, `project`）解析为 `*`。
## 架构
```
types.ts 领域类型（辨别联合、解析函数）
store.ts MarkdownMemoryStore（CRUD、搜索、引导、简介）
text-analyzer.ts 关键词提取、词干提取、相似性（无状态）
normalize.ts 参数别名解析（纯）
formatters.ts 工具处理程序的响应格式化器（纯）
config.ts 3 层配置加载（文件 > 环境变量 > 默认）
git-service.ts Git 操作边界（可注入测试）
crash-journal.ts 崩溃报告生命周期（构建、写入、读取、格式化）
index.ts MCP 服务器、工具处理程序、启动、迁移
```
## 设计
参见 `ideas/codebase-memory-mcp-design-thinking.md` 获取完整设计思考文档，包含 67 个想法、5 个概念包、预先死亡分析以及测试计划。
