Product Memory

Un servidor de memoria de qué/por qué para agentes de codificación, sobre MCP. Responde qué significa una parte de un sistema y por qué se construyó así — hasta el nivel de función — para que un agente (o tú) deje de re-deducir o re-romper una decisión que alguien ya tomó. El código actual sigue siendo la fuente de verdad del cómo; este almacén nunca intenta reemplazarlo.

Este repositorio incluye una tienda de demostración sintética (memory-store/) — dos servicios ficticios, orbitcart (checkout/pagos) y beacon (despacho de notificaciones) — para que pm eval, los tests y las herramientas MCP funcionen sin configuración adicional y sin apuntar al código real de nadie. Apunta projects.yaml a tus propios repositorios para usarlo de verdad.

Ponlo en marcha — sin necesidad de experiencia en programación

1. Descárgalo. Elige lo que te resulte más fácil:

• Si tienes Git: abre Terminal y ejecuta git clone <this repo's URL>

• Si no lo tienes: en la página de GitHub, haz clic en el botón verde Code → Download ZIP, y descomprímelo.

2. Abre una terminal dentro de la carpeta que acabas de descargar.

• Mac: busca la carpeta en Finder, haz clic derecho sobre ella, elige New Terminal at Folder (o abre Terminal y escribe cd seguido de arrastrar la carpeta dentro, y pulsa Enter).

• Windows: abre la carpeta en el Explorador de archivos, mantén pulsada la tecla Mayús y haz clic derecho dentro de ella, elige Open PowerShell window here.

• Linux: haz clic derecho dentro de la carpeta en tu gestor de archivos, elige Open Terminal Here (varía según el escritorio).

3. Ejecuta el script de configuración.

• Mac / Linux: escribe bash setup.sh y pulsa Enter.

• Windows: escribe .\setup.ps1 y pulsa Enter. Si dice que el script está bloqueado, ejecuta Set-ExecutionPolicy -Scope CurrentUser RemoteSigned una vez primero, y luego inténtalo de nuevo.

Eso es todo: instala todo lo que este proyecto necesita (nada a nivel del sistema, sin contraseña de administrador), compila la demo incluida y ejecuta una búsqueda real para demostrar que funciona. Verás algo como:

✓ 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

Si Claude Code ya está en tu máquina, el script te ofrecerá conectar Product Memory a él: di que sí, reinicia Claude Code y estará activo para todos los proyectos. Si no, o si usas un agente de codificación diferente, consulta Herramientas MCP a continuación y apunta la configuración MCP de tu agente a uv run --directory <this folder> python -m product_memory.server.

Una vez que esté en funcionamiento, prueba:

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

Cuando estés listo para usarlo de verdad (no la demo), abre projects.yaml y apúntalo a tus propios repositorios en su lugar.

Las dos apuestas de diseño

Nada de lo que escribe un agente se considera fiable a su llegada. Cada hecho propuesto mediante propose_memory recibe status: proposed — nunca verified — hasta que un humano ejecuta pm review. Confiar en una memoria equivocada cuesta más que perder una correcta, así que el valor predeterminado es "escrito", no "verdadero".

El ranking se mide, no se asume. pm eval puntúa la búsqueda por palabras clave (BM25 sobre SQLite FTS5) frente a un índice de vectores semánticos sobre un conjunto fijo de preguntas reales con respuestas conocidas, y lo vuelve a comprobar en cada ejecución en lugar de decidirlo una sola vez. El que mejor puntúe en esta ejecución es el que se usa — en el corpus privado del autor (1.192 elementos) eso es palabras clave con 0,785 MRR frente a 0,436 solo con semántica — y el índice vectorial solo se añade por debajo como recuperación adicional, sin reordenar nunca el resultado de las palabras clave. En el pequeño conjunto de demostración de 12 preguntas de este repositorio, solo las palabras clave ya encuentran las 12 (pm eval → 0.819 MRR, 12/12); ejecuta pm embed primero si quieres que aparezcan también las filas semántica/fusión en la comparación. Consulta eval/queries.json y product_memory/evaluate.py.

Cómo se puebla la memoria

Nunca un backfill completo — quedaría obsoleto antes de terminar. Cuatro canales:

Estructura

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/

Comandos

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

Herramientas 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 (escribe proposed, o auto-aprueba con redacción — consulta PM_REVIEW=1 para forzar cuarentena en su lugar)

Instalación

¿Nuevo en esto y solo quieres ponerlo en marcha? Usa bash setup.sh (.\setup.ps1 en Windows) en su lugar — consulta Ponlo en marcha más arriba. Los pasos manuales de abajo son lo mismo, pero detallados:

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

Luego apunta projects.yaml a tus propios repositorios, elimina o conserva las entradas de la demo orbitcart/beacon, y empieza a capturar memorias reales con propose_memory mientras trabajas.

Secretos

Todo lo que se escribe en el almacén pasa por redact_secrets — una lista de literales conocidos (secret-literals.txt, ignorado por git, o PM_SECRET_LITERALS) más una heurística genérica de forma de credenciales (etiqueta + valor de alta entropía en proximidad). La tienda de demo no trae nada que redactar; la suite de tests de pm eval incluye una comprobación de CI (test_demo_store_is_clean) que verifica exactamente eso.

Licencia

MIT — consulta LICENSE.