---
description: Build a living memory system for your project — capture session decisions, evolving context, and lessons learned in structured files Claude reads automatically across sessions.
allowed-tools: Read, Write, Glob, Grep
---

# Setup: Projet Mémoire

Build a living memory system so Claude holds your project context across sessions — without you re-explaining it each time.

## The boundary you must hold

Two files, two jobs. Make this explicit before creating anything.

- **CLAUDE.md = the permanent brief.** Things that don't change: your stack, your conventions, your hard rules. Set once, update rarely.
- **Memory files = what evolves.** Decisions made since last session, context that shifted, lessons from what broke. Updated after each session, read at the start of the next.

If the user has no CLAUDE.md yet, tell them to run `/setup:claude-md` first. Memory without a brief is noise on top of a blank slate.

## What belongs in memory

Memory is not a dump. Each file answers one question:

- `context.md` — current state of the project (live features, what is in progress, what is blocked). The answer to "where are we now?"
- `decisions.md` — major choices and why you made them (one line per decision, with date). The answer to "why does it work this way?"
- `conventions.md` — patterns that emerged from actual work, not intentions. The answer to "how do we do things here?"
- `lessons.md` — things that broke or surprised you, and what you learned. The answer to "what should we not do again?"

Rule: if Claude would need to ask for it at the start of a session, it belongs in memory. If it's a rule that never changes, it belongs in CLAUDE.md.

## Workflow

### Phase 1 — Audit the gaps

Before creating any file, interview the user. Ask what Claude keeps needing to ask at session start — that is where the memory gaps are.

Ask:
1. What do you re-explain most often when you start a new Claude session?
2. What decisions have you made in the past two weeks that Claude does not know about?
3. What is the current state of your project — not the stack, but what is in progress or blocked right now?
4. What went wrong recently that you would want the next session to know?

Only propose files that fill real gaps from the answers. If the user has no recent decisions to track, skip `decisions.md` for now.

### Phase 2 — Design the folder structure

Default: `.claude/memory/`. Three to four files max to start. A memory system with fifteen files is not a system, it is a dump. Propose only what fills the gaps identified in Phase 1.

```
.claude/
  memory/
    context.md      → état courant (features live, en cours, bloqué)
    decisions.md    → décisions prises (date · choix · raison)
    conventions.md  → patterns émergés du vrai travail
    lessons.md      → ce qui a cassé et ce qu'on en a appris
```

### Phase 3 — Seed the first entries

Populate each file from the Phase 1 answers. No blank files — a blank file is not memory, it is friction. Each entry: one line, past tense, with date where the decision matters.

Example `decisions.md` entry:
```
2026-08-20 · Choisi Postgres plutôt que SQLite — volume prévu dépasse les limites SQLite en production.
```

### Phase 4 — Wire it to Claude Code

Two options. Ask which fits the project's pace:

**Option A — Reference in CLAUDE.md (recommended for stable projects)**

Add one instruction to the project CLAUDE.md:
```markdown
## Mémoire projet
Lis les fichiers dans .claude/memory/ en début de session.
```

Claude will load it automatically on every session start.

**Option B — Load skill (for fast-moving projects)**

If context shifts week to week, a dedicated loading skill avoids loading stale context when you want a clean slate:
```markdown
/memory:load — charge le contexte projet avant de commencer
```

### Phase 5 — The update ritual

A memory system only works if it gets updated. Output a ritual prompt the user can run before each `/clear`:

> Résume les décisions et apprentissages de cette session. Mets à jour les fichiers dans `.claude/memory/` en conséquence. Une décision = une ligne avec la date. Ne dépasse pas 40 lignes par fichier.

Also tell the user: when a file grows past 40 lines, it is time to restructure — archive old entries, keep only what Claude still needs to know today.

## Rules

- Start with three to four files max. Growth is better than completeness on day one.
- Never let a file grow past 40 lines without restructuring. Past that, Claude loses the hierarchy.
- Memory files complement CLAUDE.md, they do not replace it. Rules stay in CLAUDE.md, evolving state goes in memory.
- If a piece of context has not changed in two months, either move it to CLAUDE.md or delete it.
- Write the memory file content in the user's language; keep this skill's own instructions in English.
- Do not create `decisions.md` if the user has no decisions to log — an empty categories hurt more than help.