projectmem
本地优先的编码智能体记忆层：记录问题、尝试、修复与决策，在重复踩坑前发出警告。
证据显示：本地优先、无遥测，唯一网络调用是用户显式开启的更新检查；SECURITY.md 用表格明确各文件存储位置与去向，并列出六条诚实的权衡（含 git hooks、后台 watcher、AI 提示注入风险）；提供完整卸载与 hooks uninstall，registry 迁移保留 .bak。扣分点：pjm init 默认自动安装三个 git hooks 并自动启动后台 watcher 进程，属于未经逐次确认的环境变更（虽有 --no-watch 等退出项）；依赖声明宽松，且未提供 lockfile 或依赖审计证据。未发现任何恶意行为、隐蔽外传或破坏性默认。
证据显示：测试覆盖了路径发现、registry 幂等、不可读配置显式报告等失败路径，doctor 提供自检。扣分点：README 自相矛盾——同一文档中 MCP 工具数先称 17 个，后两处称 15 个，SECURITY.md 又称 8 个；pyproject 将 0.3.2 标为 Production/Stable 但版本仍在 0.x 且曾出现全新安装即坏的回归，发布纪律不严。
证据显示：支持多种 MCP 客户端及无 MCP 的 CLAUDE.md 导出路径；0.3.x 集中修复 Windows 问题并有针对性测试，跨平台意识扎实。扣分点：能力边界描述掺入营销语气（"Save up to 50%+ of AI tokens"无实验支撑）；precheck 触发精度只有描述性主张，无静态证据表明误报率可控。
证据显示：文档架构清晰，安装说明具体到客户端差异与冷启动要求；canonical 命令与别名定义明确；CHANGELOG 逐版详述并署名贡献者；known limitations 以 "Honest trade-offs" 系统呈现，含提示注入风险；MIT 许可完整。扣分点：维护责任仅由个人与一个邮箱支撑，无治理或多人维护证据；示例多依赖外部链接，仓库内 FAQ 缺失。
证据显示：输出形态多样且可验证——dashboard 有快照/实时标注、测试确保全局视图只读不写、precheck 警告列出具体失败尝试。扣分点：核心差异化主张（唯一 pre-commit 警告、50% token 节省、可证明 ROI）全部是自我声明，仓库内无基准数据；hooks + watcher + summary.md 入库的隐性维护成本未量化。
证据显示：README 明确区分"设计能力，非基准结果"，changelog 引用具体 PR 和贡献者。扣分点：关键定量主张（50% token 节省、207 事件研究、arXiv 论文 2606.12329）在源文件内无法追溯验证，且 arXiv 编号格式可疑；对竞品的负面断言无仓库内证据。
- README 中 MCP 工具数量在 17/15/8 之间不一致，使用前请以实际运行的 pjm-mcp 为准。
- pjm init 会默认安装 git hooks 并启动后台 watcher，敏感仓库请使用 --no-watch 并在 init 后检查 .git/hooks。
- summary.md 与 PROJECT_MAP.md 默认提交进 git 且会被 AI 读取，注意提示注入风险：像审代码一样审这些文件的变更，勿在事件日志中记录密钥。
- "节省 50% token"、"可证明 ROI"、arXiv 论文等定量主张均未经独立验证，采购决策不应以此为准。
- 0.3.2 虽标为 Production/Stable，仍属 0.x 早期项目且曾出现全新安装即损坏的回归，建议锁定安装版本。
- 跨项目全局记忆 (~/.projectmem/global/) 会在项目间共享内容，敏感仓库使用 pjm init --no-global。
这个 Agent 能做什么，适合哪些场景？
projectmem 是一个开源的 AI 编码智能体记忆与判断层，把项目开发中的问题、失败尝试、修复和架构决策记录为带类型的事件，存放在仓库内的 .projectmem/ 目录（核心为 events.l 追加日志）。它内置一个原生 MCP 服务器，通过 stdio 方式接入 Claude Desktop、Claude Code、Cursor、Antigravity 和 Codex，共暴露 17 个工具，让智能体自行读取记忆并记录工作。自 0.3.0 起，一个 MCP 服务器即可通过项目注册表服务所有已注册仓库，不再需要按仓库单独配置。其独特能力是 pre-commit 警告：在提交前拦截即将重复的失败方案、高变更率文件和过期记忆，且记忆只标记过期、从不删除。整个系统 100% 本地运行，无云端、无遥测、无账户，需要 Python 与 Git，仅在你主动开启时才联网检查更新。
安装后用 pjm init 在项目内创建 .projectmem/ 目录、安装三个 git 钩子（pre-commit 警告、post-commit 分类、post-merge 追踪）并启动后台文件监视器。智能体通过 MCP 工具读写记忆：get_summary()、get_project_map()、precheck_file(path)、get_issue(id) 等读取接口，以及 log_issue()、record_attempt()、record_fix()、add_decision()、add_note() 等写入接口。git 提交时 pjm precheck 会对照事件日志，警告重复的失败方案（如“✗ tried CSS contain:layout”）、高变更率文件和引用已变动文件的过期决策；过期记忆用 pjm decision --supersedes <id> 退位而不删除历史。pjm visualize 和 pjm dashboard 提供本地仪表盘（失败热力图、ROI 评分、全局视图）；pjm export --claude-md 把记忆编译进 CLAUDE.md 供无 MCP 的智能体使用；pjm score 输出 A+→F 的预防评分。
- 使用 Claude Code 或 Cursor 的开发者，希望新会话不再从零开始、不再重复昨天的调试死胡同
- 维护多个仓库的团队，想用 pjm doctor 和全局仪表盘一次配置、统一查看所有项目的记忆与问题热点
- 经常在同一个高变更文件上反复踩坑的工程师，需要提交前收到具体的失败历史警告
- 使用 Copilot 等不支持 MCP 的智能体的开发者，通过 pjm export --claude.md 把“勿重试清单”注入 CLAUDE.md
- 研究智能体记忆系统的研究者，可参考其 arXiv 论文中的 Memory-as-Governance 框架与 207 事件狗粮实验
- 在意隐私的个人开发者，需要完全本地、无遥测的记忆方案，并可将 .projectmem/ 加入 .gitignore 保持私密
这个 Agent 有哪些优点和局限？
- Pre-commit 失败警告是独有能力：在提交前阻止重复已知失败方案，README 对比表中标明其他工具均不具备
- 记忆从不删除：过期决策通过 --supersedes 退位并在日志中保留标记，避免静默衰减导致的知识丢失
- 单一 MCP 服务器（0.3.0+）服务所有注册项目，每次写入都会报告落点项目，且 pin 死的服务器拒绝越界写入
- 100% 本地：无云端、无账户、无遥测，唯一网络调用是用户主动开启的更新检查
- 多客户端验证过：Claude Desktop、Claude Code、Cursor、Antigravity、Codex 均有具体配置说明
- 无数据库、无常驻服务：MCP 服务器是 stdio 子进程，其余皆为纯文本文件，可直接 grep
- 需要 Python 环境和 Git 仓库，且客户端配置必须用绝对 Python 路径（子进程不继承 shell PATH），配置出错是常见故障点
- MCP 客户端必须完全冷启动才能加载服务器，每次配置改动都需要重启工具
- 记忆捕获依赖智能体主动调用写入工具，README 承认无提示时捕获一致性会下降，需要开场提示词
- Codex 需要手动编辑 TOML（其 UI 保存不可靠）且推理档位需设为 medium 以上才能执行完整会话启动流程
- distilled 文件默认提交进仓库（summary.md 等），不希望共享记忆的团队需手动改 .gitignore
- 对比表中多数能力为设计声明而非基准测试结果，实际收益（如 50% token 节省）来自项目自述而非独立验证
如何安装或部署这个 Agent？
- pip install -U projectmem
- cd 到你的项目并运行 pjm init（会安装 git 钩子、创建 .projectmem/ 并自动注册项目）
- 运行 pjm doctor 检查已有项目并 pjm doctor --fix 注册它们
- 在 MCP 客户端配置中加入（Claude Desktop/Cursor/Codex 等）：
"mcpServers": { "projectmem": { "command": "/absolute/path/to/python", "args": ["-m", "projectmem.mcp_server"] } }
（Codex 使用 TOML：[mcp_servers.projectmem]，同样填绝对 python 路径）
- 完全退出并重启客户端（MCP 服务器仅在冷启动时加载），再运行 pjm doctor 验证。
如何使用这个 Agent？
日常流程：pjm brief 查看会话开始简报；用 pjm log、pjm attempt --failed/--worked、pjm fix、pjm decision、pjm note 手动记录，或让智能体通过 MCP 工具自动记录（log_issue、record_attempt、record_fix、add_decision、add_note）；编辑文件前智能体调用 precheck_file(path)；意图与计划写在 plan.md（pjm plan），与事件日志分离。提交时 pjm precheck 自动拦截重复失败方案，pjm precheck --snooze 2h 可临时静音（静音本身会被记录）。可视化用 pjm visualize（六标签仪表盘）、pjm dashboard（跨项目全局视图）、pjm score（ROI 评分）。
这个 Agent 与同类方案有什么区别？
README 对比了 claude-mem（会话捕获，后台 worker 且默认开遥测）、agentmemory（带衰减剪枝的记忆引擎）、mem0（聊天记忆，更新时改写事实）和 Letta/MemGPT（需要运行服务器 + Postgres 或云）。projectmem 的差异化在于：预提交失败警告（独有）、只标记过期从不删除、无数据库无常驻服务、可读的纯文本 events.l 存储、可证明的 ROI 评分，以及与记忆分离的 plan.md 意图文件。项目还计划在 0.3.3 提供 pjm import 从 mem0、agentmemory、Letta 和 Claude 会话日志迁移。