---
name: memory-management
description: Use when deciding where information lives across sessions — project memory (CLAUDE.md) vs docs-as-memory (specs, ADRs, assumptions) vs user memory — and rehydrating context on resume.
---

# Memory Management: What Lives Where, and How to Rehydrate

## When to use
- You learned something durable (a decision, an assumption, a constraint, a risk) and must decide where to record it.
- You are starting a session on an existing project and need to reconstruct prior context.
- `/continue-work` is invoked, or the user asks "where were we / what did we decide".
- Project memory (`CLAUDE.md`) is getting bloated, contradictory, or used as a scratchpad.
- You need to separate project-specific facts from user-wide preferences.

This applies to every project type. The three tiers below are universal; only the contents differ. See `.claude/docs/MEMORY_STRATEGY.md` for the full model.

## Workflow
1. **Classify the information into a tier.**
   - **Project memory** (`.claude/CLAUDE.md` constitution + the repo's own `CLAUDE.md`): durable project *law and conventions* — flow rules, safety constraints, stack conventions, where artifacts live. Short, stable, project-agnostic where possible. Not a log; not a notepad.
   - **Docs as long-term memory** (`docs/`): the project's *evolving record* — specs (`docs/specs/`), architecture (`docs/architecture/overview.md`), decision records (`docs/decisions/`), the assumptions log (`docs/state/assumptions.md`), known risks, and run state (`docs/state/`). This is where the "why" and the history live.
   - **User/global memory** (the user's private global instructions and auto-memory, outside the repo): preferences that span *all* projects — tone, tooling habits, identity. Never put project secrets or project-specific scope here; never copy global preferences into a shared repo.
2. **Write at the moment of decision, not retroactively.** When you pick a database, an auth model, a retention period, or a default — record it immediately. Architectural choices get a decision record from `.claude/templates/decision-record.md`; smaller judgment calls get an entry in `.claude/templates/assumptions-log.md`. Rule of thumb: if a reasonable senior engineer might have chosen differently, log it (`.claude/CLAUDE.md` §7).
3. **Keep each tier clean.** Promote a recurring, stable fact from docs into project memory only once it is truly a convention. Demote stale or one-off notes out of `CLAUDE.md` into a dated doc. Resolve contradictions rather than appending a new contradicting line.
4. **Never store secrets in any memory tier.** Credentials, tokens, and `.env*` contents stay in a secret manager — referenced, never written into `CLAUDE.md`, `docs/`, or global memory (`.claude/CLAUDE.md` §8).
5. **Rehydrate on resume (the continuation workflow).** When `/continue-work` runs, read in order: the project `CLAUDE.md`, then `docs/state/` (run state, active team, assumptions), then the latest specs and decision records, then `git log`/`git status` for what actually changed. Reconstruct *where in the 9-stage flow* the project sits before acting.
6. **Reconcile memory with reality.** If `docs/` claims a feature is done but the code or tests disagree, trust the code, flag the drift, and update the doc. Memory that contradicts the repo is a bug to fix, not a fact to follow.
7. **Surface memory at gates.** Re-present the assumptions log and open decisions at each stage gate so the user can cheaply correct course.

## Standards
- **Do** keep `CLAUDE.md` short, stable, and about rules/conventions; keep history and rationale in `docs/`.
- **Do** record decisions and assumptions immediately, each with alternatives, rationale, blast radius, and reversal.
- **Do** put cross-project preferences in user/global memory and project facts in the repo.
- **Do** write run/continuation state to `docs/state/` so the next session can rehydrate deterministically.
- **Do-not** store secrets, tokens, or `.env` contents in any memory tier.
- **Do-not** use `CLAUDE.md` as a chat log or dumping ground; do-not let it contradict itself.
- **Do-not** copy project-specific scope into global memory, or global preferences into a shared repo.
- **Do-not** trust a doc over the code when they disagree — reconcile and fix the doc.

## Common mistakes to avoid
- Capturing a decision only in chat — if it is not in `docs/` or `CLAUDE.md`, it is lost next session.
- Letting `CLAUDE.md` balloon with transient notes until it is too long to be read fully.
- Recording an assumption with no reversal path, so a wrong call is expensive to undo later.
- Putting an API key or DB URL "temporarily" into a doc or memory file.
- Resuming work from chat scrollback instead of `docs/state/`, and missing a prior decision.
- Treating stale `docs/` as ground truth after the code moved on.

## Output format
A clear placement decision (which tier, which file) and the written artifact: a decision record (`.claude/templates/decision-record.md`) for architectural calls, or an assumptions-log entry (`.claude/templates/assumptions-log.md`) for smaller ones, saved under `docs/`. For continuation, a short "where we are" summary: current flow stage, what changed since last session (from `git` + `docs/state/`), open decisions/assumptions, and the next safe step.

## Related agents
- `.claude/agents/core/orchestrator.md`
- `.claude/agents/core/documentation-writer.md`
- `.claude/agents/core/project-manager.md`

## Related skills/docs/checklists
- `.claude/docs/MEMORY_STRATEGY.md`
- `.claude/skills/documentation/SKILL.md`
- `.claude/templates/decision-record.md`
- `.claude/templates/assumptions-log.md`
- `.claude/commands/continue-work.md`