Building Persistent Memory for Claude Code Agents with CLAUDE.md
CLAUDE.md Is the Only Memory That Matters
Every Claude Code session starts fresh. No memory of what happened last time. No recollection of decisions made, bugs fixed, or patterns established. The context window is blank.
Except for CLAUDE.md.
The Memory Problem
When you run 5 Claude agents in parallel on a desktop app, each one needs to know things that are not in the code. Which files belong to which module. What the build command is. Why a particular workaround exists. What to do when another agent's changes break the build.
Chat history does not transfer between sessions. Extended thinking vanishes. The only thing that persists is what is written to disk - and CLAUDE.md is what Claude reads first, every time.
What Goes in CLAUDE.md
The most effective CLAUDE.md files contain information that cannot be derived from reading the code:
- Coordination rules - "If you see build errors in files you did not edit, wait 30 seconds and retry"
- Module ownership - "Agent working on accessibility owns src/accessibility/. Do not modify."
- Non-obvious patterns - "Use distributed notifications for testing, not UI automation"
- Project-specific gotchas - "ScreenCaptureKit requires entitlements that Xcode does not add by default"
What Does Not Belong
Anything Claude can figure out by reading the codebase is wasted context. Do not list your dependencies. Do not describe your file structure. Do not explain what Swift is. Every token spent on derivable information is a token stolen from useful context.
Memory That Evolves
The best CLAUDE.md files are living documents. When an agent discovers a new gotcha - a deprecated API, a build flag that matters, a race condition pattern - it gets added. The next session benefits immediately. This is persistent memory that actually compounds over time.
- CLAUDE.md - The Most Important File in Your Project
- Claude Code Auto Memory vs Explicit Specs
- AI Agent Persistent Memory Every Session
Fazm is an open source macOS AI agent. Open source on GitHub.