Brain Snapshot

Runs on: local-writes - creates or edits files in your OS folder; needs an agent with write access.

The brain snapshot is a small markdown payload (~200 tokens) that captures what is true right now: voice rules, brand fields, open flags, this week's commitments, recent decisions, and staleness state. Skills read it at task time so their output reflects the latest state of the OS instead of starting cold.

Where it lives

• Generator: scripts/brain-snapshot.py (Pure Python stdlib, no runtime deps).
• Output: brain/.snapshot.md (gitignored, per-user state).
• Mirror copy for installs: templates/scripts/brain-snapshot.py.

Generate or refresh the snapshot

python scripts/brain-snapshot.py --write

Writes the snapshot to brain/.snapshot.md. Re-run any time the underlying files change: usually after a /dream digest, after rolling the daily anchor, or at the start of a long session.

To inspect without writing:

python scripts/brain-snapshot.py

Snapshot format

Deterministic field order. Same inputs produce identical output (modulo the date: line). Sections always render: missing source files emit [unavailable] rather than crashing.

# Brain snapshot

date: YYYY-MM-DD
staleness:
  daily_anchor: fresh | stale (N days past) | [unavailable]
  weekly: fresh | stale (N days past) | [unavailable]
  weekly-must-do: fresh | [unavailable - weekly file stale] | [unavailable - weekly file missing]

## Voice (key rules)
- rhythm: <value or [NOT SET]>
- opening_style: <value or [NOT SET]>
- closing_style: <value or [NOT SET]>
- contractions: <value or [NOT SET]>
- reading_level: <value or [NOT SET]>
- preferred: <comma-joined list or [NOT SET]>
- banned: <comma-joined list or [NOT SET]>

## Brand (key fields)
- display_name: <value or [NOT SET]>
- primary_color: <hex or [NOT SET]>
- primary_font: <font or [NOT SET]>

## Open flags (top 3)
- <flag header 1>
- <flag header 2>
- <flag header 3>

## This week (must do)
- <item 1>
- <item 2>
- <item 3>

## Recent decisions (last 3)
- <decision header 1>
- <decision header 2>
- <decision header 3>

How skills consume the snapshot

A skill that opts in reads brain/.snapshot.md before producing output. The opt-in pattern is consistent across all consumers:

1. Read brain/.snapshot.md if it exists.
2. If missing, OR its date: line is more than 3 days old, run:
   python scripts/brain-snapshot.py --write
   Then read it. A stale cache read as current aims output at last month's state.
3. If the snapshot script is also missing (older install), proceed using only profile files.
   Do not block.
4. Apply the snapshot as runtime context. Do not surface every field in every output.
   Use judgment about which fields belong in which output.

What the snapshot is NOT

• It is not a database. It is a flat markdown payload regenerated from source files on demand.
• It is not authoritative. The source files (flags.md, weekly-commitments.md, decisions.md, voice-profile.yml, brand-profile.yml) remain the single source of truth.
• It is not a replacement for query.py. Query is for retrieval across the full corpus. Snapshot is for "what is true right now."
• It is not auto-fired. Skills consume it on opt-in. Setup does not require generating it.

Failure modes and recovery

• Script missing (older install). Skills fall back to profile-only context. No output is blocked.
• Source file missing. That section emits [unavailable] and others render normally.
• Source file unparsed (e.g. weekly file lacks the ## Week of YYYY-MM-DD header). The relevant staleness field shows [unparsed - ...]. The OS still functions; the user can fix the header at their convenience.
• Snapshot stale. Re-run with --write. The snapshot is cheap to regenerate.

Privacy

brain/.snapshot.md may contain personal fields (display_name, voice rules, decision headers). It is gitignored by default. If you sync the OS folder across machines, the snapshot regenerates locally on each machine.

Determinism

For test stability, the script accepts --today YYYY-MM-DD to override the current date. This is test-only. Production runs use date.today().