Honey Memory

Lever 2 applied to discovery cost. Every cold session re-greps the same things — where auth lives, the build command, why X is shaped Y. One committed file replaces N rediscovery round-trips with a single cached read, on every future session. The cheapest token is the one not re-derived.

The win is per-session and recurring. The risk is staleness — a wrong cached fact costs more than no file. So the file lives in git, next to the code that can invalidate it, and is fixed in the same change that breaks it.

Scaffold (create)

1. One file per repo: PROJECT.md at the root, committed (not ~/.claude). If the repo already has CLAUDE.md/AGENTS.md, add/refresh a ## Memory section there instead — don't add a second file.
2. Back up before overwriting an existing file: copy → FILE.original.md. If that backup already exists, stop and ask. Never clobber a restore point.
3. Write only three kinds of fact (derive by reading the repo):
   • Architecture + conventions an agent can't cheaply grep — where things live, and why (the intent, not the file list).
   • Build / test / run commands, env, and gotchas.
   • Decisions and dead-ends — choices made, paths tried and rejected. This is intent; it is never in the code.
4. Report what was written and the file path.

Never store

• Anything derivable from source — code structure, symbol locations, past fixes, git history. Re-deriving is cheaper than maintaining, and never stale.
• Secrets, tokens, credentials. The file is committed.
• Transient state — open TODOs, this-week status. That rots fastest.

If a fact is stable + expensive-to-rediscover + not-in-the-code, write it. Everything else, let agents derive on demand — caching it is where these systems quietly lose money.

Update

A markdown file does not update itself. Reliability = discipline, not infra:

• Same-change rule (primary). When code changes invalidate a fact, fix the fact in the same commit. Review catches drift because the file is in git.
• On-demand refresh. Re-read the repo and rewrite stale entries; show the diff. Don't blind-append — appending is how these files bloat and rot.
• Lint before and after a refresh. node "${CLAUDE_PLUGIN_ROOT}/bin/check.js" memory (no model) finds paths the file names that no longer exist, @imports that load nothing, the same rule loaded from two files, and a Claude Code MEMORY.md past the 200 lines / 25KB that load at session start. Fix each finding with the user's yes; never delete memory content unasked. (If CLAUDE_PLUGIN_ROOT is unexpanded, bin/check.js lives at the plugin root, two directories above this file.)
• Treat a fact as superseded, not accumulated: replace the old line, don't stack a new one beside it.

One file vs many

Start with one file. Split only when it crosses ~150–200 lines or covers clearly separable domains — then go to a thin index + topic files loaded on demand. Below that, an index costs more (the always-loaded tax) than it saves.

Keep terse

Apply Honey Lever 2 to the content — fragments over paragraphs, no narration of what the code already says. A bloated memory file is a per-session input tax. Keep it human-readable markdown: you (and reviewers) hand-edit it, so don't use a wire format — staleness costs more than the tokens a dense format would save.

Boundaries

Reversible — FILE.original.md is the restore path when overwriting. Verify every written fact against the current code before reporting done; an unverified fact is worse than an absent one.