projectmem 编程记忆

这个 Agent 能做什么，适合哪些场景？

projectmem 是面向 AI 编程代理的本地优先、事件溯源式记忆与判断层，记录问题、尝试、修复、决策和备注。它由 Python CLI、原生 MCP 服务器、Git 钩子、文件监视器、项目注册表以及本地可视化面板组成，并可通过一个 MCP 服务器访问多个已注册项目。每个项目的记忆保存在仓库内的 .projectmem/ 中，原始事件写入 events.jsonl，工具再生成供代理读取的精简摘要、问题文件和项目地图。预提交检查会结合失败历史、文件变更频率、未解决问题和可能过期的记忆，在提交前给出警告；旧记录不会被静默删除，而是可以标记过期或由新决策取代。它适合希望在 Claude Code、Claude Desktop、Cursor、Antigravity、Codex 或其他 MCP 客户端之间共享项目经验，同时坚持无账户、无遥测和本地存储的开发者。采用时需要接受 Python、Git 钩子、项目内记忆文件和客户端 MCP 配置带来的维护成本，并注意部分客户端必须完全重启才能加载服务器。

运行 pjm init 后，projectmem 创建 .projectmem/，安装预提交、提交后分类和合并后跟踪三个 Git 钩子，构建代码结构，并启动实时文件监视器。开发过程中可用 pjm log、pjm attempt、pjm fix、pjm decision 和 pjm note 写入带类型的事件；pjm regenerate 从 events.jsonl 重建 summary.md。MCP 客户端通过 get_instructions()、get_summary()、get_project_map()、get_plan()、get_issue(id) 和 search_events(query) 读取上下文，并通过 log_issue、record_attempt、record_fix、add_decision、add_note 写回经验。代理编辑文件前可调用 precheck_file(path)，命令行上的 pjm precheck 则在提交前检查已失败方案、高频变更文件、未解决问题和可能过期的文件相关决策。pjm brief 生成会话开场简报，pjm context 与 pjm wrap 生成受令牌预算约束的上下文，pjm export --claude-md 或 --cursor 可把有效经验导出给不支持 MCP 的代理。pjm visualize 生成单项目六标签页本地面板，pjm dashboard 聚合所有已初始化项目，pjm map --build 从 Python 导入关系构建结构图并叠加失败热度。自 0.3.0 起，项目注册表允许单个 MCP 服务器路由到多个仓库；显式 --root 可将服务器严格限制在一个项目。

1. 经常切换或重开 AI 编程会话的开发者，用它保存昨天的调试失败、已确认修复和架构决定，避免下一次会话从零开始。
2. 同时维护多个仓库的工程师，用一个全局 MCP 配置连接所有已注册项目，并通过 project 参数或活动项目选择写入目标。
3. 担心代理重复修改高风险文件的团队，在提交前用 pjm precheck 查看该文件的失败尝试、高频变更和可能过期的决策。
4. 使用不支持 MCP 的 Copilot、普通 Claude 或其他文件读取型助手的用户，把当前决策、注意事项和不可重试清单导出到 CLAUDE.md 或 .cursorrules。
5. 需要回顾研发过程或展示调试成本的项目，用本地面板、时间轴、问题链、失败热图和 pjm score 查看记忆与估算的节省效果。
6. 希望团队共享精炼经验但保留原始日志隐私的仓库，将摘要、项目地图、说明和问题文件提交到 Git，同时让原始 events.jsonl 保持忽略状态。

如何安装或部署这个 Agent？

需要 Python、Git 仓库以及可执行 shell。首次安装或升级：

pip install -U projectmem

进入目标仓库并初始化：

cd your-project
pjm init

若已有旧项目或正在从 0.1.x/0.2.x 升级，先扫描，再注册发现的项目：

pjm doctor
pjm doctor --fix

不需要账户、API 密钥或云端服务。默认运行不需要网络；只有显式使用 pjm doctor --online、--auto 或在面板点击更新检查时才会查询新版本。

如何使用这个 Agent？

先查看会话简报和已有记忆：

pjm brief
pjm show

记录一次完整的问题处理过程：

pjm log "authentication callback returns an empty session"
pj m attempt "increase callback timeout" --failed

上例第二条命令在来源中没有这种带空格的别名写法；实际应使用：

pjm attempt "increase callback timeout" --failed
pjm fix "preserve the session cookie during callback"

在编辑或提交前检查历史风险：

pjm precheck

构建项目结构并打开本地视图：

pjm map --build
pjm visualize

为所有已注册项目配置一个 MCP 服务器，可将以下内容加入客户端配置，并把 Python 路径替换成机器上的绝对路径：

{
  "mcpServers": {
    "projectmem": {
      "command": "/absolute/path/to/python",
      "args": ["-m", "projectmem.mcp_server"]
    }
  }
}

Codex 使用 ~/.codex/config.toml：

[mcp_servers.projectmem]
command = "/absolute/path/to/python"
args = ["-m", "projectmem.mcp_server"]

完全退出并重新打开客户端后，让代理在会话开始调用 get_instructions()、get_summary() 和 get_project_map()；编辑文件前调用 precheck_file(path)，工作中及时记录问题、尝试、修复、决策和备注。若希望服务器只能访问一个仓库，在启动参数中加入 --root 和仓库绝对路径。

这个 Agent 有哪些优点和局限？

这个 Agent 与同类方案有什么区别？

与相关度最高的同类 agent 并排比较关键指标。

FollowAgents 如何评估这个 Agent？

最近版本

来自该项目 GitHub Releases 的最新发布记录，说明为上游原文摘录，未经本站改写或测试。

1. v0.3.4 v0.3.4 — memory that stays small, and warnings you can trust 2026-10-02
   发布说明摘录

   Three community reports, three community fixes, and six more bugs found by checking them. Each report was reproduced end to end before it was fixed, and every fix was reviewed by someone other than its author. ```bash pip install -U projectmem ``` Then run pjm init once in each project. Older projects keep the AI_INSTRUCTIONS.md and git hooks of the release that created them; re-running init now refreshes both. Your previous instructions are kept as AI_INSTRUCTIONS.md.bak, and anything of yours outside projectmem's block in a hook is left untouched. Fixed …

   在 GitHub 查看 ↗
2. v0.3.3 v0.3.3 — precheck stops getting slower, and Windows works end to end 2026-09-15
   发布说明摘录

   Six field reports closed, and the check that runs before every edit no longer gets slower as your project ages. Every fix below was found by running projectmem on the machine that reported it — Windows 11, and all four MCP clients — not by reading the code. Two of them were found only because a client launched the server from a directory we did not expect. ```bash pip install -U projectmem ``` Faster pjm precheck was taking 26 seconds on a 1,200-event project, and getting worse every week. …

   在 GitHub 查看 ↗
3. v0.3.2 v0.3.2 — Windows watch support, and a doctor that tells the truth 2026-09-07
   发布说明摘录

   Windows works properly now — and pjm doctor stops saying green when it cannot see. ```bash pip install -U projectmem ``` Every fix below was found by running the thing on Windows, not by reading the code. The watcher works on Windows pjm watch --daemon crashed there with AttributeError: module 'os' has no attribute 'fork'. Daemonisation used the POSIX-only os.fork() and os.setsid(); it now spawns a detached worker with subprocess.Popen — DETACHED_PROCESS | CREATE_NEW_PROCESS_GROUP | CREATE_NO_WINDOW on Windows, start_new_session=True elsewhere. …

   在 GitHub 查看 ↗

常见问题