YAML / Team Session Continuity

Resume, fork, and continue AgentTeam runs launched from agents.yaml with the same session flags as prompt runs

praisonai run agents.yaml --continue resumes a whole team exactly where it left off — prior turns and per-agent chat history replay before your new prompt.

bash

# First run
praisonai run agents.yaml

# Come back tomorrow — team continues where it left off
praisonai run agents.yaml --continue

Diagram

Quick Start

Run your team once
bash
```
praisonai run agents.yaml
```
The run auto-saves to a project-scoped session — no memory: true needed in your YAML.
Continue the team later
bash
```
praisonai run agents.yaml --continue
```
The most recent root session for this project resumes; each agent’s prior findings replay before your new prompt.

How It Works

The adapter resolves the session, restores team state and per-agent chat history, runs astart(), then captures fresh history back into state on save.

Diagram

sequenceDiagram
    participant User
    participant Adapter
    participant Team as AgentTeam
    participant Store as SessionStore (durable, project-scoped)

    User->>Adapter: praisonai run agents.yaml --continue
    Adapter->>Store: resolve session id (SessionStore keyed lookup)
    Adapter->>Team: restore_session_state(id)
    Team->>Team: rehydrate per-agent chat_history (deduped)
    Adapter->>Team: astart()
    Team-->>Adapter: result
    Adapter->>Team: capture chat_history into state
    Adapter->>Store: save_session_state → update_session_metadata(team_session_state=...)
    Adapter-->>User: response

    classDef actor fill:#8B0000,stroke:#7C90A0,color:#fff
    classDef process fill:#189AB4,stroke:#7C90A0,color:#fff
    classDef result fill:#10B981,stroke:#7C90A0,color:#fff

    class User,Adapter actor
    class Team process
    class Store result

YAML/team runs go through the same core APIs as single-agent runs — AgentTeam.restore_session_state and AgentTeam.save_session_state. No new params, no YAML changes.

Behavior	Detail
Chat history rides along with state	Per-agent history is stashed under the reserved state key `_cli_session_chat_history` so the existing save/restore machinery persists conversation with no new core APIs
Memory-independent resume	Team state persists to the durable, project-scoped `SessionStore` (`update_session_metadata` / `get_session`), keyed by `session_id`. Resume works even when the team runs with `memory=False`; `shared_memory` is now optional enrichment, not a requirement
Deterministic keyed lookup	Restore reads by exact `session_id` from `SessionStore.get_session(...).metadata`. The pre-#3637 `search_short_term(limit=10)` fuzzy scan is gone (kept only as a legacy fallback for pre-#3635 sessions)
Rehydrate is deduplicated	Restore skips messages already present on an agent (matched on `(role, content)`), so a resume or fork never doubles prior turns
Save never fails a completed run	If save raises after kickoff, it is logged as a warning and the successful result is still returned
Opt-in via project sessions	Flags take effect only when the CLI has opted into project sessions — set automatically by `run` / `chat` / `code` when a session flag is present

Durable State Guarantees

Team state rides the same crash-safe write path as single-agent --continue.

Diagram

Guarantee	Detail
Crash-safe writes	Team state is written under `FileLock` + atomic file replace via `SessionStore` — a crashed process cannot leave a half-written session
Compaction-aware	Same store as single-agent `--continue`, so compaction checkpoints apply — see Session Store → Compaction Checkpoints
Honest about failure	`AgentTeam.save_session_state` propagates the `SessionStore` `bool` result, so a silent `False` no longer reports success
Clean unknown-session signal	Restoring an unknown `session_id` returns `False` — no fuzzy fallback that might match the wrong session

Configuration Options

Flag	Description
`--continue`	Resume the most recent root session for this project
`--session <id>`	Resume a specific session — merges saved team state and re-injects each agent’s chat history
`--fork --session <id>`	Fork a session via the hierarchical store; history is copied into the fork, deduplicated on `(role, content)`
`--no-save`	One-off team run — nothing is persisted after kickoff

restore_session_state

Core API that rehydrates team state on resume

save_session_state

Core API that persists team state after kickoff

What Gets Persisted

Team state and per-agent chat history survive a resume via the durable SessionStore; shared memory is optional enrichment.

Layer	Persisted	Restored
`team._state` (task outputs, workflow bookkeeping)	✅ (via `SessionStore.update_session_metadata`)	✅ (via `SessionStore.get_session(...).metadata`)
Per-agent `chat_history` (LLM-visible turns)	✅ (stashed under `_cli_session_chat_history`)	✅ (restored by position; a verbatim prefix already in `chat_history` is not re-added)
`shared_memory` (short/long-term backend)	✅ when enabled — optional enrichment only	✅ when enabled — legacy fallback for pre-#3635 sessions

What does not persist: running tool subprocesses, in-flight streaming state, InteractiveRuntime (ACP/LSP) sessions, and ephemeral in-memory tool caches.

User Interaction Flow

A research team YAML runs Monday and continues Wednesday with every agent’s prior findings intact.

bash

# Monday — kick off the research team
praisonai run research-team.yaml

# Wednesday — continue; each agent's Monday findings replay first
praisonai run research-team.yaml --continue

On Wednesday the adapter resolves Monday’s session, restores team._state, re-injects each agent’s captured chat history, then runs the new prompt — the researcher, analyst, and writer all pick up their earlier context.

Common Patterns

Resume yesterday’s team run:

bash

praisonai run agents.yaml --continue

Use an explicit named session:

bash

praisonai run agents.yaml --session release-checklist-v4

Fork to try a variation without touching the main thread:

bash

praisonai run agents.yaml --fork --session release-checklist-v4

Throwaway run for PII-sensitive input:

bash

praisonai run agents.yaml --no-save

Best Practices

Run from the project root

Git-remote / root-commit identity resolves consistently from the repo root, so --continue always finds the right session.

Fork before risky refactors

--fork --session <id> branches the thread — the parent session is left untouched while you try a variation.

Use –no-save for one-off exploration

Nothing hits disk after kickoff, so PII-sensitive or throwaway prompts leave no session trail.

Skip memory: true in agents.yaml

Session resume no longer needs memory: true. Team --continue writes and reads team state through the durable SessionStore, so a team declared with memory: false (or no memory: at all) resumes just as reliably as one with shared memory enabled. Add memory: true when your agents genuinely need cross-turn semantic recall — not for resume itself.

Project Sessions

How project identity and the session store resolve --continue

Run Command

Full praisonai run reference with session flags

Run Stream Events

Stream YAML / team runs as per-agent NDJSON with --output stream-json

Session Store

The durable, project-scoped store that now backs team resume too

YAML / Team Session Continuity

Quick Start

How It Works

Durable State Guarantees

Configuration Options

What Gets Persisted

User Interaction Flow

Common Patterns

Best Practices

Related