Project Memory MCP

Project Memory MCP 是一个与模型无关的 MCP Server，用来实现 Project Memory Protocol (PMP) 的第一版能力。

这个项目的核心思路不是让每个 AI 工具各自维护一套 Memory，而是把项目共享记忆统一存放在项目目录下的 .ai/ 中，保证它可读、可追踪、可复用。

项目定位

• PMP 是协议，也是目录约定。

• Project Memory MCP 是 PMP 的一种实现。

• 任何支持 MCP 的客户端，都可以读取和更新同一份项目记忆。

Related MCP server: Mono Memory MCP

MVP 能力

当前 MVP 提供 13 个核心工具：

• run_project_open_workflow

• run_conversation_end_workflow

• suggest_memory_optimization

• apply_memory_optimization

• bootstrap_project_context

• get_project_context

• get_current_task

• update_current_task

• add_decision

• record_conversation_summary

• suggest_context_updates

• summarize_git_diff

• optimize_ai_memory

目录结构

.ai/
  project.md
  architecture.md
  current-task.md
  todo.md
  decisions.md
  coding-style.md
  recent-changes.md
  recent-changes.archive.md
  conversation-summary.md

本地开发

pnpm install
pnpm build
pnpm dev

pnpm dev 会直接通过 tsx 启动 src/index.ts，适合本地联调和观察启动日志。

终端命令 与 MCP Tools 的区别

这个项目里有两类“能力入口”，使用方式不同：

1. 终端命令

这些命令在 shell / Terminal 中执行：

pnpm install
pnpm build
pnpm dev
node dist/index.js

它们的作用主要是：

• 安装依赖

• 编译项目

• 本地调试 MCP Server

• 手动观察启动日志和报错

2. MCP Tools

这些不是终端命令，而是 MCP 客户端连接到 project-memory 之后，由 AI 或客户端发起的 tool call。

例如：

• bootstrap_project_context

• get_project_context

• record_conversation_summary

• summarize_git_diff

• optimize_ai_memory

所以像 optimize_ai_memory 这样的能力：

• 不是在 Terminal 里直接输入

• 而是在 Trae、Cursor、Codex、Claude Code 等支持 MCP 的客户端里触发

运行状态与报错机制

当前开发态已经包含基础的运行状态输出和报错机制：

• 启动成功时会输出服务已监听、Memory 根目录和当前运行模式

• 遇到 uncaughtException 时会打印异常并以非零状态退出

• 遇到 unhandledRejection 时会打印异常并以非零状态退出

• 收到 SIGINT 或 SIGTERM 时会输出关闭日志

• 进程退出时会输出退出码

这意味着在 pnpm dev 运行过程中，如果启动失败、运行时抛错或进程被中断，终端里都会有明确反馈。

MCP 配置示例

{
  "mcpServers": {
    "project-memory": {
      "command": "node",
      "args": [
        "/absolute/path/to/project_memory/dist/index.js"
      ],
      "env": {
        "PROJECT_MEMORY_ROOT": "/absolute/path/to/your/project"
      }
    }
  }
}

使用说明

• 默认情况下，MCP Server 会读取 PROJECT_MEMORY_ROOT/.ai/。

• 如果没有设置 PROJECT_MEMORY_ROOT，则使用当前工作目录。

• 写入策略以追加或定向更新为主，便于审计和 Git 跟踪。

如何确认 .ai/ 实际写到哪里

如果你发现客户端里没有看到 .ai/，最常见的原因不是工具没工作，而是 project root 和你以为的目录不一致。

当前项目根目录的判定逻辑是：

1. 优先使用 PROJECT_MEMORY_ROOT

2. 如果没有设置，则回退到 process.cwd()

为了方便排查，项目现在提供：

• 启动日志会打印 Effective project root

• MCP tool get_effective_project_root

你可以直接调用：

{
  "name": "get_effective_project_root",
  "arguments": {}
}

它会返回：

• projectRoot

• memoryRoot

• projectRootSource

如果 projectRootSource 是 process.cwd()，说明客户端没有显式传入 PROJECT_MEMORY_ROOT，这时 .ai/ 很可能不在你当前打开的业务项目目录里。

推荐自动工作流

如果客户端支持基于意图自动调用 MCP tools，推荐使用下面这条明确工作流：

1. 进入项目时自动调用 bootstrap_project_context

2. 每轮对话结束时自动调用 suggest_context_updates

3. 如果属于明确完成型对话，再自动调用 record_conversation_summary

4. 当 .ai/ 变脏时，再触发 suggest_memory_optimization

为了更方便客户端接入，项目还提供了两个高层工作流封装：

• run_project_open_workflow

• run_conversation_end_workflow

如果你不想在客户端里手动编排多个 tool，也可以直接优先调用这两个工作流入口。

项目启动时的推荐流程

推荐在 AI 第一次进入项目时，优先调用 bootstrap_project_context。

它会返回两层信息：

• coreContext

  • 完整读取 project.md

  • 完整读取 current-task.md

  • 完整读取 architecture.md

  • 完整读取 coding-style.md

• supplementalContext

  • 摘要化返回 recent-changes.md

  • 摘要化返回 decisions.md

  • 摘要化返回 conversation-summary.md

  • 摘要化返回 todo.md

同时它还会返回：

• recommendedNextFiles

• warnings

其中 warnings 会提示哪些文件目前还像占位内容，适合后续继续完善。

如果你确实需要完整读取全部主要上下文，再调用 get_project_context 即可。

如果你希望直接走工作流封装，也可以调用 run_project_open_workflow。

对话结束后的更新流程

这个项目支持在每次对话结束后更新上下文文件。

推荐流程：

1. 对话结束后，由客户端调用 record_conversation_summary。

2. 工具会将一条带日期的摘要追加到 .ai/conversation-summary.md。

3. 如果这轮对话还影响了长期上下文，同一次调用也可以：

   • 覆盖 .ai/current-task.md

   • 追加到 .ai/recent-changes.md

   • 追加一条或多条记录到 .ai/decisions.md

这样可以把“短期对话摘要”和“长期项目记忆”分开维护，减少上下文被频繁误改的风险。

如果你希望一步走完对话结束阶段的推荐逻辑，也可以直接调用 run_conversation_end_workflow。

它会：

• 始终生成 suggest_context_updates 等价结果

• 在 completed=true 时自动记录对话摘要

• 在 .ai/ 需要整理时自动附带 suggest_memory_optimization 结果

建议模式

如果你希望采用“先建议，后确认”的流程，可以先调用 suggest_context_updates。

它会返回：

• 建议修改哪些 .ai/ 文件

• 每项修改是 append 还是 replace

• 对应内容的预览

随后再由用户或客户端确认是否调用 record_conversation_summary 进行真正写入。

Git Diff 摘要

可以调用 summarize_git_diff 来查看当前 Git 工作区变化。

• 如果当前目录是 Git 仓库，它会返回变更文件和 diff 统计。

• 如果当前目录不是 Git 仓库，它会返回安全的不可用结果，而不是直接报错。

• 如果 writeToRecentChanges 为 true，它还会把生成的摘要追加写入 .ai/recent-changes.md。

记忆整理流程

推荐使用两段式流程：

1. suggest_memory_optimization

2. apply_memory_optimization

这样可以先生成计划，再决定是否真正修改 .ai/。

当前会处理的内容包括：

• 初始化缺失的 .ai/ 文件

• 识别明显的占位文案

• 去除 decisions.md、recent-changes.md、conversation-summary.md、todo.md 中的重复条目

• 整理多余空白行

• 将较早的 recent-changes.md 条目归档到 recent-changes.archive.md

当前版本仍以保守优化为主，不会自动重写高风险语义内容。

归档策略

recent-changes.md 用于保留最近的变更摘要。

当其中的条目变多时，整理流程会：

• 保留最近的 3 条在 recent-changes.md

• 将更早的条目追加归档到 recent-changes.archive.md

这样可以让“最近变更”保持短小，同时保留历史记录。

触发方式

如果你已经把 project-memory 配到 MCP 客户端里，通常可以直接对 AI 说：

• “先帮我看看项目记忆该怎么整理”

• “请生成一份 memory optimization plan”

• “确认后把这些记忆整理应用掉”

也可以把它理解成两次标准 tool call：

{
  "name": "suggest_memory_optimization",
  "arguments": {}
}

确认后再执行：

{
  "name": "apply_memory_optimization",
  "arguments": {}
}

optimize_ai_memory 仍然保留为兼容入口，但更推荐直接使用上面的两段式工具。

意图触发建议

推荐客户端或 AI 采用“意图触发”而不是“固定口令触发”。

也就是说，不要求用户必须说出完全一致的一句话，只要表达的语义接近“整理项目记忆”，就可以触发 optimize_ai_memory 或后续更高层的记忆整理流程。

例如下面这些说法，都可以视为同类意图：

• “整理一下项目记忆”

• “优化一下 .ai”

• “帮我清理项目上下文”

• “把共享记忆收一收”

• “同步整理一下 memory”

• “把 recent、todo、decision 整理一下”

推荐分工如下：

• 上层 AI 负责理解自然语言意图

• MCP tool 负责执行稳定、可预期的整理动作

这样可以避免把触发逻辑设计成只能匹配单一句式，实际体验会自然很多。

什么时候用

适合在这些场景手动触发：

• .ai/ 文件积累了一段时间，想做一次整理

• 决策、最近变更或对话摘要里怀疑出现了重复内容

• 项目准备切换给另一个 AI 或另一个开发工具之前

• 想先把项目记忆整理干净，再继续沉淀新的上下文