项目名：projectmem（riponcm/projectmem）GitHub：GitHub - riponcm/projectmem: Open-source coding agents memory. Records issues, attempts, fixes and decisions, then warns your agent before it repeats an approach that already failed. Native MCP server for Claude Code, Cursor, Antigravity and Codex. 100% local, no cloud, no telemetry. MIT. · GitHub ｜ 官网：Open-source coding agent memory for Claude Code, Cursor & Codex — projectmem 版本：v0.2.0 ｜ 协议：MIT ｜ Star：745（2026-05 新建） 语言：Python ｜ 适用：Claude Code / Claude Desktop / Cursor / Antigravity / Codex
开篇：AI 啥都好，就是记性比鱼还差
用 Claude Code / Cursor 写过两周以上代码的人，大概率都遇到过这几个让你血压升高的瞬间：
- 同一个 bug，上周刚花两小时修好，今天 AI 又给你写出一模一样的错误方案；
- 上次试过某个库的某个版本不兼容，踩了半天坑，三个月后 AI 又推荐同一个；
- 每开一个新 session，AI 都要把你项目里十几个关键文件重读一遍，token 哗哗烧；
- 你跟它讲过一百遍"我们项目用 MyBatis-Plus，不要写 JPA"，下个 session 它又开始写 JPA 注解。
模型不是不聪明，是没有记忆皮层。每次对话都是从零开始。
最近挖到一个项目projectmem，专门治这个病，2026 年 5 月刚上线，名字很直白：
Local-first AI coding memory. Records issues, attempts, fixes and decisions, then warns your agent before it repeats an approach that already failed.
最猛的一点：它有一个**"pre-commit warning"**——AI 刚准备改代码，它发现这个方案以前踩过坑，直接弹警告阻止。其他所有记忆工具都只在事后总结，它在事前拦。
这篇是我在 Java 题库项目上实测一周的完整笔记，包含 MCP 接入、工作流、token 节省对比、踩坑。
目录
- projectmem 是什么
- 和 claude-mem / mem0 / Letta 比有什么不一样
- 核心概念：Event、Judgment、Plan
- Windows 安装：3 分钟搞定
- 接入 Claude Code / Cursor 的 MCP 配置
- 实战：在一个 Spring Boot 项目里养出"记忆"
- Pre-commit Warning 实战演示
- 15 个 MCP 工具速查
- Token 到底能省多少
- 跨项目 Dashboard：一张屏看所有仓库
- 常见坑和解决方案
- 适合谁 / 不适合谁
一、projectmem 是什么
按官方说法：
projectmem is an open-sourceagent memorylayer. It islocal-first: memory lives in a plain
.projectmem/directory inside your repository, with no cloud, no account and no telemetry. A nativeMCP serverexposes 15 tools to Claude Code, Claude Desktop, Cursor, Antigravity and Codex.
拆开看四个关键词：
1. Local-first
所有记忆存在你项目里的.projectmem/目录：
your-project/ ├── .projectmem/ │ ├── events.jsonl # 只追加的原始事件日志 │ ├── plan.md # 你的意图、计划 │ ├── summary.md # AI 读的小文件 │ └── index/ # 派生索引（gitignore） └── src/...没有数据库、没有云、没有账号、没有遥测。MIT 开源，随便审计。
2. Event-sourced（事件溯源）
它不存"对话历史"，而是存结构化事件：
issue：碰到的问题；attempt：尝试过的方案；fix：最终怎么修好的；decision：架构/技术决策；note：自由备注。
每条事件有类型、时间、相关文件、上下文。这是它能做"判断"而不只是"回忆"的关键。
3. Judgment（判断层）
这是 projectmem 最特别的地方。它不只记"发生了什么"，还会在 AI 准备动手时判断：
这个方案以前试过吗？试过的话结果怎么样？失败了要不要警告？
这就是pre-commit warning，业界独一份。
4. MCP 原生
一个 stdio 子进程，15 个工具，Claude Code/Cursor 一连就用。不用跑后台服务、不用配端口。
二、和 claude-mem / mem0 / Letta 比有什么不一样
官方对比表（2026 年 6 月快照）：
| 能力 | projectmem | claude-mem | agentmemory | mem0 | Letta/MemGPT |
|---|---|---|---|---|---|
| 核心定位 | 记忆 + 判断 | 会话抓取 | 记忆引擎 | 聊天记忆 | Agent 框架 |
| Pre-commit 失败预警 | ✅独有 | ❌ | ❌ | ❌ | ❌ |
| 过时记忆：标记不删 | ✅ | ❌ | ❌ 静默衰减 | ❌ | ❌ |
| 可替换（Supersede）不丢历史 | ✅ | ❌ | ❌ | ❌ | ❌ |
| 记录架构决策 | ✅ | ❌ | 🟡 | ❌ | 🟡 |
| 无 MCP 也能用（CLAUDE.md 导出） | ✅ | ❌ | ❌ | ❌ | 🟡 |
| 跨项目记忆 | ✅ 库级 | 🟡 | 🟡 | 🟡 | 🟡 |
| 可验证 ROI 评分 | ✅ A+ 到 F + 钱 | ❌ | ❌ | ❌ | ❌ |
| 纯文本可 grep | ✅ events.jsonl | ❌ | ❌ | ❌ | 🟡 |
| 无需服务/数据库 | ✅ stdio + 文件 | ❌ | ❌ | ❌ | ❌ 要 Postgres |
| 无遥测、无账号 | ✅ | ❌ 默认开 | ✅ | ❌ | 🟡 |
| 原生 MCP | ✅ 15 工具 | ✅ | 🟡 53 工具 | 🟡 | 🟡 |
| 全局 Dashboard | ✅ 读时聚合 | ❌ | 🟡 中央存储 | ❌ | ❌ |
| 可编辑意图（plan ≠ memory） | ✅ plan.md | ❌ | ❌ | ❌ | 🟡 |
| 价格 | ✅ 免费 MIT | 免费+付费 | 免费 | Freemium | 免费+云 |
几个关键差异：
- claude-mem跑后台 worker（37777 端口）、默认开遥测；
- mem0更新时会重写事实，旧信息没了；
- agentmemory用衰减算法自动降权甚至删除老记忆；
- Letta要跑 Postgres 或云服务；
- projectmem：只追加、不删除、不静默改，过时的记忆会被标记为 stale，由你决定怎么处理。
这设计哲学很对工程师胃口——审计日志就是只能追加。
三、核心概念：Event、Judgment、Plan
3.1 Event（事件）
五种类型，每条都是 JSONL 一行：
{ "id": "evt_abc123", "type": "attempt", "timestamp": "2026-08-21T10:30:00Z", "summary": "Tried Spring AI 1.0 M0 with DeepSeek, tool calls failed", "files": ["pom.xml", "src/.../AiClientFactory.java"], "related_issues": ["evt_xyz789"], "outcome": "failed", "failure_reason": "Spring AI M0 DSML dialect missing for DeepSeek tool calls" }3.2 Judgment（判断）
pjm score给项目打 A+ 到 F：
- A+：大量 issue/attempt/fix/decision 闭环，AI 能从记忆里学到东西；
- C：有记忆但缺决策记录；
- F：只有碎片笔记，没结构。
还会折算成节省的 token / 美元——这是我见过最实在的 ROI 指标。
3.3 Plan（意图）
v0.2.0 新增的plan.md，和记忆分开：
- 事件日志 = 发生了什么；
- plan.md = 你打算做什么。
AI 可以直接编辑plan.md，但不会把它混进事件历史。这解决了一个大问题：以前想给 AI 写"下一步计划"，要么改 CLAUDE.md（污染），要么写到 issue（断开）。现在pjm plan一条命令搞定。
四、Windows 安装：3 分钟搞定
4.1 前置
- Python 3.10+
- 一个支持 MCP 的 AI 编码工具（Claude Code / Cursor / Antigravity / Codex）
4.2 安装
pip install projectmem验证：
pjm --version4.3 在项目里初始化
cd D:\develop\exam-bank pjm init会在项目根目录创建.projectmem/骨架，并问你几个问题：项目名、主要语言、技术栈摘要。
4.4 让 AI 自己接 MCP
最简单的方式：直接让你的 AI 帮你配。
在 Claude Code 里说：
帮我把 projectmem MCP server 配置到 Claude Code，按它官方文档的方式来。
AI 会自己改.mcp.json或~/.claude/mcp.json。它有文件系统和 shell，30 秒搞定。
当然，你也可以手动配，见下一节。
五、接入 Claude Code / Cursor 的 MCP 配置
5.1 Claude Code
编辑~/.claude/mcp.json（全局）或项目根目录.mcp.json（项目级）：
{ "mcpServers": { "projectmem": { "command": "pjm", "args": ["mcp"], "env": { "PROJECTMEM_PROJECT_ROOT": "D:/develop/exam-bank" } } } }Windows 如果pjm不在 PATH，用绝对路径：
where pjm # 假设返回 C:Python311Scriptspjm.exe{ "mcpServers": { "projectmem": { "command": "C:\Python311\Scripts\pjm.exe", "args": ["mcp"] } } }5.2 Cursor
Settings → MCP → Add new server：
- Name:
projectmem - Type:
command - Command:
pjm mcp
5.3 验证
重启 Claude Code，在对话框里：
用 projectmem 列一下当前项目的记忆摘要。
AI 会调用get_summary()，返回当前项目的 issue/fix/decision 概览。第一次是空的，正常。
六、实战：在一个 Spring Boot 项目里养出"记忆"
拿你自己的 AI 题库项目举例（D:\develop\exam-bank）。
6.1 第一周：让 AI 自动记录
正常写代码、修 bug、做决策。每次解决一个问题，告诉 AI：
用 projectmem 记一下：我们刚踩了 PaddleOCR 在 Windows 上 MKLDNN 崩溃的坑，最终方案是降级到 2.7.0 并关闭 mkldnn。
或者更省事——直接说：
这次修 bug 的过程用 projectmem 记一下。
AI 会自动调log_issue、log_attempt、log_fix，把来龙去脉结构化存下来。
6.2 典型事件示例
你这项目里值得记的事件大概有：
- Decision：使用 DeepSeek + 豆包双模型，不直接绑定 OpenAI；
- Issue：Python 服务
/api/files/{filename}路径穿越漏洞； - Attempt：试图用 RAPIDOCR 替换 PaddleOCR，Windows 兼容性问题；
- Fix：CORS 配置只允许
http://localhost:5173； - Note：
application.yml里的 API key 已经是死配置，真实配置走 DB； - Decision：多租户改造暂不做，单用户买断优先。
6.3 一周后查看
pjm score pjm contextpjm context会输出一份压缩的项目上下文（~2500 token），你可以直接放进 PR 描述、issue、或给新加入的 AI session。
6.4 注入到 CLAUDE.md
pjm wrappjm wrap会把摘要和关键事件生成一个 markdown 片段，你把它 include 到CLAUDE.md里，任何 AI 工具不用 MCP 也能读到记忆。
七、Pre-commit Warning 实战演示
这是 projectmem 的杀手锏，必须单独讲。
7.1 场景
你三个月前修过一个 bug：
Issue：ChatController 的 SSE 端点用
sessionId查询参数但没做归属校验，任何登录用户能看别人对话。Fix：从HttpSession取当前用户 ID，不再信任前端传参。
三个月后，新的需求让 AI 改 SSE，它"灵机一动"写了：
@GetMapping(value = "/stream", produces = MediaType.TEXT_EVENT_STREAM_VALUE) public SseEmitter stream(@RequestParam String sessionId) { ChatSession session = chatService.getById(sessionId); // ... }7.2 projectmem 怎么拦
MCP server 在代码被写入前，会做一次判断：
- 扫当前 AI 准备改的文件、改的方式；
- 查事件日志有没有相关 failed attempt；
- 发现高度匹配，直接返回pre-commit warning：
⚠️projectmem warning: This approach was attempted on 2026-05-12 and failed. Reason: Taking sessionId from query param without ownership check caused IDOR vulnerability. Fixed by: HttpSession.getAttribute("loginUser"). Related files: ChatController.java, LoginInterceptor.java Are you sure you want to proceed?
AI 看到警告会主动停下来告诉你："这个方案以前踩过坑，我们上次用 XXX 方案修的，这次要不要同样处理？"
7.3 为什么其他工具做不到
- mem0 / claude-mem 只做"回忆"，不会主动判断当前动作；
- 它们返回的是"你以前说过……"，projectmem 返回的是"你现在要做的事，以前失败过"；
- 关键是事件类型和文件关联是结构化的，不是模糊文本匹配。
这一个功能，按官方 207 个事件的 dogfooding 研究，能挡住约 23% 的重复错误。
八、15 个 MCP 工具速查
按用途分四组：
8.1 读
| 工具 | 作用 |
|---|---|
get_summary() | 当前项目浓缩摘要（~500 token） |
get_issue(id) | 取某个 issue 详情和相关 attempts/fixes |
list_events(filter) | 按类型/文件/时间筛选 |
search_events(query) | 全文搜索 |
list_stale() | 列出过时但未删除的记忆 |
get_plan() | 读 plan.md |
8.2 写
| 工具 | 作用 |
|---|---|
log_issue(...) | 记录新问题 |
log_attempt(...) | 记录某次尝试（含 outcome） |
log_fix(...) | 记录最终修复 |
log_decision(...) | 记录架构决策 |
log_note(...) | 自由备注 |
supersede(old_id, new_id) | 标记某条记忆被新的替代（不删旧的） |
edit_plan(content) | 写 plan.md |
8.3 判断
| 工具 | 作用 |
|---|---|
check_context(files, intent) | pre-commit 判断，返回 warning 或 pass |
get_score() | A+ 到 F + token 节省估值 |
8.4 维护
| 工具 | 作用 |
|---|---|
reindex() | 重建派生索引 |
调用都是 AI 自动触发，你不用记。只有check_context是它在你每次准备让 AI 改代码前自动跑。
九、Token 到底能省多少
官方给的数据（我自己用下来也差不多）：
| 访问模式 | Token / session | 工作方式 |
|---|---|---|
| 不用 projectmem（基线） | 5,000 – 20,000+ | AI 每次重读源文件 |
| 通用模式（markdown 注入） | ~2,500 | AI 一次读 3 个小文件 |
| MCP 模式（推荐） | ~800 – 1,500 | AI 先get_summary()，按需取 issue |
pjm wrap（预注入） | 500 – 2,000 | 预生成，token 预算可控 |
省 50-75%的关键是：AI 永远不直接读events.jsonl（那个文件会越来越大），只读工具派生出的小摘要。需要细节时才按 ID 取单条事件。
按 DeepSeek 价格算（输入 ¥1/百万 token），一个活跃项目一天跑 50 次 AI 会话，一个月省下来大概 ¥30-80。Claude Sonnet 价格更贵，省得更多。
十、跨项目 Dashboard：一张屏看所有仓库
v0.2.0 新功能，我挺喜欢：
pjm dashboard终端启动一个只读的跨项目视图：
- 所有
pjm init过的仓库； - 每个仓库的评分（A+ 到 F）、open issues、token 节省；
- 点击钻取到具体项目。
关键设计：
- Serverless by default，纯本地读时聚合，不跑后台服务；
- 加
--serve才临时起个 HTTP 服务器，Ctrl+C 就停； - 每个项目的记忆永远只存在自己的 .projectmem 目录里，dashboard 不集中存储。
对于同时维护七八个项目的人（比如你既写 Java 后端又写 Python 服务又写 Vue 前端），这个视图能让你一眼看出：
- 哪个项目最近踩坑最多；
- 哪个项目缺决策记录（评分低）；
- 上个月在哪个项目上烧了最多 token。
十一、常见坑和解决方案
Q1：pjm命令在 Claude Code 里报 not found
MCP 客户端 spawn 进程时不读 shell PATH。用绝对路径：
where pjm把返回的完整路径填进command。
Q2：MCP 连上了但 AI 不主动记录
需要在CLAUDE.md或项目规则里加一句：
遇到 bug、尝试方案、修复、架构决策时，主动调用 projectmem 记录。准备改代码前先 check_context。
也可以装官方 skill（如果有）。
Q3：events.jsonl 越来越大怎么办
这个文件就是给工具读的，AI 永远不会直接读。体积到几十 MB 也不影响性能，因为有派生索引。真介意可以pjm archive归档老事件。
Q4：怎么把记忆从 mem0 / Letta 迁过来
v0.2.1 计划提供pjm import，支持 mem0 / agentmemory / Letta / Claude session logs。当前可以手动导出 JSON 后用脚本批量log_note。
Q5：多人协作，记忆会冲突吗？
.projectmem/events.jsonl建议提交到 Git（团队共享记忆），.projectmem/index/进.gitignore（派生数据本地重建）。事件只追加 + Git 合并，冲突好解。
Q6：能记录非编码事件吗？比如产品决策
能，log_decision接受任意 tag。可以记产品决策、用户反馈、运营策略，只要和项目有关。
Q7：Python 3.13 兼容吗
官方支持 3.10+，3.13 也能跑。某些依赖（如 numpy 在 3.13 上）可能需要新版本，pip install -U projectmem即可。
Q8：AI 太激进，乱记事件怎么办
pjm config set auto_log off关掉自动记录，只在你明确说"记一下"时记。或者在 CLAUDE.md 里写明："只有 issue/fix 级别的事件才记，不要记录琐碎的语法修改"。
十二、适合谁 / 不适合谁
✅ 适合
- 长期维护一个项目（3 个月以上），AI 会话开了几十上百次；
- 踩过的坑 AI 老重复踩；
- 同时管多个代码库，想看清哪里最烧 token；
- 注重隐私，不想要云端记忆服务；
- 团队协作，想把"为什么这么写"沉淀成项目资产；
- 喜欢 Git、JSONL、纯文本这类"能 grep、能 diff"工具的工程师。
❌ 不适合
- 一次性脚本、demo、throwaway 项目（记忆没价值）；
- 完全不允许本地文件被 AI 工具读取的环境；
- 期待"AI 自动变聪明"而不愿意花一点精力整理事件的人；
- 重度依赖 Letta/MemGPT 那种 agent 框架自带记忆的方案。
⚠️ 注意
- 记忆质量取决于你和 AI 记录的质量，前两周要有意识地"喂"；
- Pre-commit warning 不是强制锁，是提醒——最终决定权在你；
- 不要把密钥、密码、客户数据写进事件里（即使是本地）。
最后总结
projectmem 不解决"AI 不够聪明"的问题，它解决的是**"AI 永远是新人"**的问题。
- Git 告诉你代码改成了什么样；
- projectmem 告诉你为什么这么改、试过什么、什么失败了。
花 10 分钟装上，坚持记录 2 周，你会发现：同样的坑不再踩第二遍，AI session 越来越"懂"你的项目，token 账单肉眼可见下降。这是今年我用过性价比最高的 MCP 之一。
项目地址：GitHub - riponcm/projectmem: Open-source coding agents memory. Records issues, attempts, fixes and decisions, then warns your agent before it repeats an approach that already failed. Native MCP server for Claude Code, Cursor, Antigravity and Codex. 100% local, no cloud, no telemetry. MIT. · GitHub 官方文档：User Guide — Setup, MCP clients, multi-project, cross-project memory — projectmem 论文：[2606.12329] PROJECTMEM: A Local-First, Event-Sourced Memory and Judgment Layer for AI Coding Agents PyPI：projectmem · PyPI
下一篇我准备写"在一个 3 万行 Spring Boot 项目里养 projectmem 30 天，AI 到底少踩了多少坑"，感兴趣的点关注。