Skip to main content
Glama

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 cd followed 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.sh and press Enter.

  • Windows: type .\setup.ps1 and press Enter. If it says the script is blocked, run Set-ExecutionPolicy -Scope CurrentUser RemoteSigned once 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-side

If 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 propose_memory → lands as proposed → promoted with pm review

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 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 (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.server

Then 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 tools
get_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

    A3.7/5.0

    Scored across 9 tools

    Disambiguation4/5

    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.

    Naming Consistency4/5

    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.

    Tool Count5/5

    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.

    Completeness4/5

    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

    Related MCP Servers

    • A
      license
      B
      quality
      B
      maintenance
      Persistent memory MCP server that captures coding session context and automatically injects relevant memories into prompts using hybrid search for OpenCode and Claude Code.
      14
      82
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      MCP server that captures and recalls coding session memory (failures, decisions, diffs) for AI agents, enabling cross-agent continuity and preventing repeated mistakes.
      69 npm
      MIT
    • A
      license
      A
      quality
      B
      maintenance
      MCP 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.
      21
      87 npm
      1
      MIT