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.

On a fresh init, STATE.md carries a hidden setup sentinel until your project context is filled in. It's what triggers the first-run interview covered in The Keeper; cognitiveos check also surfaces it as a soft reminder until you've answered (or explicitly skipped) it.

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. If files in the project changed on a later day than the last STATE.md save, Mission Control flags the handoff as possibly stale, since the summary may predate the real last work.

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.