LLM Context MCP

项目内存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（建议日常使用）

npm install -g project-memory-mcp
project-memory-mcp setup

这将安装一次CLI，添加一个全局可用的 project-memory-mcp 命令，并将服务器存储在全局npm缓存中。

2.通过npx按需安装（无需全局安装）

npx project-memory-mcp setup

npx在第一次运行时下载包，然后重用缓存的副本。非常适合尝试该工具或连接一台机器。

3.本地克隆（开发/黑客攻击）

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。这也是您贡献和运行钩子测试的方式。看 本地开发 了解详情。

快速入门（任何安装路径）

1. 运行安装向导 在您要启用（或传递）的仓库内 --project /path):

   project-memory-mcp setup        # global install
   # or
   npx project-memory-mcp setup    # on-demand

1. 选择CLI生成服务器的方式(npx全局二进制， node dist/server.js，或自定义命令）。
2. 选择要配置的CLI（Claude Code、Gemini CLI、Codex CLI）。
3. 询问您的CLI：“呼叫 memory_status 并显示输出。“你应该看到正确的 projectRoot 和 .ai/memory.json.

更喜欢手动路线还是需要自动化标志？跳转到 本地开发 和 docs/LOCAL_SETUP.md.

将其作为项目依赖项运行

如果你想让每个队友都通过你的项目安装服务器 package.json，将其添加为开发依赖项：

npm install --save-dev project-memory-mcp

现在，您可以公开脚本：

{
  "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
2. npm run build
3. npm run test:hooks （吊钩流量可选烟雾测试）
4. 使用以下方式连接CLIs node dist/server.js 或 project-memory-mcp （通过链接后 npm link)

看 docs/LOCAL_SETUP.md 对于长格式指南，env覆盖、故障排除和钩子接线默认值。\ 需要从您的工作站发布新的npm版本吗？跟随 .

CLI设置和工具图

已经通过npx或源代码在全球范围内安装？从要启用的仓库运行向导：

# 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

这就是核心循环： 获取捆绑包→ 做工作→ 保存重要的东西.

______________________________________________________________________

快速设置（每个项目）

1. 安装软件包 （选一个）

   npm install -g project-memory-mcp   # global install
   # or use npx — no install needed

1. 运行指导设置（推荐）

   # 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 并添加：

     "mcpServers": {
       "project-memory": {
         "command": "npx",
         "args": ["project-memory-mcp"],
         "cwd": "/path/to/my-app"
       }
     }

重新启动克劳德内部 /path/to/my-app. - Gemini CLI

     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

     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，而不会出现提示：

   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.

______________________________________________________________________

日常工作流程

1. memory_get_bundle  →  load relevant context for your task
2. ... do your work ...
3. memory_save        →  store what changed / what you learned

任何型号（克劳德、Codex、双子座）都可以在另一个型号停止的地方继续。

Example: save context

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

Call `memory_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

阅读

写（直接）

写入（门控）

维护

所有写入工具都接受可选 projectRoot 多项目路由的输入。

工具调用备忘单

使用提示：

• 克劳德代码/Codex命令行界面：精确键入短语（例如“调用memory_status…”）。他们将运行该工具并内联返回输出。
• Gemini CLI：键入句子或运行 memory_compact {"maxItems":250} 直接在终端。 /mcp 显示了工具+描述的实时列表。

Data Model

memory.json 结构：

Memory Resolution Rules

projectRoot 按此优先级解决：

1. 工具输入 projectRoot （如有提供）
2. MEMORY_PROJECT_ROOT env 是
3. 最近的祖先与 .git
4. 当前工作目录

存储路径：

• 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=/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

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 如果你不想将内存提交到仓库。

______________________________________________________________________

故障排除

测试检查表

1. 为目标项目配置CLI MCP服务器
2. 重新启动CLI会话
3. memory_status 返回预期路径
4. memory_save 返回成功
5. memory_search 查找已保存的项目
6. 验证另一个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. 下次会议：仅处理自上次光标位置以来的新转录行

什么会被自动捕获

所有自动保存的项目都会获得以下标签：

• auto-hook -识别自动捕获的项目
• 特定类别标签： version, environment, dependency, commit, error-resolution, file-changes

示例：你会看到什么

会议期间：

$ 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 将包含：

{
  "items": [
    {
      "id": "mem_a1b2c3d4",
      "type": "fact",
      "title": "node version: v20.11.0",
      "content": "Detected via `node -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 via `npm 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:

{
  "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:

{
  "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:

# 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 使用您的实际安装路径。

可选的：传递显式历史文件路径：

[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 带有通知有效载荷
2. 通知钩子解析Codex的有效载荷格式并将其转发给 auto-save.js
3. 提取和保存过程与Claude/Gemini相同

______________________________________________________________________

重复数据消除策略

钩子使用多种策略防止重复项目：

1. 标题哈希跟踪：游标文件中存储的每个标题的SHA-256哈希
2. Jaccard相似性：比较新标题和现有标题之间的单词重叠（阈值：80%）
3. 跨会话已结束：哈希在会话之间持续存在，以防止重新捕获相同的事实
4. 光标位置：仅处理自上次运行以来的新转录行

光标跟踪

追踪到的州 .ai/.auto-save-cursor.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）：

npm run test:hooks

这将创建一个测试记录，并验证所有三个挂钩是否正常工作。

手动测试 （单钩）：

echo '{"session_id":"test","transcript_path":"/tmp/test.jsonl","cwd":"'$(pwd)'"}' | node dist/hooks/auto-save.js

验证已保存的项目:

# Check memory file
cat .ai/memory.json | jq '.items[] | select(.source == "auto-hook")'

# Check cursor
cat .ai/.auto-save-cursor.json

故障排除

调试模式：使用测试有效负载手动运行钩子以查看错误：

node dist/hooks/auto-save.js 

______________________________________________________________________