The most expensive thing about working with an agent is re-explaining context. Every morning you re-explain yesterday's decisions, paste the last commit message, re-establish which bug blocks the deploy. Multiply by every session and the hidden cost is hours per week, not minutes.
STATE.md kills that tax. One file, updated at the end of every session, loaded at the start of the next. The discipline: before you close a session, spend three minutes updating the file. Tomorrow, those three minutes save twenty.
STATE.md holds three things, nothing more.
Decisions: what you settled on and why. Without the why, future-you re-opens the decision. "Postgres triggers instead of cron for the daily digest: triggers are transactional, cron races the write path."
In-flight: what is half-done, specific enough to hand off. "Migration 014 written at /migrations/014_add_subscription_columns.sql but not applied. Must run before the webhook handler goes live."
Blockers: what stops forward motion, including what you tried. "Stripe webhook signature failing in test env. Tried raw body parser, still 400. Next: check env var in Vercel preview."
Cap it at 60-80 lines. When something resolves, remove it. When something ships, archive it.
The update discipline. Add a Stop hook to remind yourself:
{
"hooks": {
"Stop": [
{
"command": "echo 'Before you close: update STATE.md with decisions, in-flight, and blockers from this session.'"
}
]
}
}The reminder alone is not enough; the habit has to be automatic. The fastest path: do it for five consecutive sessions. By session six, you will feel wrong closing without updating. The discomfort is the signal that the habit has formed.
MEMORY.md is the index for everything durable. Each entry is one line pointing to a separate file. Four types:
user_*: durable facts about you: timezone, career context, preferences. user_location.md
feedback_*: rules learned from mistakes, with a confidence field. Start at 0.3, bump to 0.5 when the pattern recurs, promote to CLAUDE.md at 0.9+. feedback_public_endpoints_need_rate_limits.md
project_*: dated state and decisions for one project. Archive when it ships. project_stripe_integration_2026_05.md
reference_*: lookup tables for people, tools, APIs. reference_neon_db_config.md
Keep each index line under 200 characters and the index under 200 lines. Past that, entries get truncated and Claude cannot see them.
STATE.md is for now. MEMORY.md is for always. The rule of thumb: if you would say it in a standup, it goes in STATE.md. If you would write it in a wiki or onboarding doc, it goes in a memory file. Standups are transient; wikis are durable.
When a project ships and STATE.md still carries five lines about it, move those lines to a dated project_* memory file and clear them. The project did not stop mattering; it stopped being current. That distinction keeps STATE.md useful.
Write state, not a journal. A journal entry: "Worked on the Stripe integration. It was tricky." A state entry: "Webhook endpoint at app/api/webhooks/stripe/route.ts. Signature verification works locally, fails in Vercel preview (wrong raw body format). Next: check rawBody middleware config." One gives the next session a starting point; the other gives it a memoir.
Two more anti-patterns: in-flight entries without a concrete next action a fresh session could execute, and duplicate entries for the same topic across sessions. Merge duplicates: one topic, one entry, current state only.
A good session update is nine to twelve lines: one decision with rationale, one in-flight item with next step, one blocker with what you tried.
Scaling past 50 memory files: the digest layer. Each MEMORY.md pointer line costs roughly 100-150 tokens. At 200 lines that is 20-30K tokens of pure pointers. The fix: STRATEGY-DIGEST.md, a 2-3 sentence summary of every major document plus a "Use when:" field:
## q2-positioning.md
Q2 positioning targets AI enablement in mid-market sales orgs.
Use when: discussing target customer, pricing, or lead qualification.Claude reads the digest (about 3K tokens) and loads a full document only when relevant. At 25 strategy docs, that is 3K tokens instead of 50K. The "Use when:" field is the routing mechanism: write it as a specific trigger condition, not a description of the file.
STATE.md captures current state (decisions, in-flight, blockers) under 80 lines; update it at session end and archive history out promptly. MEMORY.md indexes durable knowledge in four types (user, feedback, project, reference), capped at 200 lines. Start tonight with three lines: one decision, one in-flight item, one blocker. Three lines beat zero while the habit forms.