Projectmem

🎉 v0.3.4 已发布 — 随着项目不断发展，摘要依然简洁；提交会归档到其修改的代码下；过时警告也不再受时区影响。 查看变更 →

我们不会让 AI 变得更聪明，而是让它积累经验。

编码 Agent 记忆 — 面向 AI 编码 Agent 的本地优先记忆与判断层。每个项目只需一个 MCP 服务。告别每次会话都重新阅读项目。告别重复昨天的错误。

网站 • 指南 • 演示 • 更新日志 • 论文

_{pjm visualize — 项目解决的每个案例、过程中的失败，以及它带来的节省。由 .projectmem/events.jsonl 在本地生成。}

🚀 从这里开始 — 一次只需五分钟

跟着这里的步骤操作，五分钟即可完成。想看演示吗——包括每条命令、命令的准确输出，以及最后的仪表板？ 请查看*完整设置指南**。*

刚开始使用 projectmem，或从 0.1.x / 0.2.x 升级？ 从 0.3.0 开始，一个 MCP 服务即可服务所有项目，因此这是你最后一次进行配置。

1. 安装或更新

pip install -U projectmem

2. 查找已有项目

pjm doctor

它会在代码所在位置查找——~/Developer、~/code、~/projects、你的云文件夹，以及 Windows 上的每个驱动器——并列出尚未注册但已有记忆的项目。若有遗漏，可手动添加：

pjm project register "/Users/you/Developer/repos/ossdrop"

3. 注册项目

pjm doctor --fix

4. 用一份配置让 AI 访问所有项目

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

不需要 --root 或 cwd——这就是它能服务所有项目的原因。各客户端的专属说明（Claude Desktop、Claude Code、Cursor、Antigravity、Codex）请参阅 MCP 集成（推荐）；pjm init 会打印这段配置，并自动填入你的 Python 路径。然后彻底重启客户端——MCP 服务仅会在完全重启时加载。

5. 检查配置

pjm doctor

如果还想让它告知是否有更新版本的 projectmem，可添加 --online——否则 projectmem 不会进行任何网络调用。如果愿意，也可以用 --auto 将检查设为每日一次。

编辑配置后再运行一次。它会标记仍限定为单个仓库的客户端——这是新项目对 Agent 不可见的最常见原因。

全部显示绿色？大功告成。 接下来，每个仓库只需运行一条命令：

pjm init

你的 Agent 会读取项目已有的经验，而不是重新摸索，并记录它发现的内容。消耗更少的 token，不再重复碰壁，记忆还能延续到本次会话之后。

什么是编码 Agent 记忆？

编码 Agent 记忆是构建项目过程中发生事项的持久记录——遇到的问题、尝试过的方法、有效的修复方案和做出的决策——这些内容会被保存下来，以便 AI 编码 Agent 在新会话开始时读取。没有它，每次会话都得从零开始。

projectmem 是为此打造的开源Agent 记忆层。它采用本地优先方式：记忆保存在仓库内普通的 .projectmem/ 目录中，无云端、无需账户，也不进行遥测——它唯一可能进行的网络调用，是你主动启用的更新检查。原生 MCP 服务向 Claude Code、Claude Desktop、Cursor、Antigravity 和 Codex 提供 17 个工具，让你的 Agent 自行读取记忆并记录工作。

与聊天记录记忆工具不同，projectmem 存储的是类型化事件——问题、尝试、修复、决策和笔记——这使它能够实现标志性功能：在你重复本项目中已经失败过的方法之前，发出提交前警告。

pip install projectmem
cd your-project && pjm init

🎬 观看演示

完整屏幕录制教程——在 YouTube 上观看

问题

每次新的 AI 会话都从零开始。Claude、Cursor、Aider——它们都会忘记昨天的决策，重复失败的调试尝试，还会耗费数百万个 token，从原始源文件中重建上下文。

问题不在模型。**问题在架构。**无状态模型需要一个记忆中枢。

解决方案

projectmem 是一个本地优先的记忆与判断层，位于 AI 工具之上。它会记录每次失败的尝试、决策和注意事项，然后将这些经验注入未来的 AI 会话。Git 跟踪改了什么。projectmem 跟踪为什么改、尝试过什么，以及哪些方法失败了。

安装

第一次使用？ → 完整设置指南 将带你完整走过整个流程：安装、连接 Claude Desktop、Claude Code、 Cursor、Codex 或 Antigravity，使用 pjm doctor 检查，并通过仪表板 查看记忆——每一步都附有真实的终端输出。

三条命令，让项目记住一切：

pip install projectmem
cd your-project
pjm init

就是这样。pjm init 会安装三个 git 钩子（提交前警告、提交后分类、合并后跟踪），自动启动实时文件监视器，在可用时继承跨项目记忆，并创建 .projectmem/。从第一分钟起，记录功能就已启用。

标准命令是 projectmem。系统还会安装 pjm 别名，方便快速使用。

✨ 0.3.4 新功能 — 精简的记忆，以及可信的警告

摘要不再无限增长。 笔记有数量上限，但“近期问题”和“决策”会列出所有记录过的内容，因此在较老的项目中，读取记忆比阅读代码还费时。所有未解决的问题仍会显示——最新的 20 条完整显示，较早的问题按 ID 显示；已解决问题最多显示最新的 10 条，决策最多显示最新的 15 条，并各自附上一行说明省略了哪些内容以及在哪里可以找到。在一个有 25 个问题和 60 条决策的测试项目中，摘要从约 2,900 个 token 减少到约 1,100 个。 （#19）

提交会归档到它们修改的代码文件下。 自动捕获会使用 Git 排序中第一个变更路径，这通常是重新生成的 .projectmem/summary.md——因此有效记忆会被标记为过时，真正的文件则丢失了历史记录。现在，归档位置是提交所涉及的源文件，并且已处理删除、重命名、合并和仓库的首次提交。 （#20）

过时警告不再受时区影响。 0.3.3 的加速优化将 Git 的本地时间提交日期与 UTC 事件时间当作文本进行比较：在 UTC 以西，近期的过时记忆从不触发警告；在 UTC 以东，新鲜记忆会立即触发警告。现在，两者都按 UTC 进行比较；已归档到 .projectmem/ 下的事件也不再触发警告，无需重写日志。

指南列出了工具的真实参数。 指南给 precheck_file 和 get_issue 写错了参数名（写成 path 和 id，而工具实际使用 file_path 和 issue_id），还展示了未带必需参数 query 的 search_events，因此 Agent 复制调用时会遇到验证错误。现在有一项测试会检查展示给 Agent 的每个调用是否与工具的实际签名一致。 （#18）

要升级？请在每个项目中运行一次 pjm init。 较早的项目保留了创建时版本附带的 AI_INSTRUCTIONS.md 和 Git 钩子，因此这些内容的修复一直无法应用。现在，pjm init 会同时刷新二者——先前的说明会保留为 AI_INSTRUCTIONS.md.bak，钩子中 projectmem 区块以外的所有自定义内容也都会原样保留。

此外：输错问题 ID 不再导致后续所有命令失效，pjm precheck 不再对 projectmem 自身的文件发出警告，并且现已支持 Python 3.13 和 3.14。

针对 #18 和 #20 的修复由 Rohan Tiwari 贡献，针对 #19 的首个数量上限由 hylin 贡献。#18 和 #19 由 @medium-effort 报告，#20 由 @bigfree 报告。

✨ 0.3.3 新功能 — precheck 不再越来越慢，Windows 全流程可用

pjm precheck 会在每次编辑前运行——说明会告诉 Agent 先调用它——所以它的开销会不断累积。在一个有 1,200 个事件的项目中，它耗时 26 秒，而且每周都变得更慢，因为它会针对每个事件运行一次 git log，来回答有关单个文件的问题。现在，它会对每个不同的文件调用一次，并以引用该文件的最早事件为界。

现在，延迟不再随项目年龄线性增长，而是保持平稳。结果与旧算法的重新实现一致，包括合并提交的情况——但这次改动引入了一个时区错误，已在 0.3.4 中修复。

已退役的决策不会再出现。 supersedes 自 0.1.4 起就已存在，但 Agent 在工作期间实际会读取的两个界面——get_context 和 precheck_file——此前都没有过滤它。你可以退役一项决策，却仍会被告知这项决策。现在两处都会过滤，AI_INSTRUCTIONS.md 也终于说明了如何退役决策，这正是模型以前从未调用它的原因。

桥接文件中会写入你的项目名称，AGENTS.md 也会生成。 一个服务会为所有项目提供服务，因此如果调用没有指定项目，就会被拒绝，而不是猜测项目名称——但此前没有任何内容告诉 Agent 项目名称，所以它只能从错误中得知，然后在每个会话中重试。现在桥接文件中会写入项目名称。它也会写入 AGENTS.md，而不只是 CLAUDE.md，因为 Antigravity 和 Codex 都不会读取后者。

六项 Windows 报告已解决。 Git 钩子使用了 bash shebang，而 Git for Windows 经常无法解析它——无法解析的 shebang 不会跳过钩子，而是会中止提交。内置的二进制路径中的反斜杠被 shell 转义吞掉了。venv 回退路径会查找 bin/，但那里不可能存在这个目录。pjm watch --daemon 的进程无法被发现或停止。还有一个框线字符会导致 pjm init 在 cp1252 控制台上直接崩溃——尽管此时它已创建了所有内容，所以命令既完成了工作，又报告失败。

每个问题都是通过在报告问题的设备上运行 projectmem 修复的——包括 Windows 11，以及三个 MCP 客户端（Antigravity、Claude 和 Codex）——而不是通过阅读代码。问题由 @medium-effort 报告；他也贡献了 0.3.2 的 Windows 守护进程支持。

✨ 0.3.2 新功能 — 正式支持 Windows

pjm watch --daemon 在 Windows 上会因 AttributeError: module 'os' has no attribute 'fork' 崩溃。现在它会生成一个分离的工作进程，而不是执行 fork，因此后台监视在所有平台上都能正常工作。

修复这个问题时，还发现了一个隐藏在它背后的第二个错误。程序通过 os.kill(pid, 0) 检查进程是否存活——这是无法移植的 POSIX 惯用写法，因为在 Windows 上，os.kill 会调用 TerminateProcess，而信号 0 根本不能用于检查。监视器在 Windows 上无法被发现或停止，而且每次运行 pjm watch --daemon 都会泄漏一个进程。两个问题现已修复。

Windows 守护进程支持由 @medium-effort 贡献（#13）。

pjm doctor 还新增了两项功能。现在，它会提醒你在编辑 AI 客户端的配置前先退出客户端——这些文件也保存应用自身的偏好设置，因此运行中的客户端可能会在退出时重写整个文件，恢复你刚删除的 --root。它还会记住上次检查到的内容，因此，如果一个原本干净的配置再次被固定，就会将其标记为回退，而不会让人觉得 doctor 时好时坏。仅操作本地文件；不会有任何内容离开你的设备。

✨ 0.3.1 新功能 — 了解何时升级

现在，两个仪表板都会显示生成页面的版本，并在旁边提供检查更新链接。只有点击后，页面才会发起请求——PyPI 的公开 JSON 会直接从浏览器获取，不会发送任何有关你设备的信息。在命令行中，pjm doctor --online 会检查一次，pjm doctor --auto 则会记住每天检查；除非你主动启用，否则两者都处于关闭状态。

✨ 0.3.0 新功能 — 一个服务，多个项目

此前，MCP 配置只能对应一个仓库：十一个项目就意味着要配置十一个服务条目，并重启十一次。**0.3.0 可以通过单个服务为所有已注册项目提供服务。**只需粘贴一次配置；此后你通过 pjm init 初始化的每个仓库都可以从中访问。

pjm project list          # what this server can reach
pjm project use ossdrop   # the default when a call names no project

log_issue(summary="stars come back empty", project="ossdrop")
→ Logged issue #0019 → ossdrop: stars come back empty

每次写入都会标明目标项目——在共享服务中，危险的故障不是“什么都不能用”，而是写入成功，却写进了错误的仓库。现有的 --root 配置无需改动即可继续使用；现在，固定到特定仓库的服务即使收到请求，也会拒绝写入其他位置。

0.3.0 的其他更新：

• **修复：全新安装时 MCP 服务无法运行。**mcp 2.0 重命名了 FastMCP，导致旧的导入路径报错——自 2026-07-28 起，每次新的 pip install projectmem 都会安装一个在导入时就会崩溃的服务。感谢 @VIVAAN-DHAWAN 发现并修复此问题。
• **安全：pjm visualize 中存在存储型 XSS 漏洞。**事件摘要未经转义便写入 DOM，而 git 提交消息会成为事件摘要——因此，你拉取的分支中若有恶意构造的提交，就可能在仪表板中运行脚本。现在，所有输出位置都会进行转义。
• 重建后的仪表板——可分享的记忆卡片、包含完整问题 → 尝试 → 修复链路的案例文件、工作量树状图、逐文件档案，以及会从上次离开的位置打开的全局视图。

注册表会自动迁移：首次读取时，0.2.x 的路径列表会自动转换，并在旁边保留一个 .bak 文件。

✨ 0.2.0 新功能 — 工作区版本

0.1.6 让你可以查看一个项目的记忆。0.2.0 将这一功能扩展到整个工作区，并弥合了发生了什么（记忆）与代码是什么（结构）之间的差距。

• 🌐 全局仪表板 — pjm dashboard 用一个页面展示所有已运行 pjm init 的项目：记录的问题总数、已确认的修复、避免的死胡同、节省的令牌数、每个项目的评分，以及“需要关注”列表。点击任意卡片即可打开该仓库专属的仪表板，每次都会重新生成。这是一个全局视图，而非全局存储——每个仓库的 .projectmem/ 只在读取时聚合，绝不会离开其所在文件夹。默认以无服务器方式运行（静态快照）；添加 --serve 即可启动一个轻量、临时的实时服务，点击“刷新”按钮即可重新读取文件——没有后台守护进程，按 Ctrl+C 即可停止。
• 🧬 结构与关系 — pjm map --build（在 pjm init 时自动运行）会遍历代码库，并为 Python 解析导入关系，生成真实的依赖图。项目地图的图谱和流程视图现在会呈现实际文件及它们之间的导入边。缓存（structure.json）由代码生成，已加入 Git 忽略规则，绝不会提交——代码只会被读取。
• 🔥 结构上的失败热度 （两者结合） — 纯代码绘图工具和纯记忆工具都无法绘制的视图：反复尝试失败的文件会亮起红色，并直接叠加在真实的导入图上。结构来自代码，热度来自记忆，它们只在渲染器中相遇。
• 🗂️ plan.md — 新增的可编辑意图文件：想法和计划，也就是你打算做的事——有意将其与事件日志区分开来。events.jsonl → summary.md 记录已发生的事；plan.md 记录你的计划。AI 会在会话开始时读取它，并直接编辑；计划永远不会变成事件。pjm plan / pjm plan "idea" / MCP get_plan()。

所有内容都 100% 保留在本地——全局仪表板是读取时生成的聚合视图，绝不是存放代码历史的中央蜜罐。

全局仪表板 — 在一个视图中查看所有已运行 pjm init 的项目：评分、问题、节省情况和“需要关注”列表，均在读取时聚合。点击每张卡片即可打开该仓库专属的仪表板。

项目的记忆也可以观看，还能分享。

• 🎬 Showoff — 一个包含三个动画场景的仪表板标签页，所有内容均根据真实事件日志渲染：故事回放（观看项目历史逐节点自行构建）、轨道（文件围绕项目运行，事件围绕所属文件运行）和 宇宙（项目化作旋转的星系——每颗明亮的星星都代表一个真实的问题、尝试、修复或决策；点击即可查看完整详情）。
• ⏺ 内置录制器 — 按下 REC（10–60 s），Showoff 就会下载动画的 .webm 片段，100% 在本地渲染，并带有“made with projectmem”徽章。你的调试故事，随时可以发推文或在站会上分享。
• 🗺️ 流程 — 项目地图的默认视图：分层流程图展示 PROJECT → DIRECTORIES → FILES → WHAT HAPPENED → MEMORY。反复失败的文件会沿着路径发出红光，每个文件都会显示结果标签，所有内容最终汇入 events.jsonl 圆柱体。只需点击一下即可切换到树状图或图形视图。
• 🧵 时间脊柱 — 时间线的默认视图：可滚动的实时轴，问题向左分支（问题、失败的尝试），知识向右分支（修复、决策、笔记）。将鼠标悬停在任意卡片上，整条问题线索都会亮起。经典列表仍保留为“详情”。

Showoff · 宇宙 — 每颗明亮的星星都是项目记忆中的真实事件

项目地图 · 流程 — 逐个文件展示发生的事情，并汇入只追加的记忆

时间线 · 时间脊柱 — 问题在左，知识在右，实时沿中间向下展开

你一定会喜欢它的原因

• 提交前警告 — 如果你即将重复失败的方法、修改频繁变动的文件，或触及尚未解决的问题，pjm precheck 会在你提交之前发出警告。它依据的是本项目自身记录的失败，因此需要底层的记忆层支持。现在，警告会列出具体的失败尝试（“这里已经失败过的做法：✗ tried CSS contain:layout”），而 pjm precheck --snooze 2h 可以让它安静一会儿——稍后提醒也会记录在案，因此即使是静默处理也有审计记录。
• 过时记忆检测 (0.1.4 新增) — projectmem 绝不会删除记忆。每条引用文件的决策都会与该文件的 git 历史交叉核对——文件发生变化后，这条记忆会被标记（“早于 auth.py 的 7 次提交——请确认或取而代之”），再由人工决定。使用 pjm decision "new way" --supersedes <id> 即可妥善弃用它：旧事件会永久保留在日志中，并带有标记。
• 会话开始简报 (0.1.4 新增) — pjm brief 用一个屏幕回答“我上次做到哪儿了？”，内容包括当前警告、可能过时的记忆、未解决的问题、近期决策、技术栈注意事项，以及附带周环比变化的预防评分。
• 适用于不支持 MCP 的 Agent 的记忆 (0.1.4 新增) — pjm export --claude-md 会将当前决策、注意事项和“不要重试——这些方法已经失败”的列表编入 CLAUDE.md（或 .cursorrules）的标记区块。Copilot、普通 Claude，以及任何会读取该文件的 Agent，都能继承你项目的判断。
• 智能上下文注入 — pjm wrap claude（或 cursor/aider）会在会话开始前，将符合 Token 预算的记忆区块注入 AI。你的 AI 从一开始就经验丰富，而非一片空白。
• 预估 ROI 评分 — pjm score 会输出字母评级（A+ → F），以及该工具估算的调试时间节省量、避免消耗的 Token 数和节省金额。支持适用于 CI 的 JSON 输出和供 README 使用的 shields.io 徽章。
• 跨项目记忆 — 在一个仓库中学到的经验会一直伴随你。库的注意事项、决策和模式保存在 ~/.projectmem/global/ 中，新项目会继承这些内容。对于带有清单文件（pyproject.toml、requirements.txt、package.json、Cargo.toml、go.mod）的项目，只会提供与其技术栈相关的经验。
• 实时文件监视器 — 后台守护进程会在两次提交之间，检测同一文件的快速编辑（调试会话）。支持电池状态感知和 gitignore 规则感知，并由 pjm init 自动启动。
• 原生 MCP 服务 — 可接入 Claude Desktop、Cursor、Antigravity、Codex，以及任何兼容 MCP 的工具。17 个原生工具会强制 AI 读取上下文、检查文件中是否存在已知失败、读取你的 plan.md，并自动记录工作。首次发布时已在这四个客户端中完成端到端验证；0.3.3 验收套件已在 Antigravity、Claude 和 Codex 中重新运行。
• 交互式仪表板 (0.1.6 扩展) — pjm visualize 会打开包含六个标签页的本地仪表板：概览、故事地图（带折叠／聚焦控件的失败热力图）、ROI 仪表板、项目地图（Flow / 树形 / 图形视图，现在基于真实代码结构）、时间线（Time Spine / 详情），以及 Showoff——带内置视频录制器的动画故事场景。
• 一个 MCP 服务管理所有项目 (0.3.0 新增) — 只需配置一次客户端，无需为每个仓库分别配置。调用时可指定项目（project="ossdrop"），也可回退到当前项目；每次写入都会报告目标仓库，固定使用 --root 的服务则会拒绝写入其目录之外。现有的单项目配置不受影响。
• 全局仪表板 (0.2.0 新增) — pjm dashboard 提供跨项目视图，涵盖你运行过 pjm init 的所有仓库：评级、问题、节省情况，以及按项目查看详情。它是全局视图，绝非全局存储——每个仓库的记忆只会在读取时汇总，并且绝不会离开其所在文件夹。默认无需服务端；添加 --serve 可启动临时实时服务（按 Ctrl+C 停止）。
• 代码结构 + 判断 (0.2.0 新增) — pjm map --build 会读取你的代码库并构建真实的导入关系图，项目地图则会将事件日志中的失败热度叠加其上：反复出错的文件会在实际关联它们的结构上方发出红光。结构缓存由代码生成，并已加入 gitignore——绝不会提交。
• 意图与记忆分开管理 (0.2.0 新增) — plan.md 用于记录想法和计划（你打算做什么），并与只追加的事件日志（已经发生的事）刻意分开。使用 pjm plan 或 MCP get_plan()；AI 会直接编辑计划，计划永远不会变成事件。
• 100% 本地运行 — 无云端、无遥测、无需账号。你的代码、你的记忆、你的设备。

对比

_{✅ 支持 · 🟡 部分支持 · ❌ 项目自身文档中未提及 · ? 未记录。此快照于 2026-10-02 根据各项目的 README、文档和更新日志整理；比较的是设计能力，而非基准测试结果。欢迎指正 — 提交 issue。}

_{没有数据库，也无需持续运行任何东西：MCP 服务是由 AI 客户端启动的 stdio 子进程，其他一切都是普通文件。唯一的服务是可选的 pjm dashboard --serve，这是一个临时的本地查看器，可通过 Ctrl+C 启动和停止。}

🚧 即将推出

• 导入现有记忆 — pjm import（计划在 0.4.0 推出）将把 mem0、agentmemory、Letta 和 Claude 会话日志中的历史记录迁移到 projectmem。它只会映射到核心事件类型 — 问题、尝试、修复、决策、备注 — 让有用信息得以导入，同时避免带入其他工具的杂项。你的判断历史也会随之迁移。

希望支持某种来源？提交 issue，告诉我们你想从哪里迁移。

AI 如何读取你的记忆（Token 效率）

架构围绕一条规则构建：AI 读取精简、提炼后的文件。工具根据庞大的原始日志生成这些文件。

估算值，并非基准测试结果。 根据 0.3.4 版本的摘要测算：新项目约需 250 个 token；包含 25 个问题和 60 个决策的项目约需 1,100 个 token；未解决的问题越多，所需 token 越多。

AI 绝不会直接读取 events.jsonl。 该文件供工具使用（pjm score、pjm context、pjm wrap）。工具会将原始日志提炼为紧凑、便于 AI 阅读的摘要。

一个服务，多个项目

从 0.3.0 开始，一个 MCP 服务即可为你注册的所有项目提供服务。只需粘贴一次配置，之后每个你运行 pjm init 的代码仓库都能通过它访问——无需添加第二项配置，也无需重启。

pjm project list          # what this server can reach
pjm project use ossdrop   # the default when a call names no project
pjm project alias ossdrop od

你的 Agent 会为每次调用选择项目：

log_issue(summary="stars come back empty", project="ossdrop")
→ Logged issue #0019 → ossdrop: stars come back empty

每次写入都会说明写入到了哪里。 这条回显正是关键：在单项目设置中，配置错误的服务只会失败；但共享服务可能会在错误的代码仓库中成功执行，从而同时污染两份审计记录。如果回复中的项目名称不是你想要的项目，请立即停止。

调用的路由优先级从高到低如下：

客户端根目录接入后，将有意排在当前项目之前：根目录代表你现在所在的位置，而当前项目是你几天前设置的模式。两者不一致时，过时的那个就是错误答案。

单仓库设置不受影响——pjm init --mcp-config-single 仍会输出固定配置，现有的 --root 配置项也会像以前一样正常工作。

MCP 集成（推荐）

适用于： Claude Desktop、Cursor、Antigravity、Codex，以及任何原生支持 MCP 的工具。MCP 服务会强制 AI 读取记忆，并自动记录每项操作。

从 0.3.0 开始，只需配置一次，而非每个代码仓库配置一次。 下面的配置块不含 --root：服务会为你注册的所有项目提供服务，并解析每次调用对应的项目。粘贴配置后，之后每个你运行 pjm init 的代码仓库都能访问——无需添加第二项配置，也无需重启。

"mcpServers": {
  "projectmem": {
    "command": "/opt/anaconda3/bin/python",
    "args": ["-m", "projectmem.mcp_server"]
  }
}

已有项目，正在升级？ 注册表只会记录自注册表推出（0.2.0）以来你运行过 pjm init 的项目，因此更早的项目不会被记录——而全局模式会通过注册表进行路由。运行一条命令即可解决：

pjm doctor          # what's unregistered, what's stale, what's still pinned
pjm doctor --fix    # register what it found

它会在代码实际存放的位置查找——~/Developer、~/code、~/src、~/projects 等目录，以及 Windows 上的所有固定磁盘；项目常常位于 D:\ 和 E:\ 下，不一定在主目录中。要指定具体位置：

pjm doctor --path ~/work --path /Volumes/ssd --fix
pjm project scan D:\ E:\ --depth 3     # the same walk, without the other checks

只有运行该命令后才会开始扫描；没有 --fix 则不会写入任何内容。升级后，CLI 只会提示一次 pjm doctor——wheel 安装无法运行代码，因此只有你输入的第一条命令能显示这条提示。

注册了一个项目时，配置就全部完成了——调用只有一个可去的位置。注册了多个项目时，你的 AI 可以传入 project="<name>"，也可以通过 pjm project use <name> 设置默认项目。pjm init 会输出此配置块，并预先填入你自己的 Python 路径。

从 0.2.x 升级？ 现有的 --root 配置项仍会像以前一样正常工作；现在，固定到某个根目录的服务即使收到请求，也会拒绝在自身代码仓库之外写入。想要用一个服务管理所有项目时，请替换为上面的配置块。

3 分钟工作流（让 AI 为你完成设置）

1. 安装并初始化。 pip install projectmem，然后进入你的项目目录并运行 pjm init——或者直接让 AI 运行。
2. 让 AI 为你设置 projectmem MCP 服务——它可以自行编辑客户端的配置文件。（它需要获得相应权限：使用 Auto / accept-edits 模式，或在提示时批准文件编辑。如果你更愿意手动粘贴，下面各部分列出了每个客户端对应的准确配置。）
3. 重启 AI 工具，让 MCP 服务加载，然后使用以下提示词开始会话：

Hi — I use projectmem as this project's memory. Before anything else,
call get_instructions(), then get_summary(), then get_project_map() to
load what we already know. As we work, log issues, attempts
(failed/worked), fixes, decisions, and notes with the projectmem tools,
and call precheck_file(file_path) before you edit a file. Ideas and plans go
in plan.md via get_plan() — never as events.

严格来说，这条提示词是可选的——正确安装 MCP 服务后，AI 会自行发现记忆。不过，说明这一点能显著提高记录的一致性，因此我们建议使用。

• 对每个项目重复此操作： pjm init + 相同的启动提示词。
• 关闭窗口后回来？ 打开时用一句话提醒——“提醒：我们在这里使用 projectmem 作为记忆。”——整个设置就会从你上次离开的地方继续。

更愿意手动配置？下面列出了每个客户端对应的准确且经过验证的配置。

Claude Desktop

最简单的方法——从界面打开配置：

• macOS： Claude 菜单 → Settings… → Developer 标签页 → Local MCP servers → Edit Config。
• Windows / Linux： 预计路径相同（Settings → Developer → Edit Config）——如果你的平台路径不同，请提交 issue，我们会更新此处。

如果你更喜欢直接打开文件：macOS 上为 ~/Library/Application Support/Claude/claude_desktop_config.json，Windows 上为 %APPDATA%\Claude\claude_desktop_config.json，Linux 上为 ~/.config/Claude/claude_desktop_config.json（如果你移动过配置目录，也可能是 $XDG_CONFIG_HOME/Claude/）。pjm init 会打印适用于当前机器的路径。

粘贴以下代码块：

"mcpServers": {
  "projectmem": {
    "command": "/opt/anaconda3/bin/python",
    "args": ["-m", "projectmem.mcp_server"]
  }
}

关于此代码块，有两点需要注意：

• 请使用 python 的绝对路径（例如 /opt/anaconda3/bin/python，也可以运行 which python 查找路径）。Claude Desktop 子进程不会继承 shell 的 PATH，因此直接使用 "python" 往往会失败。
• 现在不再需要 cwd 字段，而且以前也不能依赖它。 当前版本的 Claude Desktop（使用 Epitaxy / Cowork 工作区系统）会静默忽略 cwd——服务最终会以 cwd=/ 运行，因而无法找到 .projectmem/。这就是早期版本需要 --root 的原因。注册表取代了它：服务按名称查找项目，而不是根据自身运行位置查找项目。

"mcpServers": {
  "projectmem": {
    "command": "/opt/anaconda3/bin/python",
    "args": [
      "-m", "projectmem.mcp_server",
      "--root", "/absolute/path/to/your/project"
    ]
  }
}

然后**完全退出 Claude Desktop（Mac 上按 Cmd+Q）**并重新打开——MCP 服务只会在冷启动时初始化。

Cursor

注册 MCP 服务有两种方式——选择适合你工作流的方式：

1. 全局注册（推荐）： 在 Cursor 菜单中依次选择 → Settings… → 左侧边栏中的 Tools & MCPs → Installed MCP Servers → Add Custom MCP。粘贴下面的 JSON。
2. 按项目注册： 将 JSON 放入 <project-root>/.cursor/mcp.json——仅在打开该项目时生效。

{
  "mcpServers": {
    "projectmem": {
      "command": "/opt/anaconda3/bin/python",
      "args": ["-m", "projectmem.mcp_server"]
    }
  }
}

关于此配置块，有两点需要注意（与 Claude Desktop 的注意事项相同）：

• 使用 python 的绝对路径（运行 which python 查找路径）。Cursor 子进程无法可靠地继承 shell 的 PATH。
• 无需设置 cwd 字段。 与 Claude Desktop 一样，Cursor 会静默忽略该字段：服务最终会以 cwd=~ 运行。从 0.3.0 开始，这不再重要，因为项目是按名称在注册表中查找的，而不是根据服务的运行位置查找。

全局注册后，一个条目就适用于所有项目。如果你希望服务仅在打开对应仓库时存在，也可以继续使用按项目配置的 .cursor/mcp.json——在其中的 args 添加 "--root", "/absolute/path/to/your/project"，即可指定项目路径。

然后**彻底退出 Cursor（Mac 上按 Cmd+Q）**并重新打开。projectmem 还会像 git 查找 .git/ 一样，从 CWD 开始向上遍历，自动发现 .projectmem/，并遵循 PROJECTMEM_ROOT 和 --root <path> CLI 参数。

Antigravity

Antigravity（Google 的 AI IDE）支持标准 MCP。

最简单的方法——通过 UI 打开配置：

1. 打开 Agent 窗口（右侧的聊天面板）。
2. 点击面板标题栏中的 ⋯ Additional Options 按钮。
3. 选择 MCP Servers → Manage MCP Servers → Add new（或 Edit Config）。

如果你更喜欢直接编辑，原始文件位于 ~/.gemini/antigravity/mcp_config.json。

粘贴此配置块：

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

Antigravity 会遵循 cwd 字段，因此添加 "cwd": "/absolute/path/to/your/project" 即可生效，但这会将服务绑定到单个仓库。省略该字段，同一条配置就能服务于所有已注册的项目。

然后**彻底退出 Antigravity（Mac 上按 Cmd+Q）**并重新打开——MCP 服务仅在冷启动时初始化。全部 17 个 projectmem 工具的注册方式与 Claude Desktop / Cursor 相同。

Codex

Codex 将 MCP 配置以 TOML（而非 JSON）格式存储在 ~/.codex/config.toml 中。虽然 UI 中有 Settings → MCP Servers → Add MCP Server 表单，但在跨客户端验证时，表单的 Save 按钮无法可靠地保存配置——直接编辑文件更快、更可靠。

最简单的方法——直接编辑 ~/.codex/config.toml：

追加此配置块（保留任何现有配置）：

[mcp_servers.projectmem]
command = "/opt/anaconda3/bin/python"
args = ["-m", "projectmem.mcp_server"]

关于此配置块，有三点需要注意：

• 使用 python 的绝对路径（运行 which python 查找路径）。Codex 子进程无法可靠地继承 shell 的 PATH。
• 不再需要 --root 或 cwd。 早期版本会传入 --root 以加强防护（cwd 字段似乎在 Codex 中有效，这一点与 Claude Desktop 和 Cursor 不同）。从 0.3.0 开始，注册表已使两者都不再必要——只有在想将此服务限定于单个仓库时，才在 args 中添加 "--root", "/absolute/path/to/your/project"。
• 将推理力度设为 medium 或更高。 推理力度较低时，Codex 会跳过会话启动三项中的 get_instructions，可能导致 AI 遗漏 Setup Mode 工作流规则。设为 Medium 或更高时，会自动遵循完整的三项内容。

验证 TOML：

python -c "import tomllib; tomllib.load(open('/Users/<you>/.codex/config.toml','rb')); print('OK')"

应输出 OK。如果没有，解析器会指出出错的行。

然后彻底退出 Codex（Mac 上按 Cmd+Q）并重新打开。 与其他 MCP 客户端一样，必须冷启动。Codex MCP 服务会在聊天会话中首次调用工具时才延迟启动——如果重新打开后没有在 ps aux 中看到进程，向 Codex 聊天发送任意消息后再检查。

推理力度说明： Codex 的模式选择器位于聊天输入框底部。将其设为 medium（而非 low），以启用完整的会话启动三项行为。设置后，该选项会按会话保留。

首次运行权限提示

首次在任何支持 MCP 的客户端（Claude Desktop、Cursor、Antigravity、Codex）中使用时，你的 AI 会在每次调用 projectmem 工具前请求权限。这是符合预期的安全行为——MCP 客户端要求用户明确同意每个新工具。每个工具只需批准一次，该会话期间就不会再次出现提示。

其他 MCP 工具

任何兼容 MCP 的客户端都可以使用——将你的工具指向 python -m projectmem.mcp_server，并将 cwd 设为项目根目录，或依靠向上遍历父目录自动发现。

暴露的 MCP 工具

你的 AI 可以调用全部 17 个工具。每个仓库工具都接受可选的 project 参数——参见一个服务，多个项目：

读取类（12 个工具）：

写入类（5 个工具）：

CLI 参考

核心记忆

智能层

项目（全局 MCP）

可视化与实用工具

使用任意日志记录命令时，可通过 --at "file.py:42" 附加精确的位置元数据。

plan.md — 意图，与记忆分开保存

pjm init 会生成 .projectmem/plan.md：以纯 Markdown 记录你的想法和计划——你打算做什么（想法 · 当前计划 · 接下来 · 以后 · 已完成）。这是唯一一个刻意不作为事件日志的文件：

• events.jsonl → summary.md 记录发生过的事情（只追加，绝不重写）。
• plan.md 记录你打算做的事情——由你（或 AI）直接编辑，就像 PROJECT_MAP.md 一样。

AI 会在会话开始时通过 get_plan() 读取此文件，并就地更新：添加想法、勾选已完成的事项、将已完成的工作移到已完成。计划永远不会被记录为事件，因此意图不会混入记忆的审计记录。pjm plan 会打印计划；pjm plan "auto-batch the exporter" 会追加一条想法。该文件会提交到仓库（不会被 git 忽略），让团队共享计划。

示例：提交前警告的实际效果

$ git commit -m "switch auth to JWT"

projectmem: Pre-Commit Check
─────────────────────────────────────────────
  src/auth/middleware.py
    WARN  What already failed here (2 attempts):
           ✗ tried switching to JWT middleware (2d ago)
           ✗ patched session timeout to 60min (5d ago)
    WARN  HIGH CHURN: 5 changes in last 30 days
    WARN  1 possibly-stale memory cites this file
           decision [evt_9db5a3f8…] "auth uses session
           cookies, 30min timeout" — predates 7 commits
           Confirm it still holds, or retire it:
           pjm decision "..." --supersedes <id>
─────────────────────────────────────────────
3 warning(s). Review before committing.

重构冲刺期间想让它安静些？运行 pjm precheck --snooze 2h——警告会暂停，暂停操作本身会被记录，每次提交都会显示一行暗色文字，确保不会把沉默误认为检查通过。

隐私与安全

默认情况下，projectmem 会提交提炼后的文件（summary.md、PROJECT_MAP.md、AI_INSTRUCTIONS.md、issues/），并通过 gitignore 忽略原始日志和运行时文件（events.jsonl、watch.pid、watch.log）。这意味着队友的 AI 会自动继承团队知识——只需 git clone，AI 就能了解团队学到的内容。

想要完全隐私？ 在 .gitignore 中添加一行 .projectmem/。没有任何内容会离开你的机器。

完整的安全策略和威胁模型：SECURITY.md · 隐私与安全指南

设计原则

• 本地优先——没有云服务、没有遥测，也不会发起网络请求，除非你启用更新检查。你的数据永远不会离开你的机器。
• 项目范围限定——记忆保存在仓库中。代码迁移时，记忆也会随之迁移。
• 不绑定 AI 工具——可通过 MCP 原生使用，也可通过 Markdown 指令通用使用。适用于任何 AI 工具和任何工作流。

构建所用技术

projectmem 站在以下优秀开源项目的肩膀上：

• Typer — 让 pjm 用起来得心应手的命令行框架
• Model Context Protocol — Anthropic 制定的开放规范，让 AI Agent 能够与本地工具对话
• watchdog — 跨平台文件系统事件监控（pjm watch 的核心）
• D3.js — pjm visualize 中的交互式可视化

研究与引用

projectmem 在一篇同行可读的研究论文中有详细介绍：

PROJECTMEM：面向 AI 编码 Agent 的本地优先、事件溯源式记忆与判断层 Ripon Chandra Malo、Tong Qiu — 犹他大学 arXiv:2606.12329 · cs.AI

这篇论文提出了 记忆即治理（Memory-as-Governance） 的理念——记忆不只是回答 Agent 的问题，还会影响其下一步行动——并介绍了该项目的设计、确定性的提交前判断关卡、与 12 种当代记忆系统的能力对比，以及一项历时两个月、涵盖 10 个真实项目和 207 个事件的自用研究。

如果 projectmem 对你的研究或写作有所帮助，请引用：

@misc{malo2026projectmem,
  title         = {PROJECTMEM: A Local-First, Event-Sourced Memory and
                   Judgment Layer for AI Coding Agents},
  author        = {Malo, Ripon Chandra and Qiu, Tong},
  year          = {2026},
  eprint        = {2606.12329},
  archivePrefix = {arXiv},
  primaryClass  = {cs.AI},
  url           = {https://arxiv.org/abs/2606.12329}
}

许可证

MIT — 永久免费，可用于个人、商业和企业用途。

帮助我们触达更多开发者

我们不需要钱，需要的是你。

projectmem 由一位开发者发起，如今正由开源社区的贡献者共同塑造。每一个星标、每一次分享和每一份贡献，都有助于项目延续并不断发展。

• 为仓库加星 — 只需点击一下，就能大幅提升项目的曝光度
• 在 X / LinkedIn 上分享 — 告诉其他开发者，他们不必再付费让 AI 重新学习自己的代码库
• 提交问题 — 可以是 Bug、功能请求，也可以只是反馈
• 贡献代码 — 欢迎提交 PR；对于大型改动，请先提交问题
• 在工作中或商业产品中使用 projectmem？ 请联系 [email protected]，让我们知道谁在使用它。它是免费的——我们只是很乐意听到相关消息。

星标和分享比金钱更重要——但如果你真的想支持： 在 GitHub 上赞助 →