Skip to content

Session Boot Flow Explainer

URL: https://mkdocs.justinsforge.com/memory/handoffs/session-boot-flow-explainer-2026-05-22/

What auto-loads when a fresh Claude Code session boots on forge, in the order it happens. Phone-readable.

The boot sequence, 1 to 6

1. CLAUDE.md, project root

First thing in context. Lives at forge/CLAUDE.md. It is the only file Claude Code auto-loads every session unconditionally.

What it carries:

  • Doctrine hard rules inlined at the top. Communication (no em dashes, no filler), naming (kebab-case forge-*, friendly aliases for personal endpoints), variables (snake_case [source]_[entity]_[state]), engineering standards (robust over quick, fail loud, idempotent, test before claiming done), self-iteration (halt on doctrine conflict, do not silently override).
  • A system mental model table. Forge backend, storage, interfaces, memory, agents.
  • Quick command index for skills like /spawn, /recall, /handoff, /notify.
  • The session startup checklist (read system-map, scan MEMORY.md, check today's daily log).
  • Security hard limits (Gmail policy, no secrets in git, etc.).
  • Pointers out to FORGE-DOCTRINE.md, system-map/, memory/.

If anything in CLAUDE.md conflicts with FORGE-DOCTRINE.md, the doctrine wins. CLAUDE.md is the inline cheat sheet.

1b. L4 path-scoped CLAUDE.md

Any sub-directory can drop its own CLAUDE.md and it auto-loads when the CWD descends into that path. Reference example: brands/nova-design/CLAUDE.md loads only when working under that brand. This keeps the root file lean and gives per-project briefings without bloating every session.

2. SessionStart hook → Boot briefing

scripts/forge_hook_session_start_since_last.sh runs at every session start. Output goes straight into Claude's context as the # Boot briefing block visible at the top of every session.

What it surfaces:

  • Last session timestamp (parsed from memory/daily/*.md entries marked [Claude Code]).
  • Recent handoffs, last 7 days, from memory/handoffs/.
  • Pending tasks from the dispatcher queue.
  • Monitor alerts in last 24h.
  • Active tmux sessions (other Claude workers currently alive).

Designed to be fast (< 2s) and silent-fail. A broken hook never blocks a session.

3. MEMORY.md

Auto-loaded, first 300 lines (35KB cap, doctrine Section 12). Lives at ~/.claude/projects/-home-justinwieb-forge/memory/MEMORY.md, NOT in the forge tree (so it isn't served by mkdocs and isn't in /recall).

Index-not-knowledge-base pattern. Each line points to a topic file in the same directory (memory/general/<topic>.md style). Categories:

  • State Topics (services, machines)
  • Workflow and Behavioral Topics (feedback_*)
  • Project Topics (project_*)
  • User (user_*)
  • Reference Topics (reference_*)

If a fact contradicts the index, you fix the file, not duplicate it.

4. Steering layer (on-demand, not auto-injected)

system-map/steering.md plus the Phase 4.8 runtime deny-list. Routes agents and tasks to the right destination.

Important nuance: steering is read on-demand per the CLAUDE.md startup checklist, not auto-pulled into context. Claude opens it when the work calls for it (routing decisions, agent dispatch). This keeps it from eating session tokens when irrelevant.

5. UserPromptSubmit hook, project auto-context

Fires on every user message. When Justin mentions a project name (e.g. "Nova Design", "Sip-N-Serve", "JWVR"), the hook auto-loads that project's context file so Claude doesn't have to grep for it.

Mechanism documented in memory/general/reference_auto_context.md. Manual lookup table at system-map/projects.md.

6. Auto-memory + auto-dream (Phase 4.4)

Runs at the END of a session, not the start, but it's the reason future sessions know what happened today.

  • Stop-hook auto-memory captures persistent facts when the session ends and writes them through the memory pipeline.
  • Nightly auto-dream consolidates the day's captured facts into topic files and prunes the index.
  • Both write audit entries to LESSONS.md so every change is reversible by session id.

Net effect: tomorrow's CLAUDE.md + MEMORY.md + boot briefing already reflect what today's session learned, without Justin having to write a handoff manually.

If you remember nothing else

  • CLAUDE.md is the only thing auto-loaded unconditionally; the doctrine cheat sheet sits at its top.
  • Boot briefing (SessionStart hook, forge_hook_session_start_since_last.sh) puts last session, recent handoffs, pending tasks, and live tmux sessions in context within 2 seconds.
  • MEMORY.md is an index pointing to topic files; first 300 lines auto-load, never the topic files themselves.
  • Steering and project context are pulled on-demand (steering when routing, project context when the project is named in a prompt) so they don't eat tokens unused.
  • Auto-memory + auto-dream close the loop at session end, so tomorrow boots already knowing today.