> ## Documentation Index
> Fetch the complete documentation index at: https://praison.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# 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 theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# First run
praisonai run agents.yaml
# Come back tomorrow — team continues where it left off
praisonai run agents.yaml --continue
```
**Upgrade note (PraisonAI PR #3637).** Team `--continue` is now memory-independent and deterministic — it uses the same durable `SessionStore` as single-agent `--continue`. Sessions saved by earlier releases still resume via a one-time legacy fallback through `shared_memory`. No YAML changes, no new flags, no new params — behaviour just gets more reliable.
**The recorded model is restored here too.** `praisonai run agents.yaml --continue` follows the same `run_main` path, so with no explicit `--model` the team resumes on the model it was recorded with. See [Session Model Restore](/docs/features/session-model-restore).
```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
graph LR
subgraph "YAML Session Continuity"
Y[📄 agents.yaml] --> AD[🔌 Adapter]
AD --> R[⏪ restore_session_state]
R --> AS[▶️ astart]
AS --> C[📝 capture chat_history]
C --> SV[💾 save_session_state]
end
classDef yaml fill:#8B0000,stroke:#7C90A0,color:#fff
classDef process fill:#189AB4,stroke:#7C90A0,color:#fff
classDef intermediate fill:#F59E0B,stroke:#7C90A0,color:#fff
classDef result fill:#10B981,stroke:#7C90A0,color:#fff
class Y yaml
class AD,R,AS process
class C intermediate
class SV result
```
## Quick Start
```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
praisonai run agents.yaml
```
The run auto-saves to a project-scoped session — no `memory: true` needed in your YAML.
```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
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.
```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
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`.
```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
graph LR
subgraph "Durable Write Path"
W[💾 save_session_state] --> L[🔒 FileLock]
L --> A[📝 atomic replace]
A --> M[🗄️ SessionStore metadata]
end
classDef write fill:#8B0000,stroke:#7C90A0,color:#fff
classDef lock fill:#F59E0B,stroke:#7C90A0,color:#fff
classDef process fill:#189AB4,stroke:#7C90A0,color:#fff
classDef result fill:#10B981,stroke:#7C90A0,color:#fff
class W write
class L lock
class A process
class M result
```
| 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](/docs/features/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 ` | Resume a specific session — merges saved team state and re-injects each agent's chat history |
| `--fork --session ` | 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 |
Core API that rehydrates team state on resume
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 theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# 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 theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
praisonai run agents.yaml --continue
```
Use an explicit named session:
```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
praisonai run agents.yaml --session release-checklist-v4
```
Fork to try a variation without touching the main thread:
```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
praisonai run agents.yaml --fork --session release-checklist-v4
```
Throwaway run for PII-sensitive input:
```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
praisonai run agents.yaml --no-save
```
***
## Best Practices
Git-remote / root-commit identity resolves consistently from the repo root, so `--continue` always finds the right session.
`--fork --session ` branches the thread — the parent session is left untouched while you try a variation.
Nothing hits disk after kickoff, so PII-sensitive or throwaway prompts leave no session trail.
**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.
***
## Related
How project identity and the session store resolve `--continue`
Full `praisonai run` reference with session flags
Stream YAML / team runs as per-agent NDJSON with `--output stream-json`
The durable, project-scoped store that now backs team resume too