Product Memory
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Product Memory Why does checkout use client-side idempotency keys?"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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.
Get it running — no coding experience needed
1. Download it. Pick whichever is easier:
If you have Git: open Terminal and run
git clone <this repo's URL>If you don't: on the GitHub page, click the green Code button → Download ZIP, then unzip it.
2. Open a terminal inside the folder you just downloaded.
Mac: find the folder in Finder, right-click it, choose New Terminal at Folder (or open Terminal and type
cdfollowed by dragging the folder in, then press Enter).Windows: open the folder in File Explorer, hold Shift and right-click inside it, choose Open PowerShell window here.
Linux: right-click inside the folder in your file manager, choose Open Terminal Here (varies by desktop).
3. Run the setup script.
Mac / Linux: type
bash setup.shand press Enter.Windows: type
.\setup.ps1and press Enter. If it says the script is blocked, runSet-ExecutionPolicy -Scope CurrentUser RemoteSignedonce first, then try again.
That's it — it installs everything this project needs (nothing system-wide, no admin password), builds the included demo, and runs a real search to prove it works. You'll see something like:
✓ 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-sideIf Claude Code is already on your machine, the script will offer to connect
Product Memory to it — say yes, restart Claude Code, and it's live for every
project. If not, or if you use a different coding agent, see MCP tools
below and point your agent's MCP config at
uv run --directory <this folder> python -m product_memory.server.
Once it's running, try:
uv run pm serve # a local web page to browse the memory
uv run pm search "your question here"When you're ready to use it for real (not the demo), open projects.yaml
and point it at your own repositories instead.
Related MCP server: SyncContext
The two design bets
Nothing an agent writes is trusted on arrival. Every fact proposed via
propose_memory gets status: proposed — never verified — until a human
runs pm review. Trusting a wrong memory costs more than missing a right
one, so the default is "written," not "true."
Ranking is measured, not assumed. pm eval scores keyword search (BM25
over SQLite FTS5) against a semantic vector index on a fixed set of real
questions with known answers, and re-checks it on every run rather than
settling it once. Whichever ranks better this run is the one that ranks —
in the author's private corpus (1,192 items) that's keyword at 0.785 MRR vs.
0.436 for semantic-only — with the vector index only appended below it as
extra recall, never reordering keyword's result. On this repo's small
12-question demo set, keyword alone already finds all 12 (pm eval →
0.819 MRR, 12/12); run pm embed first if you want the semantic/fusion
rows in the comparison too. See eval/queries.json and
product_memory/evaluate.py.
How memory gets populated
Never a full backfill — it would be stale before it finished. Four channels:
# | Channel | When | What lands |
1 | Docs import | once per repo | pointers/summaries of CLAUDE.md, CONVENTIONS.md, planning docs — never forked copies |
1b | Doc-tree import | once per large docs tree | bulk import with hard filtering (drops vendored docs, stubs, duplicates, "✅ Fixed!" session reports) |
2 | Change-time capture | every finished agent task | agent calls |
3 | Ask-time backfill | whenever you ask "why does X work like this?" | the agent researches once, answers you, and proposes the answer as a memory |
Layout
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/Commands
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 onMCP 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 (writes proposed, or auto-approves with
redaction — see PM_REVIEW=1 to force quarantine instead)
Setup
New to this and just want it running? Use bash setup.sh (.\setup.ps1 on
Windows) instead — see Get it running above. The manual steps below are
the same thing, spelled out:
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.serverThen point projects.yaml at your own repositories, delete or keep the demo
orbitcart/beacon entries, and start capturing real memories with
propose_memory as you work.
Secrets
Anything written into the store is passed through redact_secrets — a
known-literals list (secret-literals.txt, gitignored, or PM_SECRET_LITERALS)
plus a generic credential-shape heuristic (label + high-entropy value in
proximity). The demo store ships with nothing to redact; pm eval's test
suite includes a CI guard (test_demo_store_is_clean) asserting exactly that.
License
MIT — see LICENSE.
Available Tools
9 toolsget_domain_rulesA
Verified invariants for a domain operation (e.g. 'wallet' / 'reverse transaction'). MANDATORY before money-path/auth/tenancy changes.
Inputs: domain (required), operation (required), project. Returns: result
get_project_overviewB
Product purpose, service map, boundaries, and critical rules for a project/repository. Call when entering a repo for the first time.
Inputs: project (required), repository.
get_recent_workC
Worklog: what was done and why, newest first. since = ISO date.
Inputs: since, project. Returns: result
get_task_contextA
Compact task-specific packet: architecture, business rules, gotchas, code pointers, risks, verification steps. Call BEFORE planning.
Inputs: task (required), paths, project, repository, +1 more. Returns: The packet get_task_context returns. Small on purpose: statements and pointers,…
propose_memoryA
Record a new memory. Auto-approved by default; set PM_REVIEW=1 to queue
it for pm review instead.
Auto-approve is the default because a proposal sitting in the inbox is a fact
the next session does not have — the queue was the thing between writing a
memory and being able to use it. Redaction and collision-safety are NOT
relaxed by it: secrets are still stripped before the write (the store is
committed to git) and an id clash still suffixes rather than overwrites.
Auto-approved entries record verified_by="auto", so a reader can tell a
machine-approved note from one a person checked.
Use at task completion: one type='code_symbol' entry per function you added
or meaningfully changed (body: WHAT: / WHY: / NEED: / WHY THIS WAY: /
GOTCHA:), passing refs with the PRD, spec or ticket that asked for it,
plus one type='worklog' entry for the task itself. Also use to record the
answer when the user asks "why does X work this way?".
Never include credentials, tokens, or passwords — this store is committed to git.
Inputs: type (required), title (required), content (required), project (required), +6 more.
read_memoryA
The FULL body of one memory, by the id a search hit returned.
The counterpart to snippet results: search gives you the passage that matched and enough to choose from, this gives you the whole note once you have chosen. Returns None when the id is unknown, which is the honest answer for a stale id from an older session rather than a guess at the nearest match.
Inputs: memory_id (required). Returns: result
search_product_memoryA
Ranked search over all verified product/architecture/incident memory.
Returns a SNIPPET of each hit — the passage that matched — plus store_path.
Read the file when a snippet turns out to be the thing; full=True returns
whole bodies, which costs roughly five times as much for a list you are
mostly scanning to choose from.
Inputs: query (required), full, limit, project, +1 more. Returns: result
why_codeA
WHAT/WHY/WHY-THIS-WAY/GOTCHA card for a function or file. Call before rewriting existing code so past decisions aren't undone blindly.
Inputs: file (required), symbol. Returns: result
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 9 tools
The tools have mostly clear, distinct purposes: search vs. read, context retrieval vs. rule retrieval, and write vs. read. However, the context-retrieval tools (get_project_overview, get_task_context, get_domain_rules, get_related_decisions) overlap somewhat and rely on descriptions to tell them apart, and search_product_memory with full=True partially duplicates read_memory.
Most tools follow a consistent get_/search_/read_/propose_ verb pattern, which makes the set predictable. why_code breaks the pattern as a noun-style tool name, and the mix of get_ with search_/read_ is a minor deviation.
Nine tools is well within the ideal range for a product memory server, and each tool covers a distinct retrieval or write need. The count feels appropriately scoped without being bloated or thin.
The surface covers the core lifecycle well: search, read, targeted context retrieval, recent work, and recording new memories. There is no explicit update/delete/invalidation tool for memories, though the append-only/id-suffix design suggests this may be intentional; still, explicit correction would make it more complete.
Related MCP Connectors
Team memory for AI coding agents and code reviews, reviewed by humans and served over MCP.
An MCP memory server. One memory your agents share — across models, devices and apps.
Hosted MCP memory for coding agents: persistent across sessions, editable markdown, team sharing.
Persistent memory, knowledge graph, task management and more for AI agents via MCP.
Related MCP Servers
- AlicenseBqualityBmaintenancePersistent memory MCP server that captures coding session context and automatically injects relevant memories into prompts using hybrid search for OpenCode and Claude Code.1482MIT
- AlicenseAqualityDmaintenanceMCP server that provides a shared semantic memory layer for AI coding agents, enabling teams to store, search, and sync context, decisions, and knowledge across projects with project-based isolation and multi-backend support.141MIT
- AlicenseNot gradedqualityDmaintenanceMCP server that captures and recalls coding session memory (failures, decisions, diffs) for AI agents, enabling cross-agent continuity and preventing repeated mistakes.69 npmMIT
- AlicenseAqualityBmaintenanceMCP server that gives coding agents persistent, verified memory of codebase decisions, conventions, and skills, with evidence-based claims that are re-checked via git hooks and human-gated review. Enables memory search, propose/approve, chat harvesting, and critique across MCP-compatible tools.2187 npm1MIT