projectmem（pmem）

中文 | English

零依赖的项目记忆编译器——让 AI 编程 agent 跨会话记住你的项目：做过什么、定了什么、踩过什么坑，代码一变记忆自动变旧。

Zero-dependency project memory compiler for AI coding agents. Memory that expires by git, carries receipts, runs assertions, and shows its own ROI.

一个 js 文件 · 0 依赖 · Node ≥ 20 · Windows/macOS/Linux · 中文友好

为什么

每个 AI 编程 agent 都有同一个病：新会话失忆。你要重新粘贴项目背景；agent 自带的 CLAUDE.md / MEMORY.md 像便利贴——只增不减、搜不了、过期了也不知道。

现有方案（agentmemory、claude-mem 等）验证了需求，但它们依赖重（固定版本二进制引擎 / Bun+uv+Chroma）、原生 Windows 是二等公民、数据进 SQLite 黑盒。

Related MCP server: gitmem

核心理念：记忆是编译产物，不是笔记仓库

五个机制在 GitHub 上逐条查新（2026-09，详见 docs/feasibility-zh.md 附录 B）：依赖驱动失效仅 1 个 0★ 实验仓库撞过方向，其余为 0 结果。

快速开始

Windows：下载/克隆仓库 → 双击 install.cmd → 完事。（没有 Node 也没关系，脚本会指路）

任何系统（推荐）：

npx projectmem demo    # 30 秒看懂完整闭环（临时目录，看完即删）
node pmem.js setup     # 或装成全局命令（从 GitHub 克隆后）

npx projectmem <命令> 免安装直接用；装成全局命令后前缀省略。

极简党：不装也行，就地用——

node pmem.js init
node pmem.js add decision "本项目零依赖，不许引入 npm 运行时依赖" --assert no-deps --file package.json
node pmem.js query 零依赖

先看效果再动手：node pmem.js demo——在临时目录自动跑一遍完整闭环（带证据写入 → 检索 → 代码一变记忆自动变旧 → 复核复活 → 断言当场红牌），每一幕都是真实命令的真实输出，看完可整个删掉。

第一条记忆就带上了完整范式：证据（自动记录 commit + 依赖文件）、失效源（package.json 一变它就变旧）、断言（谁真装了依赖，pmem check 当场红牌）。

想要"全自动"？两步做完上面的事

1. 把 pmem agent-instructions 输出的约定块贴进 CLAUDE.md / AGENTS.md——从此 agent 每次会话开始自动读记忆、过程中自动记决策/进度/坑、结束前自动查失效；

2. 把 pmem setup 打印的 SessionStart 钩子粘进 agent 的 settings.json——即使 agent 偷懒，会话启动也会强制注入记忆（静默跑失效扫描 + 断言 + 按预算注入）。

命令总览

接进你的 agent

MCP（Claude Code / ZCode / Cursor 等通用，server 以启动时的工作目录为项目根）：

# Claude Code
claude mcp add projectmem -- node /path/to/pmem.js mcp

// 其他客户端的 mcpServers 配置
{ "projectmem": { "command": "node", "args": ["/path/to/pmem.js", "mcp"] } }

工具集：pmem_add（带证据写入）、pmem_query（检索）、pmem_inject（预算注入）、pmem_stale（失效扫描）、pmem_check（断言）、pmem_show、pmem_roi。

会话启动自动注入（以 Claude Code hooks 为例，加进 settings.json；或直接跑 pmem setup 让它帮你生成）：

{
  "hooks": {
    "SessionStart": [{ "hooks": [{ "type": "command", "command": "node /path/to/pmem.js hook session-start" }] }]
  }
}

pmem hook session-start 一段输出做完三件事：静默失效扫描（git 驱动）→ 静默断言检查 → 按 1500 token 预算注入记忆，末尾附提醒行。

手动接入：pmem export 把记忆编译成紧凑的 Markdown 块（按类型分组、保状态标记、去元数据），重定向进你的 CLAUDE.md / AGENTS.md 即可：pmem export >> AGENTS.md。

CI 卡口：pmem check 退出码非 0 即失败——决策被违反或记忆过期，构建直接红。

安全

记忆要进 git、可能推上 GitHub——所以安全不是可选项，是默认行为：

• 密钥防泄漏（写入即脱敏，默认开启）：GitHub/OpenAI/AWS/Slack/Google 的 token、JWT、私钥块、password=… 类赋值，写入前自动替换为 [REDACTED:<类型>]，原值不落盘。宁可漏存，不可泄密。

• 完整性哈希链：事件日志每条带 SHA-256 链式哈希，pmem security verify 可检测历史记录被篡改（谁改过、第几行）。

• 注入检测：pmem security scan 会标记疑似提示注入的记忆（"ignore previous instructions" 类），报告不阻断。

• 路径围栏：登记文件依赖越出项目根（../、绝对路径外逃）直接拒绝。

• CI 卡口：pmem security scan（有发现退出码 1）与 pmem check、pmem security verify 都可挂 CI。

存储布局（全部可提交进 git）

.pmem/
├── events.jsonl   事件日志（append-only 审计流：add/fresh/archive/stale/inject/check）
├── index.json     机器态（原子写）
└── MEMORY.md      人读投影（自动重绘，勿手改）

• 记忆数据在你手里：纯文本、可 diff、可备份、可跨机器同步。

• 设计取舍：刻意不用 SQLite / 向量库。目标规模是单项目 ≤ 2000 条，纯 JSON + BM25-lite 完全够，换来零依赖、零编译、零黑盒。超了再升级（见路线图）。

与现成项目对比

竞品 star 数截至 2026-10-09（GitHub API 实查）。

路线图

• ✅ P0：单文件 CLI + JSONL 事件日志 + 证据链 + 中文检索

• ✅ P1：git 依赖失效扫描 + 断言 + 预算注入 + MCP stdio server

• 🔶 P2（大半完成）：命中率遥测、ROI 账本、SessionStart 自动注入钩子（hook session-start）、agent 自动记忆约定、一键安装（setup / install.cmd）、闭环演示（demo）、CLAUDE.md 导出（export）已上线；会话转录自动摘要抓取进行中

• ⬜ P3：本地向量检索（openvino/MiniLM）、LLM 记忆润色（可选层）、4 层记忆分层

开发

npm test        # node --test test/（含 MCP stdio 往返测试）

调研、查新与可行性论证全文：docs/feasibility-zh.md。

反馈与共建

• 报 bug / 提需求：Issues（模板会引导你贴诊断信息；先跑 pmem security scan 确认不带密钥）

• 用法讨论 / 晒你的玩法：Discussions

• 觉得省下了重新交代背景的时间，就点个 ⭐——这是独立开发者的全部推广预算

• 版本变更见 CHANGELOG.md

License

MIT © liv114514