# Project Memory

> 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".

- Skill: `soukupl/project-memory` (Agent Skill)
- Install (CLI): `npx skillmds@latest add soukupl/project-memory`
- Raw SKILL.md: https://api.skillmd.com/api/skills/soukupl/project-memory/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: soukupl (https://skillmd.com/u/soukupl)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/soukupl/project-memory

---


# 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

```markdown
# 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.