State and long-running work

This stage explains how nanobot retains information across Turns and how long tasks, scheduled work, and background Subagents re-enter the core Agent flow.

Corresponding source

Subject	Source
Session and replay	nanobot/session/manager.py, nanobot/session/keys.py
Compaction, Memory, and Dream	nanobot/agent/memory.py, nanobot/agent/autocompact.py, nanobot/templates/agent/dream.md
Goals and Continuations	nanobot/session/goal_state.py, nanobot/session/turn_continuation.py
Cron and Heartbeat	nanobot/cron/, nanobot/agent/cron_turns.py
Subagents	nanobot/agent/subagent.py, nanobot/agent/tools/spawn.py

Learning objectives

After this stage, you should be able to distinguish:

• Session messages;
• Session metadata;
• ContextBuilder’s context for the current Turn;
• memory/history.jsonl;
• memory/MEMORY.md;
• AutoCompact;
• token consolidation;
• Dream;
• Goal;
• Continuation;
• Cron;
• Subagent.

Reading order

1. Session files and replay boundaries
2. Compaction, Memory, and Dream
3. Goals and Continuations
4. Cron and Heartbeat
5. Subagent lifecycle

Overall relationships

flowchart TD
    T["One Turn"] --> S["Session JSONL"]
    S --> H["Session history for the next Turn"]
    S --> C["Consolidator"]
    C --> J["memory/history.jsonl"]
    J --> D["Dream"]
    D --> M["SOUL.md / USER.md / MEMORY.md"]
    M --> CTX["ContextBuilder"]
    H --> CTX

    G["Goal state<br/>Session metadata"] --> CTX
    G --> CONT["Internal Continuation"]
    CONT --> T

    CR["Cron / Heartbeat"] --> IN["InboundMessage"]
    IN --> T

    SA["Subagent"] --> R["Independent AgentRunner"]
    R --> ANN["Result InboundMessage"]
    ANN --> T

Most important boundary

“Long-running work” is not one large subsystem

Goal, Cron, and Subagent use different mechanisms. Goal is Session metadata; Continuation is an internal inbound message; Cron is persistent scheduling; Subagent is a background AgentRunner. Do not describe them collectively as a “multi-agent scheduler.”

Next step

Read Session files and replay boundaries.