| name | napkin |
| description | Per-repo behavioral memory stored in .codex/napkin.md. Use to initialize or
update the napkin for any project. Tracks repo-specific mistakes, user corrections,
and surprising gotchas that recur across sessions. Read silently at session start
if the file exists. Write during work. Curate aggressively. Complement to MEMORY.md
(which is cross-project and user-scoped); napkin is repo-scoped and committable.
|
| date | "2026-02-24T00:00:00.000Z" |
| source | adapted from https://github.com/blader/napkin by @blader (MIT) |
Created: 2026-02-24-01-31
Last Updated: 2026-02-24-12-53
Napkin
Per-repo behavioral memory that travels with the codebase.
Inspired by napkin by @blader.
Usage
/napkin
/napkin --update
/napkin --curate
What Napkin Is (and Isn't)
Napkin is a curated runbook of repo-specific behavioral corrections.
| Napkin (.claude/napkin.md) | Auto-memory (~/.claude/projects/.../MEMORY.md) |
|---|
| Scope | This repo only | Cross-project, user-level |
| Location | Inside the repo | In ~/.claude/projects/ |
| Committable | Yes — share with contributors | No — personal |
| Content | Behavioral corrections ("do X not Y") | Stable patterns, architectural decisions |
| Format | Categorized, 10-item cap | Semantic topics, 10-item cap |
Session Protocol
At session start: If .claude/napkin.md exists in this repo, read it before
doing anything else. Apply it silently — don't announce it, just let it inform your
behavior.
During work: When you make a mistake, get corrected, or encounter a surprising
gotcha, add an entry. Don't wait for the end of the session.
During curation (same session or next): Re-prioritize entries. Merge duplicates.
Remove stale entries (haven't come up in 3+ sessions). Enforce the 10-item cap per
category.
Entry Format
Each entry requires three things:
[YYYY-MM-DD] Rule title → Do X instead of Y
Examples:
[2026-02-23] Prisma in CI → Run `prisma generate` before tests or migration check fails
[2026-02-23] Branch naming → Use feat- prefix, not feature- (hooks enforce this)
[2026-02-23] Env file → Never read .env directly; use process.env in app code only
File Format
# Napkin — [Repo Name]
Last curated: YYYY-MM-DD
## Execution & Validation
- [YYYY-MM-DD] ...
- [YYYY-MM-DD] ...
## Shell & Command Reliability
- [YYYY-MM-DD] ...
## Domain Behavior Guardrails
- [YYYY-MM-DD] ...
## User Directives
- [YYYY-MM-DD] ...
Rules:
- Max 10 items per category. When at capacity, drop the oldest or least-recurring entry.
- 4 suggested categories (add repo-specific ones as needed, keep total categories ≤ 6)
- Entries must have an explicit action ("do X" or "never do Y") — no vague notes
- No one-off workarounds, verbose postmortems, or timeline notes
Initialization
If .codex/napkin.md does not exist, create it:
mkdir -p .codex
cat > .codex/napkin.md << 'EOF'
Last curated: YYYY-MM-DD
EOF
Then add it to your .gitignore (keep it personal) or commit it (share with
contributors). Committing is recommended for shared repos where multiple agents
work on the same codebase.
What Qualifies
Add to napkin:
- Mistakes you made in this repo that you made more than once
- User corrections that affect repeated behavior
- Surprising tool/environment behavior specific to this repo
- Non-obvious tactics that reliably work here
Don't add to napkin:
- One-off timeline notes ("had to fix X on 2026-02-23")
- Things that belong in MEMORY.md (cross-project patterns)
- Verbose postmortems without a clear "do X" action
- Information the docs already cover
Curation Pass
Run a curation pass at the start of any session where the napkin feels noisy:
- Re-prioritize: highest-frequency entries first within each category
- Merge overlapping entries into one specific rule
- Drop entries that haven't fired in 3+ sessions (they're probably stale)
- Enforce 10-item cap: if over, drop the least-recurring entry
- Update "Last curated" date
