in the prompt
# quick-add
Start a message with # and Claude appends it to the right memory file — the fastest way to teach a durable rule mid-session.
Deep dive · 2 of 2
How Claude Code remembers.
If Codex treats memory as a pipeline, Claude Code treats it as a library of files you can read. Memory here is human-first: a hierarchy of plain-Markdown instructions plus a model-managed directory of facts — everything diffable, version-controllable, and yours.
This is the technical companion to the Codex teardown. Read both, then the comparison — the two philosophies are nearly opposite, and the best system borrows from each.
Codex's memory is something a worker processes. Claude Code's is something a human reads. One optimizes for pipelines; the other for trust and editability.
01 / 06 — the thesis
Files first, by design.
Claude Code's memory is not one store but two cooperating ideas, both file-based:
- Instruction memory —
CLAUDE.mdfiles that are loaded into context at the start of every session. Always-on, hierarchical, the "house rules." - Recalled memory — a
memory/directory of small fact files the model reads and writes on demand, surfaced by relevance during a session.
Both are just text on disk. There's no opaque database, no embedding blob you can't inspect. You can cat any of it, edit it by hand, commit it to git, and move it between machines. That legibility is the design philosophy.
02 / 06 — instruction memory
The CLAUDE.md hierarchy.
Instruction memory cascades from broad to specific, and it composes — every layer in scope is concatenated into context at launch. Lower, more-specific files refine the ones above them.
load order · broad → specific
enterprise policy /Library/.../ClaudeCode/CLAUDE.md (org-managed) ▼ user memory ~/.claude/CLAUDE.md (all your projects) ▼ project memory ./CLAUDE.md (checked into the repo) (the team) ▼ local / subtree ./sub/dir/CLAUDE.md (loaded when relevant)
Two mechanics make it powerful:
- Imports. Any file can pull in another with
@path/to/file.md— recursively, several hops deep — so you compose memory instead of writing one monster file. - Always-on. Unlike recalled memory, these are in context from token one. That makes them perfect for standing rules and conventions — and costly if you let them bloat.
On this machine the user layer (~/CLAUDE.md) is the home-base operating manual — startup ritual, the agent fleet, comms rules. The project layer governs each repo's conventions.
03 / 06 — recalled memory
The memory directory.
The second system is a model-managed folder of small, single-fact files with structured frontmatter, plus a MEMORY.md index that's loaded each session. The model reads the index, decides which facts are relevant, and pulls them in — and writes new ones as it learns. Recall by relevance, not by always-on bulk.
The index. One line per fact, loaded every session. Cheap to scan; the model expands only what's relevant. Pointers, never the full content.
# Memory Index
## Feedback
- [feedback_pace.md](feedback_pace.md) — one chunk at a time, no scope creep
- [feedback_db_retrieval.md](...) — query the DBs mid-task, don't rely on context
## Projects
- [project_agent_fleet.md](...) — fleet roster + upgrade path
## Reference
- [design-system.md](...) — locked tokens + components
One fact, one file. Frontmatter classifies it; the body holds the fact, with [[links]] to related memories. The model writes these as it learns, then adds a pointer to the index.
--- name: feedback-pace description: process one chunk at a time; avoid scope creep metadata: type: feedback --- Don't rush. Finish one chunk before starting the next. Why: rushing produced half-done work that needed redoing. How to apply: ship a slice, confirm, then continue. See [[feedback-db-retrieval]].
The frontmatter type — user · feedback · project · reference — is how the model decides what a memory is for. It's a lightweight classification, not a provenance ledger (no fact-vs-inference status) — a gap the portable layer closes.
04 / 06 — the controls
How memory gets written.
Three human-facing levers, all of which just edit files:
slash command
/memory
Open the memory files in your editor to review, prune, or rewrite by hand. Memory you can audit and curate.
bootstrap
/init
Scaffolds a project CLAUDE.md by scanning the repo — a starting set of house rules to refine.
autonomous
model writes
The model adds fact files + index pointers on its own as it learns, then a consolidation pass keeps the set deduped.
05 / 06 — in practice
This machine, layered up.
The home-base setup shows the model's intended shape — and where people bolt on more. Three tiers, increasingly structured:
- CLAUDE.md — standing instructions and active mandates (always-on).
- memory/ dirs — per-project
MEMORY.md+ fact files; each fleet agent (data-miner, the briefing agents) has its own, so recall is scoped per agent. - a custom store — SQLite + a Kuzu graph, reached through a helper. This is not native Claude Code; it's a bolt-on, added precisely because files alone don't give you queryable, relational, provenance-tracked recall.
That third tier is the tell: file memory is excellent for instructions and human-curated facts, but the moment you need a ledger, a promotion gate, or graph relationships, you reach for a database. Which is exactly the Fleet Memory v2 argument.
06 / 06 — the verdict
What's brilliant, what's missing.
✓ Human-legible
Every memory is plain Markdown you can read, edit, and trust.
✓ Version-controlled
Project memory lives in git with the code — reviewable in PRs.
✓ Hierarchical + composable
Enterprise → user → project, with @imports. No monster file.
✓ Relevance recall
The memory tool pulls only what matters, not the whole bulk.
– No pipeline / ledger
No leased, retryable workers — consolidation is best-effort.
– No provenance status
type classifies, but nothing marks fact vs inference vs refuted.
– Per-harness, per-machine
It's on your disk, in Claude's format — not shared with Codex or Grok.
– Scaling pressure
Always-on CLAUDE.md competes for context; big sets need discipline.
The strengths are the inverse of Codex's, and so are the gaps. That's the whole reason the next page exists.