Memory Architecture
The MEMORY.md index pattern. Four memory types, a staleness protocol, and the one rule that stops memory systems from becoming archives.
- Four memory types: user, feedback, project, reference — each with its own shelf life
- Staleness protocol with date-stamp conventions and prune cycle
Every Claude Code session starts cold. The agent reads what's in front of it and starts from there. For anything running past the first week — ongoing projects, evolving decisions, people that matter, rules that came from real failures — starting cold means re-establishing context that already exists somewhere.
The session-tax is real. I tracked it for two weeks in March: I was spending 10-15 minutes per session re-explaining things I'd already explained. Not because the agent was bad. Because I had no persistent memory layer. Every session was the first session.
The MEMORY.md index pattern fixed this. Two months in, sessions start in context. The re-explanation tax is near zero.
The index pattern
One file, always loaded: memory/MEMORY.md. It's an index — one line per memory file, describing what's in it. The agent reads the index to decide which files are relevant, then loads those.
markdown
- [User Profile](user-profile.md) — Michael Brenneman, CEO TruPath, two portfolio companies
- [QC Project](projects/quantum-caddy.md) — Phase 0 status, CV test plan, patent priorities
- [MHG Project](projects/mile-high-golf.md) — Denver site, SBA loan, launch timeline
- [Feedback: codebase boundary](feedback-codebase-boundary.md) — Vault work never edits QC code directly
The description after the dash is the filter. It's what the agent reads to decide whether to load the full file. "User profile" isn't enough; "Michael Brenneman, CEO TruPath, two portfolio companies" tells the agent when this file is relevant. Write descriptions as filters, not labels.
The index has a hard limit: after 200 lines, the overhead of loading it starts to cost more than it saves. Keep it short. Prune aggressively.
Four memory types
User — who the operator is, how they think, what they care about. In a solo operation this sounds unnecessary. It isn't. It captures expertise level, working style, and domain background that change how an agent explains something. An agent that knows you're a CEO-not-engineer explains a schema decision differently than one that doesn't.
Feedback — corrections and confirmed approaches. When you say "no, don't do it that way" — that's a feedback memory. When an unusual approach worked and you didn't push back — that's also a feedback memory. Lead with the rule, then explain why. The "why" is what lets the agent apply the rule to edge cases instead of following it blindly.
Project — current state. Who's doing what, what's active, what's dead, what's blocked. Project memory has a short shelf life. The site changes. The decision gets reversed. An item about a site in active negotiation is load-bearing today and noise in three months.
Reference — pointers to external systems. Not content — location. "Pipeline bugs tracked in Linear project INGEST." "Grafana board at grafana.internal/d/api-latency is the oncall dashboard." Reference memory decays slowly — external systems change their locations rarely — but when they do change, stale reference memory sends you to the wrong place.
The staleness problem
Memory files become wrong. Stale project memory is worse than no memory — an agent acting on stale state works on a dead path with full confidence.
Two practices keep staleness under control.
Verify before recommending. If a memory file names a specific file, function, or URL, check it exists before citing it. "The memory says X" is not the same as "X exists now."
Date-stamp and prune. Project memory files get a last-verified: date in frontmatter. Anything older than 30 days without a verification pass is suspect. The monthly prune takes 15 minutes.
What not to save
This is the part most operators skip. Memory systems grow. Without pruning rules, they become archives.
Don't save: code patterns or conventions (they're in the code — read the code); git history or recent commits (use git log); architectural details visible in the codebase; ephemeral session state; debugging fixes or recipes.
The test: if a fresh agent could find the information by reading current files or running a standard command, don't save it. Memory is for what's invisible to the codebase — relationships, preferences, decisions, and rules that came from real incidents.
The average mature memory directory has 15-20 files. Most operators who don't prune end up with 60-80 files, most of which are never loaded. The session-tax drops below zero when the index becomes too expensive to read.
— Michael, from the lab