repo-memory-mcp

repo-memory-mcp

mcp-name: io.github.Umarjaum/repo-memory-mcp

为 AI 编码 Agent 提供持久记忆

AI 编码 Agent 功能强大，但会忘记特定于代码仓库的更正、惯例、约束和架构决策。repo-memory-mcp 为兼容 MCP 的编码 Agent 提供持久化、本地化且了解代码仓库的记忆层。

只需教会编码 Agent 一次，让你的代码仓库记住一切。

功能

MCP 主机决定何时调用工具；MCP 不会自动拦截每一段对话。本项目提供显式工具，让 Agent 能在会话启动时加载重要上下文、搜索相关记忆、保存更正和决策、更新过时的指引，以及归档不再适用的记忆。

记忆数据库位于检测到的代码仓库中的 .repo-memory/memory.db。它使用 SQLite、确定性的本地排序，且不依赖云服务。

开发者选择它的原因

• 持久化项目记忆： 更正、规则、惯例、约束、决策和修复 Bug 的经验教训都能跨会话保留。
• 了解代码仓库并隔离数据： 不同代码仓库的记忆互不共享。
• 隐私优先，本地运行： 无需 API 密钥、远程数据库、外部嵌入、遥测或后台上传。
• 显式 MCP 工作流： Agent 自行决定何时记忆和回忆；项目不会声称能够自动拦截对话。
• 快速且便于检查： 使用 SQLite 存储，支持 JSON 导出、CLI 诊断和人类可读的记录。
• 注重安全： 默认拒绝可能的 API 密钥、Bearer 令牌、密码、云凭证和私钥。

两分钟内完成安装和使用

公开发布到 PyPI 的发行包名为 repo-memory-mcp-ai，因为较短的 repo-memory-mcp 名称已被另一个项目使用。MCP 服务和 GitHub 项目的身份仍为 repo-memory-mcp。

pip install repo-memory-mcp-ai
repo-memory doctor

直接启动 MCP 服务：

repo-memory-mcp

或者无需永久安装即可运行：

uvx --from repo-memory-mcp-ai repo-memory-mcp

该服务在本地运行，并通过 stdio 通信，无需 API 密钥。

配置 MCP 客户端

常见的 stdio 配置如下：

{
  "mcpServers": {
    "repo-memory": {
      "command": "uvx",
      "args": ["--from", "repo-memory-mcp-ai", "repo-memory-mcp"]
    }
  }
}

请使用 MCP 主机文档中说明的客户端专用配置位置和格式。可直接复制的示例位于 examples/：

• claude-desktop.json
• cursor.json
• workflow.md

本项目不依赖特定厂商，适用于 Claude Code、Cursor、Cline、Windsurf 及其他兼容 MCP 的编码 Agent。兼容性取决于主机对 MCP 的支持情况和配置格式。

推荐的 Agent 工作流

在编码会话开始时，调用 get_startup_context()。开发者纠正了反复出现的错误时，调用 remember_correction(topic, lesson)。出现相关问题时，调用 recall_memory(query)。指引过时时，调用 update_memory()，或使用 forget_memory() 将其归档。

给 Agent 的示例指令：

At the start of this session, call get_startup_context. If I correct a repeated mistake or establish a durable project rule, store it with the appropriate repo-memory tool. Do not store credentials or transient chat context.

可用的 MCP 工具

工具	用途
get_startup_context	在会话开始时加载简明且高价值的仓库指南
remember_correction	记录从纠正或错误修复中总结的经验
remember_rule	记录持久适用的项目规则或惯例
remember_decision	记录架构决策及其理由
recall_memory	使用确定性的本地评分搜索有效记忆
list_project_rules	列出有效的项目规则
list_memories	按类型或状态筛选记忆
update_memory	修正现有记忆，而不创建替代记忆
forget_memory	归档过时记忆，以便于审计的方式留存
export_memory / import_memory	在同一仓库的安全副本之间迁移已验证的记忆

命令行

repo-memory init
repo-memory list
repo-memory rules
repo-memory search "database migrations"
repo-memory export ./memory-backup.json
repo-memory import ./memory-backup.json
repo-memory doctor

隐私与安全边界

记忆保留在运行服务的设备上。此实现不需要 API 密钥、云账户、远程数据库、外部嵌入或遥测。它只会检查明确提交给记忆工具的文本。你的操作系统、包管理器、备份和 MCP 主机可能有各自的行为。

默认情况下会拒绝可能包含机密的信息。请勿向记忆工具提交密码、令牌、私钥或凭据。.repo-memory/ 目录已被 Git 忽略，因此私有记忆不会意外提交。

开发

git clone https://github.com/Umarjaum/repo-memory-mcp.git
cd repo-memory-mcp
python -m venv .venv
. .venv/bin/activate
pip install -e '.[dev]'
pytest

发现与发布

• 项目网站：repo-memory-mcp.negoshades.workers.dev
• 文档：快速入门和工具
• 客户端指南：Claude、Cursor、VS Code、Cline 和 Windsurf
• 扩展：VS Code 和兼容 Bing 的浏览器伴侣工具
• 贡献：开源贡献指南
• 源代码：GitHub
• 包：PyPI
• 注册表元数据：server.json
• 发布指南：PUBLISHING.md

开发者

Muhammad Umar Jabbar — 巴基斯坦旁遮普省卡内瓦尔。个人网站：umarjaum.netlify.app。

路线图

未来的工作可能包括改进排序、添加置信度反馈、提供可选的本地嵌入、生成项目上下文、添加记忆检查界面，以及将伴侣扩展发布到官方市场。团队/共享记忆仍明确设为可选加入。

伴侣扩展

• extensions/vscode 为 VS Code 提供本地设置命令。
• extensions/bing 提供注重隐私的 Manifest V3 上下文菜单助手，可将选中的 Bing 研究内容转换为 repo-memory 提示词。

此浏览器伴侣工具有意不调用本地 stdio MCP 进程。浏览器与 MCP 的直接集成需要一个单独审核的原生消息传递桥接程序。

许可证

MIT。请参阅 LICENSE。