Simple project memory
A single, human-readable memory file per project so context survives across sessions.
Deliberately lightweight — no database, no tooling required.
Where it lives
./.memory/PROJECT_MEMORY.md at the repo root. Create the folder if missing.
If the repo already uses a memory system (Cognee, memspec, CLAUDE.md), prefer that and skip this —
don't duplicate durable knowledge across systems.
Structure
# Project Memory — <project name>
_Last cleaned: YYYY-MM-DD_
## Facts # stable truths about the project (stack, domains, key paths, constraints)
## Decisions # choices made and WHY (one line each, dated) — the reasoning, not the code
## Preferences # how the user wants work done here (style, workflow, do/don't)
## Open threads # in-flight work, TODOs, things to revisit — the only section that churns
Rules for good entries
- One fact per line, dated where it matters. Convert relative dates ("next week") to absolute.
- Record the non-obvious: the why behind a decision, a gotcha, a constraint — not what the
code, git history, or README already states plainly.
- Never store secrets, tokens, or credentials.
Operations
- Create: scaffold the file with the four headers and fill in what you already know.
- Update: append/edit the right section. Move finished "Open threads" into Decisions/Facts.
- Cleanup (run when asked or when the file feels bloated): merge duplicates, delete anything
now wrong or obsolete, drop entries the code/docs already cover, tighten wording, and bump
_Last cleaned:_. Show the user what you removed.
Recall
At the start of work in a repo, read .memory/PROJECT_MEMORY.md if it exists before acting.
1---2name: project-memory3description: Create, structure, update, and clean up a simple per-project memory file. Use when starting work in a new repo, when the user shares a durable fact/decision/preference worth remembering, when memory has grown stale or duplicated, or when the user says "remember this", "update memory", or "clean up memory".4---56# Simple project memory78A single, human-readable memory file per project so context survives across sessions.9Deliberately lightweight — no database, no tooling required.1011## Where it lives1213`./.memory/PROJECT_MEMORY.md` at the repo root. Create the folder if missing.14If the repo already uses a memory system (Cognee, memspec, CLAUDE.md), prefer that and skip this —15don't duplicate durable knowledge across systems.1617## Structure1819```markdown20# Project Memory — <project name>21_Last cleaned: YYYY-MM-DD_2223## Facts # stable truths about the project (stack, domains, key paths, constraints)24## Decisions # choices made and WHY (one line each, dated) — the reasoning, not the code25## Preferences # how the user wants work done here (style, workflow, do/don't)26## Open threads # in-flight work, TODOs, things to revisit — the only section that churns27```2829## Rules for good entries3031- **One fact per line**, dated where it matters. Convert relative dates ("next week") to absolute.32- Record the **non-obvious**: the *why* behind a decision, a gotcha, a constraint — not what the33 code, git history, or README already states plainly.34- Never store secrets, tokens, or credentials.3536## Operations3738- **Create**: scaffold the file with the four headers and fill in what you already know.39- **Update**: append/edit the right section. Move finished "Open threads" into Decisions/Facts.40- **Cleanup** (run when asked or when the file feels bloated): merge duplicates, delete anything41 now wrong or obsolete, drop entries the code/docs already cover, tighten wording, and bump42 `_Last cleaned:_`. Show the user what you removed.4344## Recall4546At the start of work in a repo, read `.memory/PROJECT_MEMORY.md` if it exists before acting.
soukupl