Project Memory MCP

Project Memory MCP

用于持久化项目记忆的 MCP 服务和 Claude Code 插件。借助 MEMORY.md 文件，让 AI Agent 能够在不同对话之间保留项目知识。

功能

• 存储与检索 Markdown 格式的项目知识
• 增量更新，通过 SEARCH/REPLACE 补丁实现
• 自动读取钩子 —— 在首次提示时自动加载项目记忆（Claude Code 插件）
• Dream consolidation —— 自动清理并去重项目记忆（Claude Code 插件）

安装

Claude Code 插件（推荐）

安装 MCP 服务、自动读取钩子和 Dream consolidation：

/plugin marketplace add /path/to/project-mem-mcp
/plugin install project-mem@cc-plugin-project-mem

独立 MCP 服务

适用于 Codex、Claude Desktop、Cursor 或其他 MCP 客户端：

uvx project-mem-mcp

MCP 客户端配置

{
  "mcpServers": {
    "project-mem-mcp": {
      "command": "uvx",
      "args": [
        "project-mem-mcp",
        "--allowed-dir", "/path/to/your/projects"
      ]
    }
  }
}

--allowed-dir 参数用于限制服务可访问的目录。可以多次使用。省略时，默认为当前工作目录。

从源代码安装

git clone https://github.com/pynesys/project-mem-mcp.git
cd project-mem-mcp
python -m venv venv
source venv/bin/activate
pip install -e .

工具

get_project_memory

获取 MEMORY.md 内容。不带额外参数时，返回整个文件。如果文件的估算令牌数超过约 20K（低于大多数客户端的工具结果上限），服务会抛出 ValueError；请使用 head_only 或 offset/limit 获取所需内容。

get_project_memory(
    project_path: str,
    offset: int = 0,           # 1-indexed start line; 0 = from start
    limit: int | None = None,  # max lines to return
    head_only: bool = False,   # return only size + heading TOC
) -> str

处理大型文件的常见方式：先调用一次并设置 head_only=True，以获取文件大小和章节目录（行号范围），然后通过 offset/limit 获取各章节。

search_project_memory

在 MEMORY.md 中进行子字符串搜索，不区分大小写。返回匹配行及从 1 开始的行号；结合 get_project_memory(offset, limit) 获取匹配项周围的上下文。

search_project_memory(
    project_path: str,
    query: str,
    max_results: int = 50,
) -> str

set_project_memory

覆盖整个 MEMORY.md。用于创建新的项目记忆，或在补丁应用失败时使用。

set_project_memory(
    project_path: str,
    project_info: str | None = None,
    project_info_file: str | None = None,
)

内容必须且只能来自以下两个来源之一：project_info 是 Markdown 原文；project_info_file 是服务自行读取的 UTF-8 文件绝对路径。对于草拟到文件中的大型改写，推荐使用后者，因为无需将内容作为参数再次传入。参数不会进行 Shell 展开，因此 project_info 中的 $(cat draft.md) 不起作用（服务会拒绝看起来像未展开替换表达式的载荷）。

update_project_memory

对 MEMORY.md 应用单个 SEARCH/REPLACE 补丁：

update_project_memory(project_path: str, patch_content: str)

补丁格式：

<<<<<<< SEARCH
Text to find in the project memory file
=======
Text to replace it with
>>>>>>> REPLACE

搜索文本必须在文件中恰好出现一次。将替换内容留空即可删除内容。

插件功能

作为 Claude Code 插件安装后，还可使用以下功能：

Project-memory Skill（自动触发）

指导 Claude 何时以及如何将内容保存到项目记忆中。当发现值得持久保存的见解时，会自动触发，例如架构决策、注意事项、不明显的模式和当前工作上下文。此技能标记为 user-invocable: false，因此不会显示在斜杠命令选择器中；主模型会自主调用它。

自动读取钩子

在每个会话的首次提示时，自动将 MEMORY.md 读入上下文。无需手动调用工具。

梦境整合

写入后自动触发项目记忆维护，条件如下：

• 文件大小超过 50KB
• 距上次整合已超过 24 小时

梦境会启动一个 sonnet 子 Agent，以便：

• 移除与 CLAUDE.md 文件重复的内容
• 合并已不再活跃的主题，并精简较早的 Recent Sessions 条目
• 重新组织内容，使其更清晰、更易于大模型阅读
• 大幅缩减臃肿的文件（以每次处理约缩减 30% 为目标），而非仅仅维持原样

如果触发梦境的会话刚刚写入了必须保持原样的内容，则会向子 Agent 传递一份简短的 Preserve verbatim 指针列表——这些内容会保持不变，同时整合仍会处理文件的其余部分。

不会创建备份；如有需要，可使用 git 恢复梦境运行前的状态。

手动触发：/dream

上次梦境的时间戳存储在 MEMORY.md 顶部 YAML frontmatter 块中的 last_dream: 字段里。以前使用此插件的项目可能仍有 .claude/.last-dream-timestamp 文件——该文件现已被忽略，可以安全删除（升级后首次运行梦境时，会重新填充 frontmatter）。

安全

• 根据 --allowed-dir 参数验证项目路径
• 项目记忆文件不得包含敏感信息
• 项目记忆文件必须使用英文

依赖项

• fastmcp (>=3.2.0, <4.0.0)

许可证

MIT