Memory & Persistent Context Beyond CLAUDE.md

CLAUDE.md is context you write deliberately, up front, about the project as a whole. It’s not the only way Claude Code can carry information across sessions — a complementary memory system exists specifically for facts that are more naturally learned during actual work than authored in advance.

Two Different Kinds of Persistence

CLAUDE.md is authored: you (or the team) sit down and decide what’s worth documenting, and it applies uniformly to every session in that project or for that user. It’s best suited to durable, stable facts — commands, conventions, architecture.

Memory is accumulated: individual facts captured over the course of working together — a preference you expressed mid-conversation, a correction you made to how the agent approached something, context about an ongoing piece of work that isn’t really a “project convention” but is still worth remembering next time. This is a genuinely different kind of information than what belongs in a hand-maintained CLAUDE.md, and forcing it into that file would make CLAUDE.md itself bloated and constantly-churning — exactly the anti-pattern covered in Common CLAUDE.md Mistakes & Anti-Patterns.

What Tends to Fit Each

CLAUDE.md                              Memory
─────────────────────                  ─────────────────────
"We use Vitest, not Jest"              "This user prefers terse
                                         responses without a
                                         trailing summary"

"legacy/ is deprecated,                "We're mid-migration off
 don't add new code there"              the legacy auth system,
                                         targeting end of quarter"

"Run `npm test -- <file>`              "Last time, this exact
 for a single test file"                approach to the retry
                                         logic was explicitly
                                         rejected — don't suggest
                                         it again"

The left column is stable and applies to anyone working in the project. The right column is either personal (how you specifically like to work) or time-bound (true right now, not necessarily in six months) — the kind of thing that’s genuinely awkward to maintain as hand-written prose in a committed file, but valuable to have carried forward automatically.

Why the Split Matters

Putting memory-shaped content into CLAUDE.md creates two problems: it makes the file grow unboundedly as every session-specific learning gets manually appended, and it mixes team-shared, deliberate documentation with personal or transient facts that shouldn’t necessarily apply to every other person using the same project’s CLAUDE.md. Keeping them separate means CLAUDE.md stays a curated, reviewed document, while memory absorbs the accumulating, lower-ceremony learning that happens naturally through actual use.

When to Manually Promote a Memory Into CLAUDE.md

Some facts start as a one-off memory and later prove durable and general enough to deserve promotion into the actual committed file — the signal is usually repetition: if the same correction or preference keeps recurring across many sessions and clearly isn’t personal or transient, it’s likely become a genuine team convention worth writing into CLAUDE.md deliberately, rather than continuing to rely on it being recalled from memory each time.

<!-- Started as: "this user corrected the agent's approach to error handling
     in three separate sessions" (a memory pattern) -->

<!-- Promoted to CLAUDE.md once the pattern was clearly a team convention: -->
## Error Handling
- Never catch and silently swallow errors in request handlers — always log
  with a request ID and re-throw or return a typed error response.

Common Mistakes

Treating memory as a substitute for writing CLAUDE.md at all. Memory captures what’s learned incidentally; it doesn’t replace the value of deliberately authoring the project’s core commands and conventions up front — a project with excellent memory accumulation but no CLAUDE.md still starts every fresh context without the basics.

Manually copying every memory into CLAUDE.md “to be safe.” This defeats the purpose of having two separate mechanisms — if everything ends up in CLAUDE.md regardless, you’re back to a single, ever-growing file with no distinction between curated and incidental content.

Expecting memory to apply the same way across different projects when it was actually project-specific. Personal preferences (communication style) reasonably apply everywhere; project-specific learnings (a rejected approach for a particular codebase’s retry logic) shouldn’t leak into unrelated projects.

Frequently Asked Questions

Does memory replace the need for a well-written CLAUDE.md? No — they’re complementary. CLAUDE.md remains the right home for stable, deliberately-authored, team-shared context; memory handles what accumulates through use and doesn’t need the same review/commit ceremony.

Is memory shared across a team the way a committed CLAUDE.md is? Generally no — memory tends to be tied to the individual working context, which is exactly why genuinely team-wide learnings should eventually get promoted into the committed CLAUDE.md rather than staying only in one person’s accumulated memory.

Can memory go stale the same way CLAUDE.md can? Yes, in principle — a memory captured under circumstances that later changed can become just as misleading as a stale line in CLAUDE.md, which is part of why genuinely important, durable facts are better served by being reviewed and promoted into the maintained file rather than relied on indefinitely as an unreviewed memory.

Summary

CLAUDE.md and memory solve adjacent but distinct problems: one is deliberately authored, reviewed, team-shared, and durable; the other accumulates incidentally from actual work, is often personal or transient, and requires no upfront ceremony. Recognizing which kind of information you’re dealing with — and promoting genuinely durable, repeated patterns from memory into CLAUDE.md when they earn it — keeps both mechanisms doing what they’re actually good at.