Product Memory

A what/why memory server for coding agents, over MCP. It answers what a piece of a system means and why it was built that way — down to the function level — so an agent (or you) stops re-deriving or re-breaking a decision someone already made. The current code stays the source of truth for how; this store never tries to replace it.

This repo ships with a small synthetic demo store (memory-store/) — two fictional services, orbitcart (checkout/payments) and beacon (notification dispatch) — so pm eval, the tests, and the MCP tools all run out of the box without pointing at anyone's real codebase. Point projects.yaml at your own repos to use it for real.

让它运行起来——无需编码经验

1. 下载。 选择任一更简单的方式：

• 如果你有 Git：打开终端并运行 git clone <this repo's URL>

• 如果没有：在 GitHub 页面上，点击绿色的 Code 按钮 → Download ZIP，然后解压缩。

2. 在你刚刚下载的文件夹中打开终端。

• Mac： 在 Finder 中找到该文件夹，右键点击它，选择 New Terminal at Folder（或打开 Terminal 并输入 cd ，然后将文件夹拖入，再按回车）。

• Windows： 在文件资源管理器中打开该文件夹，按住 Shift 并右键点击内部空白处，选择 Open PowerShell window here。

• Linux： 在文件管理器中右键点击该文件夹内部，选择 Open Terminal Here（因桌面环境而异）。

3. 运行设置脚本。

• Mac / Linux： 输入 bash setup.sh 并按回车。

• Windows： 输入 .\setup.ps1 并按回车。如果提示脚本被阻止，先运行一次 Set-ExecutionPolicy -Scope CurrentUser RemoteSigned，然后重试。

就这样——它会安装此项目所需的一切（不会安装到系统范围，无需管理员密码），构建附带的演示，并运行一次真实搜索以证明其有效。你会看到类似这样的内容：

✓ Python 3 found (3.13.5)
✓ uv found
✓ Dependencies installed
✓ Demo memory store indexed

Trying a real search against the demo store...
  8.75  [adr/verified] adr-0004-idempotency-keys-generated-client-side
        ADR-0004: idempotency keys are generated client-side, not server-side

如果 Claude Code 已经在你的机器上，脚本会提供将 Product Memory 连接到它的选项——选择是，重启 Claude Code，它就会在每个项目中生效。如果没有，或者你使用不同的编码代理，请参阅下面的 MCP 工具，并将你的代理的 MCP 配置指向 uv run --directory <this folder> python -m product_memory.server。

运行起来后，试试：

uv run pm serve             # a local web page to browse the memory
uv run pm search "your question here"

当你准备真正使用它（而非演示）时，打开 projects.yaml，改为指向你自己的仓库。

两个设计赌注

代理写入的任何内容在到达时都不会被信任。 通过 propose_memory 提出的每个事实都会获得 status: proposed——永远不会是 verified——直到有人运行 pm review。信任一个错误的记忆比错过一个正确的记忆代价更高，因此默认是“已写入”，而不是“为真”。

排名是实测出来的，而不是假设出来的。 pm eval 对关键词搜索（基于 SQLite FTS5 的 BM25）与语义向量索引在一组固定的、已知答案的真实问题上进行评分，并在每次运行时重新检查，而不是一次定论。这次运行中排名更好的一方就是排名更高的一方——在作者的私人语料库（1,192 条）中，关键词搜索的 MRR 为 0.785，而纯语义搜索为 0.436——向量索引仅作为额外召回追加在其下方，从不重新排序关键词的结果。在本仓库较小的 12 题演示集上，仅关键词搜索就已经能找到全部 12 题（pm eval → 0.819 MRR, 12/12）；如果你想在比较中也包含语义/融合行，请先运行 pm embed。参见 eval/queries.json 和 product_memory/evaluate.py。

记忆如何被填充

绝不全量回填——那样在完成之前就已经过时了。有四种渠道：

布局

memory-store/           canonical store — markdown files in git, one fact each
  _inbox/               agent proposals awaiting human promotion (or auto-approved, see below)
  <project>/<repo>/     verified + promoted items
demo-repos/             tiny stub repos the demo store's code_symbol entries point at
projects.yaml           registry: project -> repos -> disk paths
product_memory/
  models.py             data contracts (MemoryItem, TaskContext, WhyCard, ...)
  store.py              parse/iterate/propose store files
  index.py              SQLite FTS5 build + ranked search (disposable index)
  semantic.py           chunking + vector index, used for recall only
  evaluate.py           `pm eval` — MRR per retrieval mode, the ranking gate
  conventions.py        derive a repo's house style (declared + observed)
  retrieval.py          packet assembly (deterministic, no LLM)
  staleness.py           flags memories whose source code/doc changed since
  server.py             FastMCP stdio server — the MCP tools
  webapp.py             FastAPI local server (`pm serve`), loopback only
  dashboard.py          the review queue UI
  ingest/                importers + secret redaction
  cli.py                `pm` — the commands below
eval/queries.json       retrieval cases with known answers
tests/

命令

pm serve                 # live local server: real search, feedback, persisted marks
pm dashboard --open      # generate the standalone review-queue file
pm search "query"        # ranked search from the terminal
pm eval                  # score retrieval against eval/queries.json — run before ranking changes
pm conventions --project beacon --repo beacon   # derive a repo's house style
pm review                # the only path from proposed to verified
pm index && pm embed     # rebuild the keyword index and the chunked vector index
pm stale                 # notes whose source moved on

MCP 工具

get_task_context · search_product_memory · get_project_overview · get_domain_rules · get_related_decisions · why_code(file, symbol) · get_recent_work · propose_memory（写入 proposed，或在脱敏后自动批准——参见 PM_REVIEW=1 强制隔离）

设置

刚接触这个并且只想让它跑起来？请改用 bash setup.sh（Windows 上为 .\setup.ps1）——参见上面的 让它运行起来。下面的手动步骤是相同内容的详细说明：

git clone <this repo>
cd product-memory
uv sync
uv run pytest
uv run python -m product_memory.cli eval   # or: pm eval, once installed

# register for ALL repos (user scope):
claude mcp add --scope user product-memory -- \
  uv run --directory "$PWD" python -m product_memory.server

然后，将 projects.yaml 指向你自己的仓库，删除或保留演示用的 orbitcart/beacon 条目，并在工作中开始使用 propose_memory 捕获真实的记忆。

机密

写入存储的任何内容都会经过 redact_secrets——一个已知字面量列表（secret-literals.txt，已 gitignore，或 PM_SECRET_LITERALS）加上一个通用的凭据形状启发式规则（标签 + 邻近的高熵值）。演示存储不附带任何需要脱敏的内容；pm eval 的测试套件包含一个 CI 守卫（test_demo_store_is_clean），正是用来断言这一点。

许可证

MIT——参见 LICENSE。