# Agent memory mini-audit

A 10-minute audit for Claude Code / Codex / agent projects that keep forgetting important context.

## Rule

Memory earns rent. If a note will not change a future decision, it is not memory. It is a log.

## The audit

### 1. List every place context lives

Write down the paths, not vibes:

- Root instructions: `CLAUDE.md`, `AGENTS.md`, `README.md`, etc.
- Project docs: `docs/`, architecture notes, decisions.
- Session logs: closeout files, issue comments, PR notes.
- Tool memory: MCP stores, agent-specific memory files, profiles.
- Private/local overrides: ignored files, local settings.

If you cannot list the sources, the agent cannot reliably obey them.

### 2. Mark each source with a job

Use one job per source:

- Stable rules: commands, constraints, stack, safety boundaries.
- Decisions: choices that should survive a month.
- Logs: what happened in a session.
- Receipts: test output, links, IDs, deploy URLs.
- Scratch: temporary notes.

Most memory failures are not forgetting. They are role confusion.

### 3. Delete or demote rented-space thieves

Move these out of memory:

- Raw transcripts.
- Stale plans.
- Completed TODOs.
- Long error dumps after the fix is understood.
- Preferences that only applied once.
- “Remember to do X” notes with no durable rule behind them.

Keep them searchable if useful. Do not keep them injected.

### 4. Add dates and owners

Every durable note should answer:

- When was this true?
- Who or what decided it?
- What would make it obsolete?

Stale memory is worse than no memory because it sounds authoritative.

### 5. End every meaningful session with a closeout

Use this prompt:

```text
Before we stop, write a compact closeout.
Update durable memory only for rules or facts that will still matter in a month.
Append the session log with changed files, decisions, verification, and open questions.
Do not paste the transcript. Distill the state.
```

## Pass/fail

Pass:

- Your root memory is short enough to scan.
- Current work is in a log, not immortal memory.
- Decisions have dates and reasons.
- Verification receipts point to actual commands or URLs.
- You know what to delete next.

Fail:

- The agent has to read a wall of stale text before acting.
- Memory, docs, logs, and receipts are mixed together.
- You keep adding “just one more note” because retrieval is unreliable.

## My bias

Start boring: three markdown files beat an overbuilt RAG stack you do not maintain.

- `CLAUDE.md` / `AGENTS.md`: stable rules and map.
- `docs/session-log.md`: what happened.
- `docs/decisions.md`: choices that should outlive the session.

Then automate only the parts you actually repeat.