Sessions — Under the Hood

A single chat assistant remembers what you said three messages ago. A multi-agent pipeline does not, because each agent spawns fresh with nothing but its instructions and the files it can read. The shared memory is on disk — a per-run folder of YAML that every agent reads from and writes to.

Every /run, /team, and /designer command creates a session on disk: 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 is 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.

Sessions are not just a record of what happened. They are 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 enriches the request, the planner decomposes it into work items, 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.

Think of the session directory as the flight recorder and the shared workspace rolled into one. It records what happened, in what order, and whether it succeeded — and it gives every agent the context it needs to do its job without drifting off course.

Why agents need sessions

When you ask a single AI assistant to do something, it has the full conversation context. Multi-agent pipelines do not work that way. Each agent spawns fresh — it has its instructions and whatever files it can read, but it has no memory of what 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 matters most for longer pipelines. By the time the validator runs, the original request might be several 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.

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

What's in a session directory

When you run a command, cAgents creates a directory under cagents-memory/sessions/ with this shape:

.
├── instruction.yaml        # what was requested
├── status.yaml             # current pipeline state
├── plan.yaml               # the planner's output
├── work_items.yaml         # the granular task breakdown
├── coordination_log.yaml   # controller's execution record
├── validation_report.yaml  # the validator's verdict
└── workflow/
    └── agent_tree.yaml     # every agent that was spawned

The top-level files tell the story in order: instruction.yaml is what you asked for, status.yaml is where the pipeline is right now, plan.yaml and work_items.yaml are what the planner produced, coordination_log.yaml is what the controller did, and validation_report.yaml is the validator's final read. The workflow/agent_tree.yaml audit trail records which agents ran and how they were related.

A /team session has a slightly different shape — instead of a single work_items.yaml, it carries a work_meta.yaml read once at the top plus a per-wave work_items_wave_{K}.yaml for each wave. The rest of the files are the same.

The prompts panel on this article walks you through reading each of these files end to end on a real session in your project. The article frames the schema; the panel does the read.

How sessions get named

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

• skill — the command that created the session (run, team, designer)
• 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 skill and slug on the same day

Real examples from this project:

The naming makes it easy to find sessions by command, 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 — 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. The prompts panel has read-only walkthroughs for both lookup styles.

Read the core files

instruction.yaml — the request record

This file captures what you asked for, frozen at the moment the session started. The prompts panel reads the full file and translates it into prose; the keys worth knowing are request: (the verbatim ask), session_type (run, team, or designer), flags (any CLI flags you passed, such as --resume or --dry-run), and parent_session_id — null for standalone runs, but populated when a /team parent spawned a child /run.

status.yaml — the state machine

This is the file you check first when you want to know where a pipeline stands. It carries the current pipeline_state plus a state_history array — an ordered timeline of every state the pipeline passed through, each with a timestamp and a duration. You can see exactly how long each phase took, and the panel narrates that timeline for you on a real session.

Two facts make status.yaml the load-bearing file. The latest entry's duration tells you whether the pipeline is finished, mid-run, or interrupted. And the set of states actually visited tells you which path the adaptive pipeline took — a faster path for simpler tasks skips states, and status.yaml is where that choice is recorded.

agent_tree.yaml — the audit trail

Every agent spawned during the pipeline gets registered in workflow/agent_tree.yaml — its id, type, parent relationship, spawn time, and role. 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. The panel walks the tree and maps each agent back to the pipeline phase it served.

What states the pipeline passes through

The state machine has five states. Not every pipeline hits all of them — the adaptive pipeline skips states based on complexity.

Simpler tasks take a fast path. A tier 2 run can go straight INIT → PLANNED → COORDINATED → VALIDATED, skipping ORCHESTRATED's three enrichment agents — the fast path described in Part 3. Complex tier 3 and tier 4 tasks hit every state and loop COORDINATED's executor/reviewer cycle up to three times before advancing. The status.yaml file always tells you which path a specific session took.

Resume an interrupted run

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.

cAgents finds the most recent incomplete session, reads status.yaml to determine the last completed state, and restarts the pipeline from the next state. Work that was already done does not get repeated — completed work items in coordination_log.yaml are reused, and only unfinished ones re-run. The prompts panel verifies a session is resumable, identifies the exact resume point, and triggers the resume for you.

How nested sessions link parent and child

/team creates a parent session that spawns child /run sessions, one per parallel task in a wave. The parent_session_id field in each child's instruction.yaml links back to the parent, and the hierarchy is at most two levels deep — a team_* parent over its run_* children.

A /team session running three parallel tasks across two waves creates a directory shape like this:

cagents-memory/sessions/
├── team_article-wave-design_260621_001/      # parent session
├── run_homepage-article_260621_001/           # child — wave 1
├── run_portfolio-article_260621_002/           # child — wave 1
└── run_blog-article_260621_003/                # child — wave 2

The parent's coordination_log.yaml tracks which children were spawned, which wave they belong to, and their completion status — a quality gate validates each wave before the next one starts. Each child is a self-contained session with its own status.yaml, agent_tree.yaml, and full execution record.

This is how a single /team command coordinates parallel work 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.

When you're done

You know the shape of cagents-memory/sessions/, what each YAML file in a session carries, which states the pipeline can move through, and how a parent links to its children. Open the prompts panel on any real session in your project to read it end to end without browsing files yourself.

Previous: Part 4 — /team: parallel and cross-domain execution is where those parent sessions and their waves come from.

Next: Part 6 — Hooks: the event system covers the deterministic triggers that fire on session lifecycle events — the surface where rules-as-prose drift gets pinned down to exit codes.