The Auto-Memory System

Chapter 1 drew a firm line between memory and rules files: rules are for conventions meant to apply identically, forever, to every course; memory is for the kind of thing that's specific to one conversation or learned gradually over time. This chapter takes that distinction seriously and looks at the memory system itself in the same detail the earlier chapters gave the rules files — including a real, honest case where the two systems overlap more than they probably should.

Where It Lives, and Why It's Still File-Based

Memory in this project is itself a persistent, file-based system, living in its own dedicated folder separate from this repository's own rules/ tree. That's worth noticing: memory isn't some opaque, unreadable internal state — it's plain files too, just organized around a different question than a rules file asks. A rules file asks "what should always be true?" A memory file asks "what have I learned about this specific user, this specific project, or where to find something, that's worth carrying into a future conversation?"

The Four Memory Types

The Two-Step Save Process

Saving a memory is never a single write. First, the memory itself gets its own file, with a small frontmatter block naming it, describing it, and tagging its type:

Second, a single-line pointer gets added to MEMORY.md — the always-loaded index every future session actually reads. A memory file that exists but was never added to that index is exactly as invisible as a rules file that exists but was never added to CLAUDE.md's own @rules/ list from Chapter 1 — the same "one step, easy to forget" failure shape, one level down.

What Doesn't Belong in Memory At All

Code patterns, architecture, and file paths are excluded on purpose — they can be derived by reading the current project state directly, and a memory claiming to know them risks going stale the moment the code actually changes. Debugging solutions are excluded too, for the same reason: the real fix lives in the code itself and the commit message, not in a separate remembered description of it that could drift out of date.

Before Recommending From Memory

A memory that names a specific file, function, or flag is a claim that it existed when the memory was written — not a guarantee it still does. Before acting on it, the same discipline every earlier chapter has already applied to rules files applies here too: check the file still exists, grep for the function, verify the flag before recommending it. "The memory says X exists" and "X exists now" are two different claims, and only the second one is safe to act on.

Coding Challenges