Writer’s Brief

The Hook

I discovered that 15 lines of my Claude Code memory file were being silently dropped every single session. No error, no warning. Just gone.

Main Points to Cover

  1. How Claude Code’s memory system actually works under the hood (it’s not a system prompt, it’s injected as a “system-reminder” in user messages with a disclaimer that says your instructions “may or may not be relevant”)
  2. The 200-line hard cap on MEMORY.md that nobody talks about, and the compliance data showing monolith files at 92% vs modular rules at 96%
  3. The refactor: splitting a 197-line monolith into 7 focused rule files, compressing 215 lines of memory to 78, and adding a hook that force-loads learnings every session

The Angle

Personal discovery / problem solved. “I built this elaborate memory system for Claude and it was working… mostly. Then I looked under the hood.”

Target Reader

Claude Code power users who have a CLAUDE.md file and suspect it’s not being followed consistently. People who’ve put effort into customizing Claude and want it to actually stick.

Tone Notes

Casual, a little surprised/amused at the silent truncation. Technical but not dry. The vibe of “I found a bug in my own setup and here’s how I fixed it.” Show the before/after numbers.

Raw Material / Moments to Write From

These are notes for Alex to write from. Not prose.

  • The silent truncation: MEMORY.md was 215 lines. Hard cap is 200. The last 15 lines (Chrome automation notes, Gmail MCP quirks) were being dropped EVERY SESSION with zero indication. I only found out by researching how the system actually works.
  • The compliance numbers are real data from community testing: <200 lines = 92% rule application rate. Modular rules (~50 lines each) = 96%. Over 400 lines = 71%. Small focused files beat big monoliths.
  • The “may or may not be relevant” disclaimer: Anthropic wraps your CLAUDE.md content in a system-reminder that literally tells Claude your instructions might not matter. GitHub issue #7571 was filed about this. Closed as NOT PLANNED. The workaround: put “IMPORTANT: These instructions OVERRIDE” at the top. Or use hooks, which bypass the disclaimer.
  • The three-tier architecture that emerged: CLAUDE.md = rules (always do this), MEMORY.md = state (here’s what’s going on), learnings.md = growth (what went wrong and right). Most people dump everything into CLAUDE.md.
  • The before/after is satisfying: 197-line monolith → 56-line index + 7 rule files. 215-line truncated memory → 78-line compressed memory + 2 topic files. learnings.md went from “Claude might read it” to “guaranteed loaded via hook.”
  • Five expert perspectives were generated (Simon Willison, Swyx, Karpathy, @steipete, Dan Shipper) to evaluate the setup. Deployed as interactive HTML to here.now. Dan Shipper’s take: “The emotional memory is your secret weapon.” Most people’s memory files are purely technical. Mine include how to handle me when I’m anxious. That’s a relationship, not configuration.
  • The @import trick: CLAUDE.md supports @path/to/file syntax that makes referenced files first-class citizens instead of just path strings Claude might or might not follow up on.
  • Meta-moment: used the memory system to audit itself. Claude researched how its own memory works, reviewed its own config files, and restructured them. The tool improved the tool.