riponcm/projectmem

projectmem – 为 AI 编码代理打造的本地优先记忆

功能简介 – projectmem 在每个仓库中创建一个极小的自包含数据库（隐藏的 .projectmem/ 文件夹）。它记录 AI 辅助开发人员在处理代码时发生的类型化事件，例如问题、尝试的修复、决策和笔记。然后，本地 MCP（Multi‑Client Protocol）服务器公开 17 个工具，供流行的编码代理——Claude Desktop/Code、Cursor、Antigravity、Codex 等——调用，以读取该历史记录并记录新操作。目标是让代理不再每次会话都从头开始，避免重复已知的死胡同，并减少 token 使用量。

关键组件

• pjm CLI – 主要用户界面（pjm init、pjm doctor、pjm precheck、pjm dashboard 等）。它注册项目、安装 git 钩子（提交前警告、提交后分类、合并后跟踪）、启动 MCP 服务器，并生成可视化仪表板。
• MCP 服务器 – 单个 Python 进程，为所有已注册项目提供服务。客户端只需在其 AI 工具配置中配置一次（mcpServers.projectmem.command 等）。服务器响应 log_issue、precheck_file、get_context 等调用。
• 事件存储 – 纯文本 events.jsonl 加上派生的 summary.md。事件是类型化的（问题、尝试、修复、决策、笔记），并链接到它们所关注的源文件。
• 仪表板 – HTML 可视化（pjm visualize、pjm dashboard），显示“记忆卡”、失败热图、ROI、案例文件以及跨多个项目的全局视图。
• 提交前警告 – 一个 git 钩子，在提交前检查事件日志，并在更改重复先前失败的方法时发出警告。

如何使用

1. pip install -U projectmem。
2. 运行 pjm doctor 以发现现有仓库并注册任何缺失的仓库。
3. 将生成的 MCP 配置块添加到你的 AI 编码工具（Claude、Cursor 等）。
4. 在仓库内，pjm init 创建 .projectmem/、安装 git 钩子并启动监视器。
5. 从那时起，AI 会在会话开始时读取存储的事件，并自动写入新事件；你也可以手动调用 pjm precheck。

新内容（v0.3.4）

• 摘要现在设有上限，以保持精简（token 数量减少约 60%）。
• 提交会归入它们所修改的实际源文件下，修复了过时警告的错误。
• 过时警告的时区处理现在基于 UTC，使其在全球范围内可靠。
• MCP 文档中的工具签名已更正；现在有测试验证每个公开的调用。
• 针对 Windows、Python 3.13/3.14 和升级路径处理的轻微稳定性修复。

为何重要 AI 编码助手是无状态的；没有外部记忆，它们会重复读取整个代码库并重新探索失败的修复，浪费 token 和开发人员时间。projectmem 提供了一个本地优先、保护隐私的记忆层，能持久保存代码更改背后的“原因”，使代理能够凭经验行动，而不是从空白状态开始。

了解更多

• 完整网络指南：https://projectmem.dev/guide
• 演示视频：https://youtu.be/pELGdXHj_Ls
• 研究论文（arXiv 2606.12329）描述设计以及一项 207 事件研究。
• 源代码和文档位于 GitHub；包位于 PyPI。