Product Memory

Ein What/Why-Speicherserver für Coding-Agenten über MCP. Er beantwortet, was ein Teil eines Systems bedeutet und warum er so gebaut wurde — bis auf die Funktionsebene — damit ein Agent (oder du) aufhört, eine bereits getroffene Entscheidung erneut abzuleiten oder zu brechen. Der aktuelle Code bleibt die Quelle der Wahrheit für wie; dieser Speicher versucht nie, ihn zu ersetzen.

Dieses Repo enthält einen kleinen synthetischen Demo-Speicher (memory-store/) — zwei fiktive Dienste, orbitcart (Checkout/Zahlungen) und beacon (Benachrichtigungsversand) — sodass pm eval, die Tests und die MCP-Tools sofort laufen, ohne auf die echte Codebasis von jemandem zu zeigen. Richte projects.yaml auf deine eigenen Repositories aus, um es wirklich zu nutzen.

Zum Laufen bringen — keine Programmiererfahrung nötig

1. Herunterladen. Wähle, was dir leichter fällt:

• Wenn du Git hast: Öffne das Terminal und führe git clone <this repo's URL> aus

• Falls nicht: Klicke auf der GitHub-Seite auf den grünen Code-Button → Download ZIP und entpacke die Datei.

2. Öffne ein Terminal in dem Ordner, den du gerade heruntergeladen hast.

• Mac: Finde den Ordner im Finder, klicke mit der rechten Maustaste darauf und wähle Neues Terminal im Ordner (oder öffne Terminal und tippe cd , ziehe dann den Ordner hinein, und drücke Enter).

• Windows: Öffne den Ordner im Datei-Explorer, halte die Umschalttaste gedrückt und klicke mit der rechten Maustaste hinein, wähle PowerShell-Fenster hier öffnen.

• Linux: Klicke in deinem Dateimanager mit der rechten Maustaste in den Ordner und wähle Terminal hier öffnen (je nach Desktop unterschiedlich).

3. Führe das Setup-Skript aus.

• Mac / Linux: Tippe bash setup.sh und drücke Enter.

• Windows: Tippe \.setup.ps1 und drücke Enter. Falls gemeldet wird, dass das Skript blockiert ist, führe zuerst einmal Set-ExecutionPolicy -Scope CurrentUser RemoteSigned aus und versuche es dann erneut.

Das war's — es installiert alles, was dieses Projekt braucht (nichts systemweit, kein Admin-Passwort), erstellt die enthaltene Demo und führt eine echte Suche aus, um zu zeigen, dass es funktioniert. Du wirst so etwas sehen:

✓ 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

Wenn Claude Code bereits auf deinem Rechner ist, bietet das Skript an, Product Memory damit zu verbinden — sag ja, starte Claude Code neu, und es ist für jedes Projekt aktiv. Wenn nicht, oder wenn du einen anderen Coding-Agenten verwendest, siehe MCP-Tools unten und richte die MCP-Konfiguration deines Agenten auf uv run --directory <this folder> python -m product_memory.server aus.

Sobald es läuft, versuche:

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

Wenn du bereit bist, es wirklich zu nutzen (nicht die Demo), öffne projects.yaml und richte es stattdessen auf deine eigenen Repositories aus.

Die zwei Design-Entscheidungen

Nichts, was ein Agent schreibt, wird bei der Ankunft vertraut. Jede Tatsache, die über propose_memory vorgeschlagen wird, erhält status: proposed — niemals verified — bis ein Mensch pm review ausführt. Einer falschen Erinnerung zu vertrauen kostet mehr, als eine richtige zu verpassen, daher ist der Standard „geschrieben“, nicht „wahr“.

Ranking wird gemessen, nicht angenommen. pm eval bewertet die Stichwortsuche (BM25 über SQLite FTS5) gegen einen semantischen Vektorindex auf einer festen Menge realer Fragen mit bekannten Antworten und prüft sie bei jedem Lauf erneut, statt sie nur einmal festzulegen. Welches bei diesem Lauf besser abschneidet, das rankt — im privaten Korpus des Autors (1.192 Einträge) ist das Stichwort bei 0,785 MRR gegenüber 0,436 für rein semantisch — wobei der Vektorindex nur darunter als zusätzlicher Recall angehängt wird und das Stichwort-Ergebnis nie umsortiert. Bei der kleinen Demo-Menge dieses Repos mit 12 Fragen findet allein die Stichwortsuche bereits alle 12 (pm eval → 0.819 MRR, 12/12); führe zuerst pm embed aus, wenn du auch die semantischen/Fusion-Zeilen im Vergleich sehen willst. Siehe eval/queries.json und product_memory/evaluate.py.

Wie der Speicher gefüllt wird

Nie ein vollständiges Backfill — es wäre veraltet, bevor es fertig ist. Vier Kanäle:

Aufbau

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/

Befehle

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-Tools

get_task_context · search_product_memory · get_project_overview · get_domain_rules · get_related_decisions · why_code(file, symbol) · get_recent_work · propose_memory (schreibt proposed, oder genehmigt automatisch mit Schwärzung — siehe PM_REVIEW=1, um stattdessen Quarantäne zu erzwingen)

Einrichtung

Neu hier und willst es einfach zum Laufen bringen? Benutze stattdessen bash setup.sh (\.setup.ps1 unter Windows) — siehe Zum Laufen bringen oben. Die manuellen Schritte unten sind dasselbe, ausführlich erklärt:

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

Richte dann projects.yaml auf deine eigenen Repositories aus, lösche oder behalte die Demo-Einträge orbitcart/beacon, und beginne beim Arbeiten, echte Erinnerungen mit propose_memory aufzuzeichnen.

Geheimnisse

Alles, was in den Speicher geschrieben wird, läuft durch redact_secrets — eine Liste bekannter Literale (secret-literals.txt, gitignoriert, oder PM_SECRET_LITERALS) plus eine generische Heuristik für Anmeldedaten (Bezeichnung + Wert mit hoher Entropie in der Nähe). Der Demo-Speicher enthält nichts zu schwärzen; die Testsuite von pm eval enthält eine CI-Absicherung (test_demo_store_is_clean), die genau das bestätigt.

Lizenz

MIT — siehe LICENSE.