项目内存MCP服务器
共享的、项目范围的内存 克劳德代码, 法典,以及 Gemini CLI --因此,所有三个代理都记住了相同的上下文。```
You (any CLI) ──► MCP Server ──► .ai/memory.json (per project)
此存储库附带了一个Node.js MCP服务器,该服务器将项目事实/决策保存到 `/.ai/memory.json`任何受支持的CLI都可以读/写相同的文件,因此在Claude、Codex和Gemini之间切换感觉是有状态的:使用以下命令加载上下文 `memory_get_bundle`,执行工作,并保存更改的内容 `memory_save`.
## 为什么选择Project Memory MCP?
- **共享上下文** -一个 `.ai/memory.json` 每次回购使Claude、Codex和Gemini保持同步。
- **电池包括工具** –搜索、捆绑包生成、固定、提案、自动压缩。
- **无声捕捉** –可选挂钩在会话结束时自动保存版本、deps和commits。
- **CLI+程序化** –通过以下方式运行stdio服务器 `project-memory-mcp` 或者在Node项目中导入构建工件。
## 安装选项
选择适合您团队的工作流程:
### 1.全局CLI(建议日常使用)```bash
npm install -g project-memory-mcp
project-memory-mcp setup
这将安装一次CLI,添加一个全局可用的 project-memory-mcp 命令,并将服务器存储在全局npm缓存中。
2.通过npx按需安装(无需全局安装)```bash
npx project-memory-mcp setup
npx在第一次运行时下载包,然后重用缓存的副本。非常适合尝试该工具或连接一台机器。
### 3.本地克隆(开发/黑客攻击)```bash
git clone https://github.com/nicobailon/project-memory-mcp-js.git
cd project-memory-mcp-js
npm install
npm run build
然后将CLI指向 node /absolute/path/dist/server.js。这也是您贡献和运行钩子测试的方式。看 本地开发 了解详情。
快速入门(任何安装路径)
- 运行安装向导 在您要启用(或传递)的仓库内
--project /path):```bash
project-memory-mcp setup # global install
or
npx project-memory-mcp setup # on-demand
1. 选择CLI生成服务器的方式(`npx`全局二进制, `node dist/server.js`,或自定义命令)。
1. 选择要配置的CLI(Claude Code、Gemini CLI、Codex CLI)。
1. 询问您的CLI:“呼叫 `memory_status` 并显示输出。“你应该看到正确的 `projectRoot` 和 `.ai/memory.json`.
更喜欢手动路线还是需要自动化标志?跳转到 本地开发 和 `docs/LOCAL_SETUP.md`.
## 将其作为项目依赖项运行
如果你想让每个队友都通过你的项目安装服务器 `package.json`,将其添加为开发依赖项:```bash
npm install --save-dev project-memory-mcp
现在,您可以公开脚本:```jsonc
{
"scripts": {
"memory:serve": "project-memory-mcp serve",
"memory:setup": "project-memory-mcp setup --yes --runner node"
}
}
从那里,您的CLI条目可以指向 `npx project-memory-mcp` 或 `node ./node_modules/project-memory-mcp/dist/server.js`已发布的套餐将 `dist/` 树,因此在消费类机器上不需要构建步骤。
## 本地开发
退出这个回购计划?
1. `npm install`
1. `npm run build`
1. `npm run test:hooks` (吊钩流量可选烟雾测试)
1. 使用以下方式连接CLIs `node dist/server.js` 或 `project-memory-mcp` (通过链接后 `npm link`)
看 `docs/LOCAL_SETUP.md` 对于长格式指南,env覆盖、故障排除和钩子接线默认值。\
需要从您的工作站发布新的npm版本吗?跟随 `docs/LOCAL_NPM_DEPLOY.md`.
## CLI设置和工具图
已经通过npx或源代码在全球范围内安装?从要启用的仓库运行向导:```bash
# Install globally (recommended)
npm install -g project-memory-mcp
# Or use npx (no install needed)
npx project-memory-mcp
# Or clone and run locally
git clone https://github.com/nicobailon/project-memory-mcp-js.git
cd project-memory-mcp-js && npm install && npm run build && npm start
| 你想要什么 | 工具调用 |
|---|---|
| 检查设置是否正确 | memory_status |
| 在任务之前加载上下文 | memory_get_bundle |
| 保存一些东西到内存中 | memory_save |
| 搜索过去的记忆 | memory_search |
这就是核心循环: 获取捆绑包→ 做工作→ 保存重要的东西.
快速设置(每个项目)
- 安装软件包 (选一个)```bash
npm install -g project-memory-mcp # global install
or use npx — no install needed
1. **运行指导设置(推荐)**```bash
# from the repo you want to wire up (or pass --project)
npx project-memory-mcp setup
# or, after a global install:
project-memory-mcp setup
- 提示a 服务器ID (例如。,
project-memory-npx).ID必须匹配[a-z0-9-]{3,32};提供--server-id编写脚本或使用运行时--yes. - 提示输入项目目录(默认为当前工作文件夹)。
- 允许您选择如何启动MCP服务器(
npx全局二进制,node /path/to/dist/server.js,或自定义命令)。 - 允许您选择要配置的CLI(Claude Code、Gemini CLI、Codex CLI)。
- 自动更新
~/.claude.json(与a.bak备份)并运行必要的gemini mcp/codex mcp命令,以便它们指向正确的项目。 - 旗帜:
--project /path,--server-id my-server-name,--cli claude,gemini,--runner global(别名:--runner-profile),--yes,--command,以及--args让您编写脚本或跳过提示。跑project-memory-mcp setup --help查看完整列表。 - 要求已安装相应的CLI,并在您的
PATH.
> Claude在沙盒中的设置:set PROJECT_MEMORY_MCP_CLAUDE_CONFIG_PATH=/custom/path/claude.json (或 CLAUDE_CONFIG_PATH)在运行向导之前,如果 ~/.claude.json 不可写。向导读取/写入该自定义文件,但仍会生成 .bak 旁边。
Prefer the fully manual wiring? Expand for the original commands.
- 克劳德代码 –编辑
~/.claude.json并添加:```json
"mcpServers": {
"project-memory": {
"command": "npx",
"args": ["project-memory-mcp"],
"cwd": "/path/to/my-app"
}
}
重新启动克劳德内部 `/path/to/my-app`.
- **Gemini CLI**```bash
cd /path/to/my-app
gemini mcp add project-memory npx project-memory-mcp --trust
gemini mcp list # should show CONNECTED
/mcp # (in-session) inspect tools/resources
编辑 .gemini/settings.json 如果你需要定制 cwd 或env变量。
- Codex CLI```bash
cd /path/to/my-app
codex mcp add project-memory npx project-memory-mcp
codex mcp list
始终启动 `codex` 从 `/path/to/my-app` 因此服务器检测到正确的根。
1. **验证路由**
- 在该项目中,要求您的CLI `Call memory_status and show the output.` 你应该看看 `projectRoot` = `/path/to/my-app` 和 `memoryFilePath` = `/path/to/my-app/.ai/memory.json`如果没有,请修复MCP配置(`cwd`、env变量等),然后继续。
- 需要命令提醒吗?跑 `memory_help` 随时查看备忘单。
向导会记住你最后的选择 `/.ai/memory-mcp.json`,因此未来的运行可以预先填充相同的服务器ID和运行器。如果你想从头开始,请删除该文件。
一旦你跑了 `setup` 一次,您可以将保存的配置重新应用于任何CLI,而不会出现提示:```bash
project-memory-mcp switch # all CLIs
project-memory-mcp switch --cli claude # Claude only
project-memory-mcp switch --project ~/code/api
> 更喜欢长篇指南(环境覆盖、故障排除、自动挂钩)?看 docs/LOCAL_SETUP.md.
日常工作流程```
- memory_get_bundle → load relevant context for your task
- ... do your work ...
- memory_save → store what changed / what you learned
任何型号(克劳德、Codex、双子座)都可以在另一个型号停止的地方继续。
Example: save context```text
Call MCP tool `memory_save` with:
- title: "Project runtime versions"
- type: "fact"
- content: "PHP 7.4.33, Laravel 5.6.40"
- tags: ["php","laravel","environment"]
- source: "claude"
Example: load context``text
Callmemory_get_bundle` with prompt "I am fixing login API bugs" and maxItems 12.
### 自动压缩和归档
- 当超过时,服务器会自动压缩 **400** 活动项存在(请参见 `CONFIG.autoCompact`).最旧的条目被移动到 `.ai/memory-archive.json`,并添加了一个摘要注释,以便您仍然知道存档了什么。
- 要手动触发压缩(或调整每个项目的阈值),请调用 `memory_compact` 并提供覆盖,例如 `{ "maxItems": 250 }`.
- 存档的内容可供将来手动审查--`memory_get_bundle` 只显示最相关的活动笔记,而摘要则保持历史线索的可发现性。
- 想要零点击上下文吗?配置可选 `dist/hooks/auto-memory.js` 脚本(`... start` 上 `UserPromptSubmit`, `... stop` 上 `Stop`)自动注入捆绑包和自动保存成绩单。
______________________________________________________________________
## 参考
All Tools
### 阅读
|工具|目的|
|---|---|
| `memory_help` |快速入门使用技巧+示例提示|
| `memory_status` |显示已解析的项目根、内存文件路径、计数、修订|
| `memory_search` |对已保存的项目进行关键字/标签搜索|
| `memory_get_bundle` |当前任务的紧凑型分级内存包|
| `memory_list_proposals` |按状态列出提案|
### 写(直接)
|工具|目的|
|---|---|
| `memory_save` |立即保存存储项(无需审批步骤)|
| `memory_pin` |固定或取消固定现有项目|
### 写入(门控)
|工具|目的|
|---|---|
| `memory_propose` |创建提案(待批准)|
| `memory_approve_proposal` |批准/拒绝提案,可选编辑|
### 维护
|工具|目的|
|---|---|
| `memory_compact` |将旧项目归档到 `.ai/memory-archive.json` 并添加总结注释,保持活跃店铺的精简|
所有写入工具都接受可选 `projectRoot` 多项目路由的输入。
### 工具调用备忘单
|工具|最小CLI提示|注意事项|
|---|---|---|
| `memory_status` | `Call memory_status and show the output.` |确认 `projectRoot` + `.ai/memory.json` 在你开始之前。 |
| `memory_help` | `Call memory_help.` |返回此备忘单+最佳实践提示。 |
| `memory_get_bundle` | `Call memory_get_bundle with {"prompt":"Fixing login bugs"}` |调整 `maxItems`, `types`,或 `projectRoot` 每项任务。 |
| `memory_save` | `Call memory_save with {"title":"New API",...}` |提供 `content`;可选 `tags`, `pinned`, `source`. |
| `memory_search` | `Call memory_search with {"query":"redis"}` |添加 `includeContent`, `tags`,或 `types` 过滤器。 |
| `memory_propose` | `Call memory_propose with {"items":[...],"reason":"code review"}` |保存前需要审批步骤时使用。 |
| `memory_approve_proposal` | `Call memory_approve_proposal with {"proposalId":"prop_...","action":"approve"}` |包括 `edits` 在批准之前调整提案内容。 |
| `memory_pin` | `Call memory_pin with {"itemId":"mem_...","pinned":true}` |固定使关键笔记以捆的形式出现。 |
| `memory_compact` | `Call memory_compact with {"maxItems":250}` |保持活跃店铺的精简;省略payload以使用默认值。 |
使用提示:
- **克劳德代码/Codex命令行界面**:精确键入短语(例如“调用memory_status…”)。他们将运行该工具并内联返回输出。
- **Gemini CLI**:键入句子或运行 `memory_compact {"maxItems":250}` 直接在终端。 `/mcp` 显示了工具+描述的实时列表。
Data Model
`memory.json` 结构:
|字段|描述|
|---|---|
| `version` |格式版本(当前 `1`) |
| `project` |元数据: `id`, `root`,时间戳|
| `items` |已批准/已保存的内存条目|
| `proposals` |门控工作流条目(`pending`, `approved`, `rejected`) |
| `revision` |每次写入时递增|
Memory Resolution Rules
`projectRoot` 按此优先级解决:
1. 工具输入 `projectRoot` (如有提供)
1. `MEMORY_PROJECT_ROOT` env 是
1. 最近的祖先与 `.git`
1. 当前工作目录
存储路径:
- `MEMORY_FILE_PATH` env-var if set(相对路径从项目根解析)
- 否则 `/.ai/memory.json`
Update and Delete
没有 `memory_update` 或 `memory_delete` 工具还。
**要更新,请执行以下操作:** 使用以下命令保存已更正的项目 `memory_save`.添加一个标签,如 `supersedes:` 并且可选 `memory_pin` 新的。
**要全部删除:** `rm -f /.ai/memory.json`
**要删除一个项目,请执行以下操作:** 手动编辑 `items` JSON文件中的数组。
Environment Variables
|变量|目的|
|---|---|
| `MEMORY_PROJECT_ROOT` |强制特定项目根|
| `MEMORY_FILE_PATH` |重写内存文件路径(从项目根进行相对解析)|
| `PROJECT_MEMORY_MCP_CLAUDE_CONFIG_PATH` |覆盖安装向导读取/写入Claude配置的位置(默认为 `~/.claude.json`) |
| `CLAUDE_CONFIG_PATH` |与上述相同,保持兼容性;仅在项目特定变量未设置时使用|
```bash
MEMORY_PROJECT_ROOT=/path/to/project npm run start
# Point setup at a sandbox-friendly Claude config file
PROJECT_MEMORY_MCP_CLAUDE_CONFIG_PATH=.tmp/claude-test.json \
npx project-memory-mcp setup --claude
File Layout```text
server.ts # entrypoint (source)
dist/server.js # entrypoint (runtime)
src/main.ts # MCP bootstrap and transport connection
src/tools.ts # tool registration and handlers
src/storage.ts # lock, load/write, atomic persistence
src/runtime.ts # project root/path resolution
src/domain.ts # scoring/tokenization/validation helpers
src/config.ts # constants
src/logger.ts # stderr logger
.ai/memory.json # persisted project memory (per project)
添加 `.ai/` 到 `.gitignore` 如果你不想将内存提交到仓库。
______________________________________________________________________
## 故障排除
|问题|修复|
|---|---|
| `memory.json` 未创建|调用 `memory_status` --项目根可能是错误的。修复 `cwd` (Claude)或从正确的文件夹运行CLI。 |
|服务器在CLI中不可用|请检查CLI MCP配置。确认 `node -v` 工作文件和服务器文件存在。 |
|数据未保存|您必须调用写入工具(`memory_save` 或批准提案)。单独聊天不会持续下去。 |
### 测试检查表
1. 为目标项目配置CLI MCP服务器
1. 重新启动CLI会话
1. `memory_status` 返回预期路径
1. `memory_save` 返回成功
1. `memory_search` 查找已保存的项目
1. 验证另一个CLI(Claude/Gemini/Codex)是否可以看到相同的项目
______________________________________________________________________
Auto-Save Hook (Claude Code + Gemini CLI + Codex CLI)
这 `hooks/` 目录包含钩子 **自动捕获** 会话中的内存项--无需手动 `memory_save` 需要常规事实。
### 运作原理
自动保存挂钩运行 **默默地在后台** 每次会议后:
1. **触发**:CLI会话结束时:
- 克劳德代码:on `Stop` 事件(Ctrl+C或会话结束)
- Gemini CLI:打开 `SessionEnd` 事件
- Codex CLI:通知事件(配置时)
1. **处理**:
- `dist/hooks/auto-save.js` 读取会话记录(JSONL或JSON格式)
- 启发式提取器分析工具调用和结果
- 提取结构化事实,如版本、依赖关系、提交、错误修复
1. **储蓄**:
- 使用标题哈希和相似性检查对现有内存进行重复数据消除
- 将新项目保存到 `.ai/memory.json` 随着 `source: "auto-hook"` 和 `tags: ["auto-hook"]`
- 在以下位置更新光标 `.ai/.auto-save-cursor.json` 跟踪进度
1. **下次会议**:仅处理自上次光标位置以来的新转录行
### 什么会被自动捕获
类别 · 命令示例 · 提取项目 · 类型
**版本检查** · `node -v` · “节点版本:v20.11.0” · 事实
`python --version` · “python版本:3.11.5” · 事实
`npm -v`, `pip -v`, `go version` · 版本事实
**依赖项** · `npm install express` · “添加依赖项:express” · 事实
`pip install requests` · “添加了依赖关系:请求” · 事实
`cargo add tokio` · “添加了依赖项:tokio” · 事实
**Git提交** · `git commit -m "fix auth bug"` · “提交:修复身份验证错误” · 注意
**错误修复** · 命令失败→ 重试命令成功 · “已解决:\[错误摘要\]” · 事实
**文件变更** · 写入/编辑工具调用 · “本次会话修改的文件(5)” · 注意
所有自动保存的项目都会获得以下标签:
- `auto-hook` -识别自动捕获的项目
- 特定类别标签: `version`, `environment`, `dependency`, `commit`, `error-resolution`, `file-changes`
### 示例:你会看到什么
**会议期间:**```bash
$ node -v
v20.11.0
$ npm install express
added 57 packages
$ git commit -m "Add express server"
[main abc1234] Add express server
会话结束后 (自动、静音):
你的 .ai/memory.json 将包含:``json
{
"items": [
{
"id": "mem_a1b2c3d4",
"type": "fact",
"title": "node version: v20.11.0",
"content": "Detected vianode -v",
"tags": ["version", "environment", "auto-hook"],
"source": "auto-hook",
"createdAt": "2026-02-12T13:39:17.364Z"
},
{
"id": "mem_e5f6g7h8",
"type": "fact",
"title": "Added dependency: express",
"content": "Installed vianpm install express`",
"tags": ["dependency", "auto-hook"],
"source": "auto-hook",
"createdAt": "2026-02-12T13:39:18.123Z"
},
{
"id": "mem_i9j0k1l2",
"type": "note",
"title": "Commit: Add express server",
"content": "Full command: git commit -m \"Add express server\"",
"tags": ["commit", "auto-hook"],
"source": "auto-hook",
"createdAt": "2026-02-12T13:39:19.456Z"
}
]
}
### 按CLI设置
#### 克劳德代码(已配置)
此回购包括 `.claude/settings.json`:```json
{
"hooks": {
"Stop": [{
"hooks": [{
"type": "command",
"command": "node \"$CLAUDE_PROJECT_DIR/dist/hooks/auto-save.js\"",
"async": true,
"timeout": 15
}]
}]
}
}
状态: ✅ 在此项目中自动工作
禁用:删除或重命名 .claude/settings.json
环境:吊钩接收 CLAUDE_PROJECT_DIR 指向项目根的env-var
Gemini CLI(已配置)
此回购包括 .gemini/settings.json:```json
{
"hooks": {
"SessionEnd": [{
"matcher": "*",
"hooks": [{
"name": "auto-save",
"type": "command",
"command": "node \"$GEMINI_PROJECT_DIR/dist/hooks/auto-save.js\""
}]
}]
}
}
**状态**: ✅ 在此项目中自动工作
**禁用**:删除或重命名 `.gemini/settings.json`
**环境**:吊钩接收 `GEMINI_PROJECT_DIR` 指向项目根的env-var
**重要**:Gemini钩子必须向stdout输出有效的JSON。钩子回来了 `{}` 为了兼容性。
______________________________________________________________________
#### Codex CLI(需要手动设置)
**需要安装**:在以下位置编辑您的全局Codex配置 `~/.codex/config.toml`:```toml
# Enable history persistence (required for hooks to access transcript)
[history]
persistence = "save-all" # or just true
# Add the notify hook (adjust path to your installation)
[notify]
command = ["node", "/absolute/path/to/project-memory-mcp-js/dist/hooks/codex-notify.js"]
替换 /absolute/path/to/project-memory-mcp-js 使用您的实际安装路径。
可选的:传递显式历史文件路径:```toml
[notify]
command = ["node", "/path/to/dist/hooks/codex-notify.js", "--history", "/path/to/history.jsonl"]
**禁用**:删除 `[notify]` 部分从 `config.toml`
**环境**:吊钩接收 `CODEX_PROJECT_DIR` 指向项目根的env-var
**运作原理**:
1. 食品法典委员会电话 `codex-notify.js` 带有通知有效载荷
1. 通知钩子解析Codex的有效载荷格式并将其转发给 `auto-save.js`
1. 提取和保存过程与Claude/Gemini相同
______________________________________________________________________
### 重复数据消除策略
钩子使用多种策略防止重复项目:
1. **标题哈希跟踪**:游标文件中存储的每个标题的SHA-256哈希
1. **Jaccard相似性**:比较新标题和现有标题之间的单词重叠(阈值:80%)
1. **跨会话已结束**:哈希在会话之间持续存在,以防止重新捕获相同的事实
1. **光标位置**:仅处理自上次运行以来的新转录行
### 光标跟踪
追踪到的州 `.ai/.auto-save-cursor.json`:```json
{
"sessionId": "current-session-id",
"lastLineIndex": 42,
"itemHashes": ["hash1", "hash2", "..."],
"updatedAt": "2026-02-12T13:39:17.658Z"
}
sessionId-当前会话ID(会话更改时重置光标位置)lastLineIndex-最后处理的转录行(0索引)itemHashes-最近的标题哈希值(保留最后200个用于数据删除)updatedAt-上次更新时间戳
会话更改行为:何时 sessionId 变化, lastLineIndex 重置为-1,但 itemHashes 保留用于跨会话重复数据删除。
最小阈值
为了减少噪音,钩子只处理带有 至少2条助理消息 在自上次光标位置以来的新行中。
跳过单圈交换。
测试钩子
自动化测试 (所有三个CLIs):```bash
npm run test:hooks
这将创建一个测试记录,并验证所有三个挂钩是否正常工作。
**手动测试** (单钩):```bash
echo '{"session_id":"test","transcript_path":"/tmp/test.jsonl","cwd":"'$(pwd)'"}' | node dist/hooks/auto-save.js
验证已保存的项目:```bash
Check memory file
cat .ai/memory.json | jq '.items[] | select(.source == "auto-hook")'
Check cursor
cat .ai/.auto-save-cursor.json
### 故障排除
|问题|解决方案|
|---|---|
|钩子未运行|检查CLI设置文件是否存在(`.claude/settings.json`, `.gemini/settings.json`)或Codex `config.toml` |
|未保存任何项目|检查成绩单至少有2条助理消息。试着跑步 `node -v` 并结束会议。 |
|未出现的项目|验证 `.ai/memory.json` 存在并检查挂钩stderr中的错误|
|出现重复项|检查光标文件 `.ai/.auto-save-cursor.json` 正在更新|
|Codex挂钩不工作|确保 `history.persistence` 已启用且历史文件存在|
**调试模式**:使用测试有效负载手动运行钩子以查看错误:```bash
node dist/hooks/auto-save.js < test-payload.json
