Product Memory

コーディングエージェント向けの、MCP 上で動作する what/why メモリサーバーです。システムの一部が 意味する ことと、なぜそのように構築されたか を、関数レベルまで掘り下げて答えます。これにより、エージェント（またはあなた）が、誰かがすでに行った決定を再導出したり、壊したりすることを防ぎます。現在のコードは どのように のソース・オブ・トゥルースであり続けます。このストアは決してそれを置き換えようとはしません。

このリポジトリには小さな合成デモストア（memory-store/）が同梱されています。orbitcart（チェックアウト/支払い）と beacon（通知配信）という2つの架空のサービスがあり、pm eval、テスト、MCP ツールがすべて、誰かの実際のコードベースを参照せずにすぐ動作します。実際に使うには、projects.yaml を自分のリポジトリに向けてください。

実行方法 — コーディング経験は不要

1. ダウンロードする。 どちらか簡単な方を選んでください:

• Git をお持ちの場合: Terminal を開いて git clone <this repo's URL> を実行

• お持ちでない場合: GitHub ページで緑の Code ボタンをクリック → Download ZIP を選択し、解凍します。

2. ダウンロードしたフォルダ内でターミナルを開きます。

• Mac: Finder でフォルダを探し、右クリックして New Terminal at Folder を選択します（または Terminal を開いて cd と入力し、フォルダをドラッグ＆ドロップして Enter を押します）。

• Windows: ファイルエクスプローラーでフォルダを開き、Shift を押しながらフォルダ内で右クリックし、Open PowerShell window here を選択します。

• Linux: ファイルマネージャーでフォルダ内を右クリックし、Open Terminal Here を選択します（デスクトップによって異なります）。

3. セットアップスクリプトを実行します。

• Mac / Linux: bash setup.sh と入力して Enter を押します。

• Windows: .\setup.ps1 と入力して Enter を押します。スクリプトがブロックされたと表示された場合は、最初に 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 を開いて自分のリポジトリを指定してください。

2つの設計上の賭け

エージェントが書いたものは、到着時点では信頼されません。 propose_memory を介して提案されたすべての事実は、人間が pm review を実行するまで status: proposed のままになり、決して verified にはなりません。誤ったメモリを信頼することは、正しいメモリを見逃すことよりもコストがかかるため、デフォルトは「真」ではなく「書き込まれた」です。

ランキングは推測ではなく測定されます。 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 を参照してください。

メモリがどのように蓄積されるか

完全なバックフィルは行いません。完了する前に古くなってしまうからです。4つのチャネルがあります:

レイアウト

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 を参照してください。