Document

Document Project Context

Preserve the small amount of project context that should survive the current conversation. The memory is a curated operational reference, not a transcript, status dump, or substitute for code and canonical documentation.

Find the canonical memory

Read repository instructions first. Reuse an established project-memory, decision-log, handoff, or equivalent file when one exists and clearly serves this purpose.

Otherwise use PROJECT_MEMORY.md at the repository root. Create it only when there is durable information to record, with the following sections as needed:

# Project Memory

## Decisions

## Constraints and invariants

## Discoveries and gotchas

## Failed approaches

## Open threads

Omit empty sections when creating or maintaining the file. Follow stronger local conventions when they conflict with this default.

What belongs in memory

Record information whose absence could cause future work to repeat a mistake, violate an invariant, reopen a settled decision, or lose an important thread:

• decisions and the reason they were made;
• constraints, invariants, compatibility requirements, and intentional oddities;
• non-obvious discoveries about the codebase or environment;
• failed approaches when knowing why they failed will prevent repetition;
• operational gotchas and reliable recovery knowledge;
• unresolved questions or follow-ups that remain relevant after this task.

Do not record:

• routine edits already clear from the diff or git history;
• a chronological play-by-play of the conversation;
• temporary debugging output or speculative guesses;
• information already maintained authoritatively elsewhere—link to it instead;
• credentials, tokens, personal data, or other secrets.

Write useful entries

Each entry should be concise and answer the questions a future conversation would actually have: what must be remembered, why it matters, and where the evidence or affected implementation lives.

Use a form such as:

- **Short topic** — Durable fact, decision, or warning. Explain the reason or consequence when it is not obvious. Evidence: `path/to/file`, test name, issue, or command result. Last verified: YYYY-MM-DD.

Use dates only when freshness or sequence matters. Never invent evidence, certainty, ownership, or approval. Clearly label an unresolved belief as unverified.

Curate instead of append

Before adding an entry, search the memory and canonical project docs:

• update an existing entry rather than adding a duplicate;
• replace stale current-state claims with verified information;
• preserve decision history by marking a decision superseded and linking its replacement when the rationale still matters;
• remove resolved open threads and information that is now obvious, irrelevant, or canonical elsewhere;
• keep the file short enough to scan at the start of a future conversation.

When consulting memory, treat it as a lead rather than unquestionable truth. Verify time-sensitive or implementation-specific claims against the current repository before acting on them, and refresh the entry when the evidence has changed.

Completion check

Confirm that every addition is durable, non-duplicative, evidence-linked when practical, free of secrets, and actionable or explanatory for someone without the current conversation. Summarize what was added, updated, superseded, or removed.