The AI's Memory
Claude Code has no memory between sessions. We solved this with a single file that carries architecture decisions, coding patterns, and rules across every conversation.
We use Claude Code, which like all (at time of writing) AI systems, has no memory between sessions. Every time we start a new conversation, it’s a blank slate. When you’re building a complex app over weeks, that’s a problem.
The solution is a file called CLAUDE.md in the project root (similar solutions exist for other AI services such as AGENTS.md for Codex). Claude Code reads CLAUDE.md automatically at the start of every session. It’s the AI’s persistent context, accumulated knowledge of every architecture decision, coding pattern, and hard-won lesson from the entire project.
What’s In It
It captures architectural decisions; the data flow from Views → AppState → Repository → SwiftData → CloudKit, which layers can talk to which, and where business logic lives. It captures coding patterns too; how to handle draft state in SwiftUI views, how to defer state changes safely, and the patterns that keep things consistent across hundreds of files.
There are design system rules in there; colour, spacing, corner radii, typography, fonts, shadows, gradients. There are warnings about the files that break everything if you get them wrong, so the AI treads carefully whenever it sees one.
Then there’s a section of hard rules. Git, sync logic modification approval, running tests after changes. Most importantly, scope discipline; the rule that the AI only changes what the prompt asks it to change.
The Refactor
Our CLAUDE.md started at around 1,300 lines. It grew organically as we added context, patterns, and lessons learned. Eventually it became unwieldy; duplicated information, contradictory guidance, important details buried under noise.
We used Claude to refactor it down to about 370 lines, over 70% smaller. Most of what we cut was ambiguity, and what was left was sharper for it.
Some principles we followed:
- One way to do things, not multiple options
- Show the pattern once, don’t repeat it
- Rules and critical warnings at the top, reference material at the bottom
- Delete anything the AI could figure out from the codebase itself
- Link to separate architecture docs instead of inlining everything
The Payoff
Every session starts with shared understanding. We don’t waste tokens explaining the architecture, and we don’t get suggestions that contradict our patterns. The AI knows what we’ve decided and builds on it.
If anything in this whole pipeline has paid off the most, it’s this. When the AI produces something that violates a pattern, we don’t just ask it to try again; we update CLAUDE.md so the same pattern violation doesn’t keep happening.
The file is a living document. It grows when something genuinely needs to be there, and it gets trimmed whenever it starts accumulating noise.