STATE.md

STATE.md is your current-state snapshot: the single file your agent reads at the start of every session and overwrites at the end. It holds your current focus, blockers, and open loops, so context survives between sessions.

It is a snapshot, not a log. It holds CURRENT state only and stays roughly the same size forever. History rolls to sessions/; idea and someday lists live in their zone folders. You never edit it by hand and you never run a "save" command. Hooks keep it current automatically.

Why not memory.md? MEMORY.md is now an agent-memory convention (Claude Code keeps its own under .claude/). Naming this file STATE.md sidesteps that collision and says what it is: the current state, curated by you, not the agent's auto-memory.

The 7 sections

# STATE.md: Current State
> A snapshot, not a log. Overwritten each session. History lives in sessions/.

## Current Focus
- Project / Task / Status

## Blockers
- active blockers only, removed when resolved

## Open Loops
- started but unfinished, ACTIVE only (closed loops roll to sessions/)

## Active Projects
- max 3, enforced

## Session Handoff
- Last worked on / Stopped because / Pick up by / Watch out for

## Recently Completed
- last 5 only, older wins roll to sessions/

## Agent Notes
- learned preferences, capped at ~10

Session Handoff, the most important section

The Handoff is the bridge between one session and the next. It's overwritten at every session-end and answers four questions:

• Last worked on: the task you were in.
• Stopped because: the interruption point or reason you stopped.
• Pick up by: the exact next action.
• Watch out for: the gotcha, the half-done thing, the fragile state.

This is what an ADHD brain needs first: not "here's your state," but "here's literally the next thing to do."

PICK UP, the Mission Control headline

cognitiveos start reads the Handoff and leads with it. The ➡ PICK UP line is the first thing you see: the exact next action, with the stop reason underneath:

┌─ cognitiveOS ──────────────────────────────┐
│  ➡  PICK UP    Wire the deploy script       │
│               (stopped: waiting on RPC key) │
│                                            │
│  🔥 FOCUS     Fix wallet connection bug     │
│  🔁 LOOPS     2 open                        │
│  🧱 BLOCKED   Base RPC key                  │
│  ✅ RECENT    Shipped contract v2           │
└────────────────────────────────────────────┘

The same pick-up line leads the hook envelope your agent reads at session start, so it resumes exactly where you left off.

How it stays flat

STATE.md doesn't grow because the end-session hook overwrites current state, rolls closed loops and old wins to sessions/, and prunes Agent Notes. cognitiveos check flags it if it ever exceeds ~150 lines ("STATE.md is growing, should be a snapshot"), a backstop, since the roll-out is agent-driven.

See also: Hooks · Commands.