An Auto Memory Index That Grew Out of Control

1. What's gone wrong, mechanically:

MEMORY.md is supposed to function as a concise index: the first 200 lines or 25KB of it (whichever limit is hit first) are loaded at the start of every session, and it's meant to hold roughly one line per entry, linking out to topic files for detail. This file is doing the opposite — it's accumulating full paragraphs of detail directly in the index (the JWT/auth entry alone runs several lines and trails off into "also there's a known issue where..."), and at 260+ lines it is almost certainly already past the 200-line cutoff. That means a meaningful fraction of this file — quite possibly including information the engineer actually needs — is not being loaded into context at session start at all; it's silently invisible past the cutoff. Claude Code does try to catch this: when Claude writes to MEMORY.md and the file is near or over the limit, Claude Code either reminds it to shorten the file or returns an error telling it to rewrite the index — but that mechanism clearly hasn't been effective here, since the file kept growing past the point where it should have been split.

2. What it should look like instead:

MEMORY.md should shrink to short, single-line pointers, with the actual substance moved into topic files that are read on demand rather than loaded at every session start:

# Memory Index

## Project
- [build.md](build.md): ~40s clean build, faster with cache
- [staging-redis.md](staging-redis.md): read-after-write staleness (~2s)

## Preferences
- Arrow functions for one-off callbacks in .map()/.filter()

## Reference
- [auth-debugging.md](auth-debugging.md): JWT issuer mismatch, clock skew

With staging-redis.md, auth-debugging.md, etc. holding the actual paragraphs of detail. Those topic files have no size limit of their own — they're not loaded at startup, only read on demand with normal file tools when a task relates to them — so this isn't about losing information, it's about which information pays a "loaded every session, whether relevant or not" tax versus which is available but only fetched when actually needed. The arrow-function preference is short enough to stay inline in the index as-is; not everything needs to be split into its own file, just the entries that are already multi-line or growing.

3. The misplaced entry:

The arrow-functions bullet — "User asked to always use arrow functions instead of function declarations for one-off callbacks" — is a stated preference/rule, not a discovered fact about the codebase or a debugging insight. Depending on how durable and team-relevant it is, it's arguably misfiled in auto memory at all, not just poorly formatted within it. If this is meant to be an actual team convention (not just this one engineer's personal taste), it belongs in the project's committed CLAUDE.md (or a .claude/rules/ file scoped to relevant source files) where it's reviewed, shared with the team via git, and doesn't depend on every other engineer's local auto memory happening to contain the same note. Auto memory is machine-local by construction — a preference recorded there only shapes this engineer's sessions, on this machine, and says nothing to a teammate cloning the repo fresh. Recall the earlier distinction: when you tell Claude to remember something in chat, Claude defaults to writing it to auto memory unless you explicitly ask for it to go into CLAUDE.md instead — so this is exactly the failure mode where that default was probably wrong for what the engineer actually wanted.