Memory architecture

What memory is

Your AI sessions don\u2019t remember each other by default. Every new session starts blank. CLAUDE.md is the layer that fixes that for project-level facts. Memory is the layer for everything else \u2014 your role, your preferences, the state of work across multiple ventures, the rules you\u2019ve adopted from past corrections, references to things that live in other tools.

Memory is structured as MEMORY.md at the root of a memory folder, plus a set of detail files it links to. MEMORY.md is an index: one-line entries that load on every session, each pointing to a detail file the agent fetches when relevant. The index stays in front of the agent always; the details are just-in-time.

Most people get the split wrong by putting too much in the index, or by storing ephemeral work-in-progress as if it were permanent context. Both produce a memory layer that loads slowly, ages badly, and the agent eventually starts ignoring.

The 100-line story

I let MEMORY.md grow to 50 lines before I noticed. Sessions got slower to start; the agent started missing things that were technically \u201cin memory\u201d but buried in noise. I pulled the file open and audited it line by line.

About 60% of the lines weren\u2019t pulling weight. Some described project state from a month earlier (the v8 model that had since become v9). Some described work-in-flight that belonged in a sprint contract. Some were bare wikilinks with no description, which meant the agent had to load the linked file just to know what was in MEMORY.md.

I cut to 18 lines. Each remaining line answers why would I open this on a future session? \u2014 not what is in this file? The token cost of a fresh session dropped to about a third. More importantly, the lines that survived now actually load-bear: the agent uses them.

The discipline that produced this isn\u2019t complicated. It\u2019s a single rule applied at insert time and re-applied at monthly audit. This lesson is that rule.

Three ways memory fails

Hover any card to see the diagnosis.

The fix is the same in all three: memory is the index, not the document. Each entry in MEMORY.md is one line that loads always; details live in linked files fetched only when needed.

The load-test

The diagnostic to apply when adding to memory or auditing existing memory:

For each line in this MEMORY.md, ask:
"Does this fact need to be in front of every agent session, or is
it fine to fetch when relevant?"

Classify each line as:
- KEEP       — yes, the agent needs this loaded by default
- FETCH      — only relevant in some sessions; belongs in wiki / decision log
- STALE      — describes a state that has changed since this line was written
- EPHEMERAL  — work-in-flight; belongs in a sprint contract or plan file

Output a triaged MEMORY.md and a list of the lines I should move
elsewhere.

The output buckets every line into four classes:

• KEEP \u2014 the agent needs this loaded by default. Earns a place in MEMORY.md.
• FETCH \u2014 only relevant in some sessions. Wiki, decision log, or wikilink the agent loads when relevant.
• STALE \u2014 describes a state that has since changed. Delete or rewrite.
• EPHEMERAL \u2014 work-in-flight. Move to a sprint contract or plan file.

A healthy MEMORY.md sits at 15\u201330 lines. Anything north of 50 means the load-test isn\u2019t being applied at insert time.

Annotated transcript

A real audit conversation. Click any pinned annotation under an agent reply to expand the commentary.

Four memory types

Every memory entry classifies as one of four types. The type tells you where the entry lives, when it gets updated, and how the agent uses it.

If you can\u2019t classify an entry into one of the four, it probably doesn\u2019t belong in memory. Three things people try to put in memory that don\u2019t belong:

• Code patterns or conventions. Belong in CLAUDE.md if project-wide, or in a decision log if a single choice.
• Recent commits or git activity. The git log is authoritative. Memory shouldn\u2019t duplicate it.
• Debugging fixes. The fix lives in the code; the why-it-broke lives in a postmortem. Memory doesn\u2019t need to summarize either.

MEMORY.md skeleton \u2014 drop this in your project

The whole MEMORY.md is an index. Each entry is one line. Detail lives in the linked files.

# Memory

> Long-running context that persists across sessions. Read at the start
> of every session. Updated when state changes.
>
> This is an index — keep entries to one line. Detail lives in linked files.

## Operator profile
- [Operator profile](memory/operator-profile.md) — role, priorities, working style

## Projects
- [Project A](memory/projects/project-a.md) — current state, milestones, open issues
- [Project B](memory/projects/project-b.md) — current state, milestones, open issues

## People
- [Key contacts](memory/people/key-contacts.md) — most important relationships, last contact, next step

## Reference
- [Glossary](memory/glossary.md) — acronyms and domain terms
- [Compliance reference](memory/context/compliance.md) — tax / hiring / regulatory by state

## Active feedback / preferences
- (Add lines here as preferences emerge that should persist across sessions.)

## What NOT to save here
- Code patterns, conventions, file paths — derivable from current state
- Git history, recent changes — \`git log\` is authoritative
- Debugging solutions — fix lives in code; why lives in a postmortem
- Anything already in CLAUDE.md
- Ephemeral task details — those belong in the inbox or sprint contracts

Memory captures **state**, not **action**.

5\u20137 sections, one line per entry, every line links to a detail file when needed. Keep MEMORY.md itself short \u2014 15\u201330 lines is the right size.

Prompt kit

Three prompts for keeping memory healthy. Save in your CLAUDE.md or personal snippets file.

For each line in this MEMORY.md, ask:
"Does this fact need to be in front of every agent session, or is
it fine to fetch when relevant?"

Classify each line as:
- KEEP       — yes, the agent needs this loaded by default
- FETCH      — only relevant in some sessions; belongs in wiki / decision log
- STALE      — describes a state that has changed since this line was written
- EPHEMERAL  — work-in-flight; belongs in a sprint contract or plan file

Output a triaged MEMORY.md and a list of the lines I should move
elsewhere.

I want to save this to memory: "<the fact>"

First, classify it as one of:
- user        (preference, role, working style)
- project     (state of an ongoing venture or workstream)
- feedback    (a correction or rule the user wants to persist)
- reference   (pointer to where information lives in another tool)

Then check: does this fact change agent behavior across many future
sessions? If no, propose where it should go instead (wiki, decision
log, sprint contract). If yes, write the one-line entry for
MEMORY.md plus the detail file it links to.

Walk every line in MEMORY.md plus the linked detail files.

For each, check whether the claim is still true:
- Verify against current code state for project memories
- Check timestamps — anything not updated in 60+ days needs review
- Cross-reference against recent decision logs

Output a list of:
- Lines to update (with the new wording)
- Lines to delete (with reason)
- Lines to keep as-is

Apply this

20-minute exercise. Audit or create a MEMORY.md. The discipline is one rule applied at insert time + a monthly cadence.