← Agentic coding The wiring · State

The memory layer

The context window is small and forgets everything when it resets — memory is every trick for making an agent remember across turns, sessions, and projects.

01

Why it's needed

The context window is a fixed budget. When a session ends, it wipes. Anything the agent should still know tomorrow has to live somewhere durable and be loaded back in at the start of the next session. That's the memory layer: a hierarchy from always-in-context rules down to an external service it queries on demand.

Without deliberate memory architecture, every session starts from zero — no knowledge of your codebase conventions, your preferences, or what happened last time. The agent isn't forgetful by design; it's forgetful by default. Memory is the fix.

02

The memory hierarchy

Think of it as a temperature gradient: hot at the top where thinking happens, cold at the bottom where facts are stored permanently. Recall pulls lower layers up into context; write-back pushes new facts down to persist.

Context window volatile · tiny · where thinking happens HOT
↑ recall ↓ write-back
CLAUDE.md / memory files project + user rules · loaded every session
↑ recall ↓ write-back
Session summaries last session's state · injected at SessionStart
↑ recall ↓ write-back
External memory service facts about you · queried on demand · effectively unlimited COLD

Hot, small, and forgetful at the top; cold, vast, and permanent at the bottom.

03

The built-in layer

Claude Code ships with CLAUDE.md as its native memory primitive. It's a Markdown file that gets loaded into context at the start of every session — no configuration required. The hierarchy is:

CLAUDE.md 
# Project rules
@.claude/architecture.md
@.claude/conventions.md

# Quick capture — appended by /remember
Always use pnpm, never npm.
Prefer explicit types over inference in public APIs.

The quick-capture flow — a /remember-style command — appends a new fact to the file in-session. The agent writes its own rules.

04

Cheap-and-static vs rich-and-learned

Two strategies coexist; knowing when to use each one matters.

Written rules

CLAUDE.md — hand-authored, always in context, zero dependencies. You maintain it; it never surprises you. The ceiling is your own effort: if you don't write it, it doesn't know it. Static by design.

Learned memory

An external service like Honcho observes your sessions, stores conclusions about you, and recalls only what's relevant. It evolves on its own, works cross-project, and effectively has no size limit — at the cost of a dependency and less direct control over what it retains.

Both can coexist — written rules for invariants you'll never want to change, learned memory for the living context that shifts as you and your projects evolve.

05

How I actually use it

My setup

I run three tiers. CLAUDE.md holds the hard rules — the things that never change, the conventions I've decided on. Per-project memory files track the state of a given codebase: what's been built, what's in-flight, the architecture decisions that would otherwise evaporate at session end. And Honcho carries who I am across every project — my preferences, my patterns, the context about me that I should never have to repeat. The three tiers don't compete; they stack. Each layer handles what the one above it can't.

06

Sources