Product Memory

코딩 에이전트를 위한 what/why 메모리 서버입니다. MCP 위에서 동작하며, 시스템의 한 조각이 *의미하는 바(what)*와 *왜 그렇게 구축되었는지(why)*를 함수 수준까지 답합니다. 그래서 에이전트(또는 여러분)는 이미 내려진 결정을 다시 유도하거나 다시 깨뜨리는 일을 멈추게 됩니다. 현재 코드는 *어떻게(how)*에 대한 진실의 원천으로 남으며, 이 저장소는 그것을 대체하려 하지 않습니다.

이 저장소에는 작은 합성 데모 저장소(memory-store/)가 포함되어 있습니다. orbitcart(체크아웃/결제)와 beacon(알림 전송)이라는 두 개의 가상 서비스가 있어, pm eval, 테스트, MCP 도구들이 누군가의 실제 코드베이스를 가리키지 않아도 바로 실행됩니다. 실제로 사용하려면 projects.yaml을 여러분의 저장소를 가리키도록 설정하세요.

실행하기 — 코딩 경험 불필요

1. 다운로드하세요. 더 쉬운 방법을 선택하세요:

• Git이 있다면: 터미널을 열고 git clone <this repo's URL>을 실행하세요.

• Git이 없다면: GitHub 페이지에서 초록색 Code 버튼을 클릭하고 → Download ZIP을 선택한 다음 압축을 풀세요.

2. 방금 다운로드한 폴더 안에서 터미널을 여세요.

• Mac: Finder에서 폴더를 찾아 마우스 오른쪽 버튼으로 클릭하고 New Terminal at Folder를 선택하세요. (또는 Terminal을 열고 cd 를 입력한 다음 폴더를 끌어다 놓고 Enter를 누르세요.)

• Windows: 파일 탐색기에서 폴더를 연 다음 Shift 키를 누른 채 폴더 안을 마우스 오른쪽 버튼으로 클릭하고 Open PowerShell window here를 선택하세요.

• Linux: 파일 관리자에서 폴더를 마우스 오른쪽 버튼으로 클릭하고 Open Terminal Here를 선택하세요. (데스크톱 환경에 따라 다릅니다.)

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를 통해 제안된 모든 사실은 사람이 pm review를 실행하기 전까지 status: proposed 상태를 가지며, 절대 verified 상태가 되지 않습니다. 잘못된 메모리를 신뢰하는 비용은 올바른 메모리를 놓치는 비용보다 크기 때문에, 기본값은 "작성됨(written)"이지 "참(true)"이 아닙니다.

랭킹은 가정이 아니라 측정된 결과입니다. pm eval은 알려진 답이 있는 고정된 실제 질문 집합에 대해 키워드 검색(SQLite FTS5 기반 BM25)을 의미론적 벡터 인덱스와 대조하여 점수를 매기고, 한 번만 결정하는 대신 실행할 때마다 다시 확인합니다. 이번 실행에서 더 좋은 순위를 보인 쪽이 순위를 차지합니다. 저자의 개인 말뭉치(1,192개 항목)에서 키워드 검색은 0.785 MRR, 의미론적 검색만 사용한 경우는 0.436 MRR이었으며, 벡터 인덱스는 추가 재현율(extra recall)로서 그 아래에만 추가되고 키워드 결과의 순서를 절대 바꾸지 않습니다. 이 저장소의 작은 12-질문 데모 세트에서는 키워드만으로도 12개를 모두 찾습니다(pm eval → 0.819 MRR, 12/12). 비교에 의미론적/퓨전 행도 포함하려면 먼저 pm embed를 실행하세요. eval/queries.json 및 product_memory/evaluate.py를 참조하세요.

메모리가 어떻게 채워지는가

절대 전체 백필(backfill)을 수행하지 않습니다. 완료되기 전에 이미 쓸모없어지기 때문입니다. 네 가지 채널이 있습니다:

레이아웃

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로 기록하거나, 편집(redaction)과 함께 자동 승인합니다 — 대신 강제 격리하려면 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, gitignore 처리됨, 또는 PM_SECRET_LITERALS)과 일반적인 자격 증명 형태 휴리스틱(라벨 + 근접한 고엔트로피 값)으로 구성됩니다. 데모 저장소에는 편집(redact)할 내용이 없으며, pm eval 테스트 스위트에는 이를 정확히 단언하는 CI 가드(test_demo_store_is_clean)가 포함되어 있습니다.

라이선스

MIT — LICENSE를 참조하세요.