---
name: honey-memory
description: >-
  Create and maintain one committed per-project memory file (PROJECT.md) so
  agents stop re-discovering the same facts every cold session. Stores only the
  stable, expensive-to-rediscover, not-in-the-code context — architecture +
  why, build/test/run commands, decisions and dead-ends — as human-readable
  markdown, versioned with the code so it can't silently rot. Use when asked to
  set up project memory/context, stop agents re-grepping the codebase, scaffold
  or refresh a PROJECT.md / CLAUDE.md memory section, or cut cold-start
  rediscovery cost. Prose context only — never code, config, or data.
license: MIT
---

# 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.
- 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.