# Honey Memory

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

- Skill: `s1lverelixir/honey-memory` (Agent Skill)
- Install (CLI): `npx skillmds@latest add s1lverelixir/honey-memory`
- Raw SKILL.md: https://api.skillmd.com/api/skills/s1lverelixir/honey-memory/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Docs & Writing
- Author: S1lverElixir (https://skillmd.com/u/s1lverelixir)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/s1lverelixir/honey-memory

---


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