Sessions - Under the Hood

This is Part 9 of a 10-part series on cAgents. Previous: /review - Quality Review | Next: Hooks - The Event System

The first eight articles showed what each command does. This one shows what happens on disk when you run them.

Every /run, /team, /org, and /designer command creates a session - a directory of YAML files that tracks everything from the initial request to the final validation. The session is the source of truth for the pipeline. It's how cAgents knows which agents ran, what state the pipeline is in, whether work completed successfully, and where to pick up if something gets interrupted.

But sessions aren't just a record of what happened. They're also how agents stay on track while work is in progress. A multi-agent pipeline can involve a dozen agents working across multiple phases - the orchestrator hands off to a planner, the planner hands off to a decomposer, the controller spawns execution agents. None of these agents share memory with each other. The session directory is the shared memory. Each agent reads the outputs from the previous phase, does its work, and writes its outputs for the next phase. Without the session on disk, every agent would be starting from scratch with nothing but the original request.

I think of sessions as the flight recorder and the shared workspace rolled into one. They record what happened, in what order, and whether it succeeded. And they give every agent in the pipeline the context it needs to do its job without drifting off course.

Why Sessions Matter for Agent Coordination

When you ask a single AI assistant to do something, it has the full conversation context. It remembers what you said three messages ago. Multi-agent pipelines don't work that way. Each agent spawns fresh - it has its instructions and whatever files it can read, but it has no memory of what the previous agents discussed or decided.

Sessions solve this. The planner writes plan.yaml with objectives and acceptance criteria. The controller reads that plan and knows exactly what to execute against. The validator reads the plan and the controller's coordination_log.yaml and knows what success looks like. Each agent is grounded in concrete artifacts from the previous phase, not a vague understanding of the request.

This is especially important for longer pipelines. By the time the validator runs, the original user request might be five agent handoffs ago. Without the session files, the validator would have to reconstruct intent from scratch. With them, it has the plan, the acceptance criteria, and the execution record - everything it needs to make a precise judgment.

Previous sessions are also available as reference material. When cAgents starts a new task, the enrichment phase can look at how similar work was handled before - which controllers were selected, what plans worked, what failed. The Agent_Memory/sessions/ directory is a growing library of past decisions that informs future ones.

Session Directory Structure

When you run a command, cAgents creates a directory under Agent_Memory/sessions/ with this structure:

Agent_Memory/sessions/run_shift-geometric-shapes_260330_003/
├── instruction.yaml        # What was requested
├── status.yaml             # Current pipeline state
└── workflow/
    ├── agent_tree.yaml     # Every agent that was spawned
    ├── plan.yaml           # The planner's output
    ├── coordination_log.yaml  # Controller's execution record
    ├── execution_summary.yaml # Final results
    └── events/
        ├── EVT-1.yaml      # State transition events
        ├── EVT-2.yaml
        └── index.yaml      # Event ordering

The top-level files - instruction.yaml and status.yaml - tell you what was requested and where the pipeline is right now. The workflow/ subdirectory holds the detailed execution record: which agents ran, what they planned, how they coordinated, and what they produced.

Session Naming

Session directories follow a consistent naming convention: {type}_{slug}_{YYMMDD}_{NNN}.

• type - the command that created the session (run, designer, team, org)
• slug - a kebab-case summary of the request, auto-generated from your task description
• YYMMDD - the date
• NNN - a sequence number, incremented if you run the same type and slug on the same day

Real examples from this project:

The naming makes it easy to find sessions by command type, topic, and date without opening any files. When you have dozens of sessions in the directory, the convention pays for itself. That said, you rarely need to browse this directory yourself - just ask Claude "find the session where I worked on the auth module" or "what was the last /team run?" and it will locate the right one instantly.

The Core Files

instruction.yaml - The Request Record

This file captures what you asked for, frozen at the moment the session started:

session_id: run_shift-geometric-shapes_260330_003
session_type: run
command: /run
request: "they should shift through all the common geometric shapes - not just hold one"
created_at: "2026-03-31T06:00:00Z"
flags: {}
parent_session_id: null
metadata:
  working_directory: /home/PathingIT/caelandrayer.ca

The parent_session_id is null for standalone runs. When a /team or /org session spawns child /run sessions, the children point back to the parent here. The flags field records any CLI flags you passed (--dry-run, --interactive, --resume).

status.yaml - The State Machine

This is the file you check first when you want to know where a pipeline is:

pipeline_state: VALIDATED
revision_round: 0
validation_cycles: 0
created_at: "2026-03-31T06:00:00Z"
state_history:
  - state: INIT
    entered_at: "2026-03-31T06:00:00Z"
    duration_ms: 2000
  - state: PLANNED
    entered_at: "2026-03-31T06:00:02Z"
    duration_ms: 107720
  - state: PROMPTS_READY
    entered_at: "2026-03-31T06:02:00Z"
    duration_ms: 95118
  - state: VALIDATED
    entered_at: "2026-03-31T06:03:35Z"
    duration_ms: null

The state_history array is an ordered timeline of every state the pipeline passed through, with timestamps and durations. You can see exactly how long each phase took.

Notice this example went INIT -> PLANNED -> PROMPTS_READY -> VALIDATED. That's only four states out of the full seven. The adaptive pipeline skips states based on task complexity - this was a tier 2 task that took the "fast path" described in Part 3, bypassing ORCHESTRATED, DECOMPOSED, and COORDINATED.

agent_tree.yaml - The Audit Trail

Every agent spawned during the pipeline gets registered here:

agents:
  - id: pipeline
    type: cagents:run
    parent: root
    depth: 0
    spawned_at: '2026-03-31T06:00:00Z'
    cagents_type: cagents:run
    short_role: Pipeline Engine
    role_description: Make particles shift through geometric shapes
    session: run_shift-geometric-shapes_260330_003
  - id: a896233d2db44f00b
    type: cagents:universal-planner
    parent: root
    depth: 0
    spawned_at: '2026-03-31T06:02:52Z'
    cagents_type: cagents:universal-planner
    short_role: Universal Planner

Each entry includes the agent's ID, type, parent relationship, spawn time, and role description. When a pipeline finishes, completion summaries get appended to each agent's entry - what it produced, whether it succeeded, and how long it took.

This is the full audit trail. If you need to know which agent made a specific change or how many agents a pipeline spawned, agent_tree.yaml has the answer.

Pipeline States

The full state machine has seven states. Not every pipeline hits all of them - the adaptive pipeline skips states based on complexity.

Simple tasks (tier 1) might go straight from INIT to PLANNED to PROMPTS_READY to VALIDATED. Complex tasks (tier 3) hit every state. The status.yaml file always tells you which path a specific session took.

Resumption

Sessions checkpoint as they go. Every state transition writes to disk before the next state begins. If a run gets interrupted - your terminal closes, your machine sleeps, the network drops - the session directory preserves everything up to the last completed state.

To pick up where you left off:

/run --resume

cAgents finds the most recent incomplete session, reads the status.yaml to determine the last completed state, and restarts the pipeline from the next state. Work that was already done doesn't get repeated.

The events/ directory is what makes this possible. Each EVT-*.yaml file records a state transition with enough context to reconstruct the pipeline's position. The index.yaml file maintains the ordering.

Nested Sessions

/org and /team create parent sessions that spawn child /run sessions. The parent_session_id field in each child's instruction.yaml links back to the parent.

A /team session running three parallel tasks creates a directory structure like this:

Agent_Memory/sessions/
├── team_article-wave-design_260321_001/      # Parent session
├── run_homepage-article_260321_001/           # Child - wave 1
├── run_portfolio-article_260321_002/          # Child - wave 1
└── run_blog-article_260321_003/               # Child - wave 2

The parent session's coordination_log.yaml tracks which children were spawned, which wave they belong to, and their completion status. Each child is a self-contained session with its own status.yaml, agent_tree.yaml, and full execution record.

This is how a single /org command can coordinate work across multiple domains without losing track of any individual piece. The parent knows what it delegated. Each child knows what it did. The session structure keeps everything connected.

Series navigation: Previous: /review - Quality Review | Next: Hooks - The Event System