Memory & Cold Starts

Every new Claude Code session starts from scratch. CLAUDE.md provides rules, STATUS.md provides state, plan docs provide scope — but the working relationship resets. The agent follows rules mechanically instead of with understanding.

The cold-start problem

Three categories of context get lost:

Collaboration calibration. You push back. You want the agent to push back. You prefer options with tradeoffs over a single recommendation. CLAUDE.md can encode this as rules, but a 2,000-turn session follows those rules with understanding. A fresh session follows them mechanically.

Active mental model. Where the project is, what was just tried, what didn’t work and why, which ideas are percolating. STATUS.md captures the state of the work. It doesn’t capture the state of your thinking about the work.

Established trust. By turn 500, you’ve built up a model of when to just do it vs. when to check. A new session is maximally cautious or maximally presumptuous — neither is right.

The first category is the most durable (changes slowly, applies across projects). The second is the most volatile (changes every session). The third is the hardest to capture in text.

The docs/memory.md approach

Michi uses a docs/memory.md file in each project — a portable, repo-committed memory the agent reads at session start. Three sections:

Collaboration. How we work together. Calibration, preferences, confirmed approaches, corrections. “When I say ‘separate what from how,’ I mean extract sub-components by intent, not create utility files.” “Start slow — earn speed within the session.”

Mental model. What you’re thinking about. Active threads, percolating ideas, things tried and abandoned. The state of thinking, not just the state of the work.

Landmarks. Non-obvious project facts, pointers to external systems, key decisions not captured elsewhere. Things a new session would spend time re-discovering.

Boundaries with other docs

• Code patterns → docs/reference/code-style.md
• Project state → STATUS.md
• What happened → docs/journal.md
• How we work together / what would be painful to lose → docs/memory.md

Skill integration

Michi skills read memory at natural points:

• michi-explore reads memory at start (orient before investigating)
• michi-session reads at pre-flight (calibrate before implementing)
• michi-debrief prompts for memory updates (capture what was learned about collaboration)
• michi-sustainability checks memory for staleness (prune what’s now in other docs)

What makes a good memory entry

The litmus test: “what would be painful to lose in a new session?”

Worth remembering:

• “First-epic specs are hypotheses — learned this when the spec referenced a non-existent npm package”
• “When the agent starts too fast, pull back to ‘only take the single smallest next step’”
• “The long-session strategy is deliberate — don’t suggest breaking into smaller sessions”

Not worth remembering:

• “We refactored the auth module” (that’s in git)
• “The project uses React with Zustand” (that’s in CLAUDE.md)
• “We had a long session today” (ephemeral, no applied lesson)

A good memory captures the why, not just the what. It changes how a new session behaves. It isn’t derivable from code, git, or existing docs.

Status

This is a first-generation solution. Claude Code’s own memory system and future cross-session tools will likely improve on this. The docs/memory.md approach is designed to be complementary — portable in the repo, integrated with Michi skills, useful now while better solutions develop.