Product Memory

Сервер памяти «что/почему» для кодинг-агентов, работающий через MCP. Он отвечает на вопросы, что означает часть системы и почему она была построена именно так — вплоть до уровня функций, — чтобы агент (или вы) перестал заново выводить или ломать решение, которое кто-то уже принял. Текущий код остаётся источником истины для как; это хранилище никогда не пытается его заменить.

В этом репозитории есть небольшое синтетическое демонстрационное хранилище (memory-store/) — два вымышленных сервиса, orbitcart (checkout/платежи) и beacon (отправка уведомлений), — так что pm eval, тесты и MCP-инструменты работают из коробки без привязки к чьей-либо реальной кодовой базе. Укажите projects.yaml на свои репозитории, чтобы использовать его по-настоящему.

Запуск — без опыта программирования

1. Скачайте его. Выберите, что удобнее:

• Если у вас есть Git: откройте Терминал и выполните git clone <this repo's URL>

• Если нет: на странице GitHub нажмите зелёную кнопку Code → Download ZIP, затем распакуйте архив.

2. Откройте терминал в только что скачанной папке.

• Mac: найдите папку в Finder, щёлкните по ней правой кнопкой мыши и выберите Новый терминал в папке (или откройте Терминал, введите cd и перетащите папку в окно, затем нажмите Enter).

• Windows: откройте папку в Проводнике, зажмите Shift и щёлкните правой кнопкой внутри папки, выберите Открыть окно PowerShell здесь.

• Linux: щёлкните правой кнопкой внутри папки в файловом менеджере и выберите Открыть терминал здесь (зависит от окружения).

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 и укажите в нём свои репозитории.

Два ключевых допущения

Ничто из написанного агентом не считается доверенным по умолчанию. Каждый факт, предложенный через propose_memory, получает status: proposed — никогда verified, — пока человек не запустит pm review. Доверие ошибочной памяти обходится дороже, чем пропуск правильной, поэтому по умолчанию запись «записано», а не «истинно».

Ранжирование измеряется, а не предполагается. pm eval оценивает поиск по ключевым словам (BM25 поверх SQLite FTS5) против семантического векторного индекса на фиксированном наборе реальных вопросов с известными ответами и перепроверяет его при каждом запуске, а не один раз. Какой метод ранжирует лучше в этом запуске, тот и используется — в личном корпусе автора (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.

Как наполняется память

Никогда не выполняется полный бэкфилл — он устарел бы раньше, чем завершился. Четыре канала:

Структура

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, gitignored, или PM_SECRET_LITERALS) плюс общая эвристика формы учётных данных (метка + значение с высокой энтропией поблизости). Демонстрационное хранилище поставляется без данных для редактирования; тестовый набор pm eval включает CI-проверку (test_demo_store_is_clean), которая утверждает именно это.

Лицензия

MIT — см. LICENSE.