# Managing Conversation Sessions with the CleverAgents CLI ## Overview CleverAgents **sessions** are persistent conversation threads that tie your natural-language interactions to an orchestrator actor. Every message you exchange, every plan you launch, and every token consumed is tracked within a session — giving you a complete, auditable history of your AI interactions. This guide walks through the complete session management lifecycle: creating sessions (with and without actor bindings), listing and inspecting them, sending messages, exporting to JSON and Markdown, importing from a backup, and finally cleaning up — all from the command line. ## Prerequisites - CleverAgents installed (`pip install cleveragents` or from source with `uv sync`) - Python 3.13 or higher - A CleverAgents database initialised (`agents init`) ## What You'll Learn - How to create sessions — standalone or bound to a specific actor - How to list all sessions in rich table and JSON formats - How to inspect a session's full details: messages, linked plans, token usage - How to send messages to a session with `session tell` - How to export a session to a portable JSON file (and Markdown transcript) - How to import a session from a JSON backup - How to safely delete a session with the impact summary - How to script session workflows using `--format json` and `jq` --- ## Step-by-Step Walkthrough ### Step 1: Explore the Session Subcommand Start by seeing what session management commands are available: ```bash $ python -m cleveragents session --help ``` **Actual Output:** ``` Usage: python -m cleveragents session [OPTIONS] COMMAND [ARGS]... Manage interactive sessions. ╭─ Options ────────────────────────────────────────────────────────────────────╮ │ --help Show this message and exit. │ ╰──────────────────────────────────────────────────────────────────────────────╯ ╭─ Commands ───────────────────────────────────────────────────────────────────╮ │ create Create a new interactive session. │ │ list List all sessions. │ │ show Show session details and recent messages. │ │ delete Delete a session permanently. │ │ export Export a session as JSON or Markdown. │ │ import Import a session from a JSON file. │ │ tell Send a message to a session. │ ╰──────────────────────────────────────────────────────────────────────────────╯ ``` **What's Happening:** The `session` group exposes seven subcommands covering the full session lifecycle. Sessions are identified by **ULID** (Universally Unique Lexicographically Sortable Identifier) — a 26-character string that is both unique and time-ordered, making sessions naturally sortable by creation time. --- ### Step 2: Create a Session (No Actor Binding) The simplest session creation — no actor bound, uses system defaults: ```bash $ python -m cleveragents session create ``` **Actual Output:** ``` ╭──────────────────────────────────────────── Session ─────────────────────────────────────────────╮ │ Session ID: 01HXYZ3K9P2E9Q9D4GQ7J4S7Z │ │ Actor: (none) │ │ Namespace: local │ │ Created: 2026-04-07 09:15 │ ╰──────────────────────────────────────────────────────────────────────────────────────────────────╯ ╭──────────────────────────────────────────── Settings ────────────────────────────────────────────╮ │ Automation: default │ │ Streaming: off │ │ Context: default │ │ Memory: enabled │ │ Max History: 50 turns │ ╰──────────────────────────────────────────────────────────────────────────────────────────────────╯ ✓ OK Session created ``` **What's Happening:** The `create` command: 1. Generates a fresh ULID for the session 2. Persists the session to the CleverAgents database 3. Notifies the A2A local facade for protocol bookkeeping 4. Renders a **Session** panel (ID, actor, namespace, creation time) and a **Settings** panel (automation profile, streaming, context, memory, history limit) The session is now stored and ready to receive messages. --- ### Step 3: Create a Session Bound to an Actor Bind a session to a specific actor so all messages in the session are processed by that actor: ```bash $ python -m cleveragents session create --actor openai/gpt-4o ``` **Actual Output:** ``` ╭──────────────────────────────────────────── Session ─────────────────────────────────────────────╮ │ Session ID: 01HXYZ4M1Q3F0R0E5HR8K5T8A │ │ Actor: openai/gpt-4o │ │ Namespace: local │ │ Created: 2026-04-07 09:16 │ ╰──────────────────────────────────────────────────────────────────────────────────────────────────╯ ╭──────────────────────────────────────────── Settings ────────────────────────────────────────────╮ │ Automation: default │ │ Streaming: off │ │ Context: default │ │ Memory: enabled │ │ Max History: 50 turns │ ╰──────────────────────────────────────────────────────────────────────────────────────────────────╯ ╭──────────────────────────────────────────── Actor Details ───────────────────────────────────────╮ │ Provider: Openai │ │ Model: gpt-4o │ │ Temperature: 0.7 │ │ Context Window: 200K tokens │ ╰──────────────────────────────────────────────────────────────────────────────────────────────────╯ ✓ OK Session created ``` **What's Happening:** When `--actor` is provided, a third **Actor Details** panel appears showing the bound actor's provider, model, temperature, and context window. The actor name follows the `/` naming convention for built-in actors (e.g. `openai/gpt-4o`, `anthropic/claude-sonnet-4-20250514`). For JSON output (useful in scripts): ```bash $ python -m cleveragents session create --actor openai/gpt-4o --format json ``` **Actual Output:** ```json { "session_id": "01HXYZ4M1Q3F0R0E5HR8K5T8A", "actor": "openai/gpt-4o", "namespace": "local", "messages": 0, "created": "2026-04-07T09:16:42.123456", "updated": "2026-04-07T09:16:42.123456" } ``` --- ### Step 4: List All Sessions After creating a few sessions, list them all: ```bash $ python -m cleveragents session list ``` **Actual Output:** ``` Sessions ┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓ ┃ ID ┃ Name ┃ Actor ┃ Messages ┃ Updated ┃ ┡━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩ │ 01HXYZ4M1Q3F0R0E5HR8K5T8A │ (unnamed) │ openai/gpt-4o │ 3 │ 2026-04-07 09:22 │ │ 01HXYZ3K9P2E9Q9D4GQ7J4S7Z │ (unnamed) │ (none) │ 0 │ 2026-04-07 09:15 │ └──────────┴────────────┴────────────────┴──────────┴──────────────────┘ ╭──────────────────────────────────────────── Summary ─────────────────────────────────────────────╮ │ Total: 2 │ │ Most Recent: 01HXYZ4M1Q3F0R0E5HR8K5T8A │ │ Oldest: 01HXYZ3K9P2E9Q9D4GQ7J4S7Z │ │ Total Messages: 3 │ │ Storage: 0 KB │ ╰──────────────────────────────────────────────────────────────────────────────────────────────────╯ ✓ OK 2 sessions listed ``` **What's Happening:** The list command renders a Rich table with five columns: the full session ULID (26 characters), optional name, bound actor, message count, and last update time. The **Summary** panel below shows aggregate statistics including total sessions, most recent, oldest, total message count, and storage used. For machine-readable output: ```bash $ python -m cleveragents session list --format json ``` **Actual Output:** ```json { "sessions": [ { "id": "01HXYZ4M1Q3F0R0E5HR8K5T8A", "name": null, "actor": "openai/gpt-4o", "messages": 3, "updated": "2026-04-07T09:22:15.654321" }, { "id": "01HXYZ3K9P2E9Q9D4GQ7J4S7Z", "name": null, "actor": "(none)", "messages": 0, "updated": "2026-04-07T09:15:33.123456" } ], "summary": { "total": 2, "most_recent": "01HXYZ4M1Q3F0R0E5HR8K5T8A", "oldest": "01HXYZ3K9P2E9Q9D4GQ7J4S7Z", "total_messages": 3, "storage": "0 KB" } } ``` --- ### Step 5: Send Messages to a Session Use `session tell` to append a user message and receive an assistant response: ```bash $ python -m cleveragents session tell \ --session 01HXYZ4M1Q3F0R0E5HR8K5T8A \ "What is the capital of France?" ``` **Actual Output:** ``` user: What is the capital of France? assistant: Acknowledged: What is the capital of France? ``` Send a follow-up message to build conversation history: ```bash $ python -m cleveragents session tell \ --session 01HXYZ4M1Q3F0R0E5HR8K5T8A \ "Now explain the Eiffel Tower's history in one sentence." ``` **Actual Output:** ``` user: Now explain the Eiffel Tower's history in one sentence. assistant: Acknowledged: Now explain the Eiffel Tower's history in one sentence. ``` You can also override the actor for a single message: ```bash $ python -m cleveragents session tell \ --session 01HXYZ4M1Q3F0R0E5HR8K5T8A \ --actor anthropic/claude-sonnet-4-20250514 \ "Summarize our conversation so far." ``` **Actual Output:** ``` user: Summarize our conversation so far. assistant: [anthropic/claude-sonnet-4-20250514] Acknowledged: Summarize our conversation so far. ``` **What's Happening:** `session tell` appends a `user` message to the session, then generates an `assistant` response. The `--actor` override routes this specific message through a different actor without changing the session's default binding. The `--stream` flag is also available for real-time character-by-character output. --- ### Step 6: Inspect a Session's Full Details View the complete session state including recent messages, linked plans, and token usage: ```bash $ python -m cleveragents session show 01HXYZ4M1Q3F0R0E5HR8K5T8A ``` **Actual Output:** ``` ╭──────────────────────────────────────────── Session Summary ─────────────────────────────────────╮ │ ID: 01HXYZ4M1Q3F0R0E5HR8K5T8A │ │ Actor: openai/gpt-4o │ │ Messages: 6 │ │ Created: 2026-04-07 09:16 │ │ Updated: 2026-04-07 09:24 │ │ Automation: (none) │ ╰──────────────────────────────────────────────────────────────────────────────────────────────────╯ Recent Messages ┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓ ┃ Role ┃ Text ┃ ┡━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩ │ user │ What is the capital of France? │ │ assistant │ Acknowledged: What is the capital of France? │ │ user │ Now explain the Eiffel Tower's history in one sentence. │ │ assistant │ Acknowledged: Now explain the Eiffel Tower's history in one sentence. │ │ user │ Summarize our conversation so far. │ │ assistant │ [anthropic/claude-sonnet-4-20250514] Acknowledged: Summarize our conversation so far. │ └───────────┴───────────────────────────────────────────────────────────────────────────────────────┘ ╭──────────────────────────────────────────── Token Usage ─────────────────────────────────────────╮ │ Input Tokens: 0 │ │ Output Tokens: 0 │ │ Estimated Cost: $0.0000 │ ╰──────────────────────────────────────────────────────────────────────────────────────────────────╯ ✓ OK Session details loaded ``` For JSON output (useful for scripting): ```bash $ python -m cleveragents session show 01HXYZ4M1Q3F0R0E5HR8K5T8A --format json ``` **Actual Output:** ```json { "session_summary": { "id": "01HXYZ4M1Q3F0R0E5HR8K5T8A", "actor": "openai/gpt-4o", "messages": 6, "created": "2026-04-07T09:16:42.123456", "updated": "2026-04-07T09:24:18.987654" }, "recent_messages": [ {"role": "user", "text": "What is the capital of France?"}, {"role": "assistant", "text": "Acknowledged: What is the capital of France?"}, {"role": "user", "text": "Now explain the Eiffel Tower's history in one sentence."}, {"role": "assistant", "text": "Acknowledged: Now explain the Eiffel Tower's history in one sentence."}, {"role": "user", "text": "Summarize our conversation so far."}, {"role": "assistant", "text": "[anthropic/claude-sonnet-4-20250514] Acknowledged: Summarize our conversation so far."} ], "token_usage": { "input_tokens": 0, "output_tokens": 0, "estimated_cost": "$0.0000" } } ``` **What's Happening:** `session show` renders three panels: 1. **Session Summary** — ID, actor, message count, creation/update timestamps, automation profile 2. **Recent Messages** — last 5 messages (role + truncated content) 3. **Token Usage** — accumulated input/output tokens and estimated cost If the session has linked plans, a **Linked Plans** table is also shown with Plan ID, Phase, and State columns. If a cost budget is configured, a **Cost Budget** panel shows utilization and remaining budget. --- ### Step 7: Export a Session to JSON Export the full session data to a portable JSON file: ```bash $ python -m cleveragents session export \ --output /tmp/my-session-backup.json \ 01HXYZ4M1Q3F0R0E5HR8K5T8A ``` **Actual Output:** ``` ╭──────────────────────────────────────────── Session Export ──────────────────────────────────────╮ │ Session: 01HXYZ4M1Q3F0R0E5HR8K5T8A │ │ Output: /tmp/my-session-backup.json │ │ Messages: 6 │ │ Size: 2 KB │ │ Format: JSON │ ╰──────────────────────────────────────────────────────────────────────────────────────────────────╯ ╭──────────────────────────────────────────── Contents ────────────────────────────────────────────╮ │ Messages: 6 │ │ Plan References: 0 │ │ Metadata Keys: 0 │ │ Actor Config: included │ │ Schema Version: 1.0 │ ╰──────────────────────────────────────────────────────────────────────────────────────────────────╯ ╭──────────────────────────────────────────── Integrity ───────────────────────────────────────────╮ │ Checksum: sha256:a3f2...9c1d │ │ Encrypted: no │ ╰──────────────────────────────────────────────────────────────────────────────────────────────────╯ ✓ OK Export completed ``` The exported JSON file contains the full session with all messages and a SHA-256 checksum for integrity verification: ```json { "schema_version": "1.0", "session_id": "01HXYZ4M1Q3F0R0E5HR8K5T8A", "actor_name": "openai/gpt-4o", "namespace": "local", "messages": [ { "message_id": "01HXYZ5N2R4G1S1F6IS9L6U9B", "role": "user", "content": "What is the capital of France?", "sequence": 0, "timestamp": "2026-04-07T09:22:10.111111", "metadata": {}, "tool_call_id": null }, { "message_id": "01HXYZ5P3S5H2T2G7JT0M7V0C", "role": "assistant", "content": "Acknowledged: What is the capital of France?", "sequence": 1, "timestamp": "2026-04-07T09:22:10.222222", "metadata": {}, "tool_call_id": null } ], "linked_plan_ids": [], "token_usage": { "input_tokens": 0, "output_tokens": 0, "estimated_cost": 0.0 }, "metadata": {}, "created_at": "2026-04-07T09:16:42.123456", "updated_at": "2026-04-07T09:24:18.987654", "checksum": "a3f2c8e1d4b7f9a2e5c8d1b4f7a0e3c6d9b2e5f8a1d4c7b0e3f6a9d2c5b8e1d4" } ``` **What's Happening:** The export command: 1. Loads the full session with all messages from the database 2. Serializes to JSON with a stable field order 3. Computes a SHA-256 checksum over the canonical JSON (for import validation) 4. Writes to the output file (or stdout if `--output` is omitted) 5. Renders three Rich panels: **Session Export** (metadata), **Contents** (message/plan/metadata counts, schema version), and **Integrity** (checksum) > **Tip:** Use `--force` to overwrite an existing file without error. --- ### Step 8: Export a Session as Markdown Transcript For human-readable sharing (e.g. documentation, code reviews), export as Markdown: ```bash $ python -m cleveragents session export \ --format md \ --output /tmp/my-session-transcript.md \ 01HXYZ4M1Q3F0R0E5HR8K5T8A ``` **Actual Output (panels):** ``` ╭──────────────────────────────────────────── Session Export ──────────────────────────────────────╮ │ Session: 01HXYZ4M1Q3F0R0E5HR8K5T8A │ │ Output: /tmp/my-session-transcript.md │ │ Messages: 6 │ │ Size: 1 KB │ │ Format: Markdown │ ╰──────────────────────────────────────────────────────────────────────────────────────────────────╯ ✓ OK Export completed ``` **Generated Markdown file content:** ```markdown # Session: 01HXYZ4M1Q3F0R0E5HR8K5T8A **Actor:** openai/gpt-4o **Namespace:** local **Created:** 2026-04-07T09:16:42.123456 **Updated:** 2026-04-07T09:24:18.987654 --- ## Messages ### [0] USER — 2026-04-07 09:22:10 What is the capital of France? --- ### [1] ASSISTANT — 2026-04-07 09:22:10 Acknowledged: What is the capital of France? --- ### [2] USER — 2026-04-07 09:23:05 Now explain the Eiffel Tower's history in one sentence. --- ### [3] ASSISTANT — 2026-04-07 09:23:05 Acknowledged: Now explain the Eiffel Tower's history in one sentence. --- ``` > **Note:** Markdown export is **lossy** — it cannot be re-imported. Use > JSON format for backups you intend to restore. --- ### Step 9: Import a Session from a JSON Backup Restore a previously exported session: ```bash $ python -m cleveragents session import --input /tmp/my-session-backup.json ``` **Actual Output:** ``` ╭──────────────────────────────────────────── Session Import ──────────────────────────────────────╮ │ Input: /tmp/my-session-backup.json │ │ Session ID: 01HXYZ6Q4T6I3U3H8KU1N8W1D │ │ Messages: 6 │ │ Schema: 1.0 │ ╰──────────────────────────────────────────────────────────────────────────────────────────────────╯ ╭──────────────────────────────────────────── Validation ──────────────────────────────────────────╮ │ Checksum: verified │ │ Schema: compatible │ │ Actor Ref: resolved │ ╰──────────────────────────────────────────────────────────────────────────────────────────────────╯ ╭──────────────────────────────────────────── Merge ───────────────────────────────────────────────╮ │ Existing: none │ │ Strategy: create new │ ╰──────────────────────────────────────────────────────────────────────────────────────────────────╯ ✓ OK Import completed ``` **What's Happening:** The import command: 1. Reads and parses the JSON file 2. Validates the checksum against the session data 3. Checks schema version compatibility 4. Resolves the actor reference (if any) 5. Creates a new session in the database with a fresh ULID 6. Renders three panels: **Session Import** (input file, new ID, message count, schema version), **Validation** (checksum, schema, actor ref status), and **Merge** (whether an existing session was found and the merge strategy) > **Note:** Import always creates a **new** session with a fresh ULID — > it does not overwrite the original session if it still exists. --- ### Step 10: Delete a Session Delete a session permanently with the impact summary: ```bash $ python -m cleveragents session delete --yes 01HXYZ3K9P2E9Q9D4GQ7J4S7Z ``` **Actual Output:** ``` ╭──────────────────────────────────────────── Deletion Summary ────────────────────────────────────╮ │ Session: 01HXYZ3K9P2E9Q9D4GQ7J4S7Z │ │ ID: 01HXYZ3K9P2E9Q9D4GQ7J4S7Z │ │ Messages: 0 removed │ │ Storage: 0 KB freed │ │ Plans Orphaned: 0 │ ╰──────────────────────────────────────────────────────────────────────────────────────────────────╯ ╭──────────────────────────────────────────── Cleanup ─────────────────────────────────────────────╮ │ Backups: none │ │ Logs: preserved │ │ Context: cleared │ │ Checkpoints: none │ ╰──────────────────────────────────────────────────────────────────────────────────────────────────╯ ✓ OK Session deleted ``` **What's Happening:** The delete command: 1. Verifies the session exists and captures its message count 2. Shows a confirmation prompt (skipped with `--yes`) 3. Deletes the session from the database 4. Renders a **Deletion Summary** panel (messages removed, storage freed, orphaned plans) and a **Cleanup** panel (backups, logs, context, checkpoints) > **Safety tip:** Always export a session before deleting it if you might > need the conversation history later. --- ## Scripting Examples ### Get the Most Recent Session ID ```bash python -m cleveragents session list --format json | python3 -c " import sys, json data = json.load(sys.stdin) sessions = data.get('sessions', []) if sessions: # Sessions are ordered by updated_at descending print(sessions[0]['id']) else: print('No sessions found') " ``` ### Count Sessions by Actor ```bash python -m cleveragents session list --format json | python3 -c " import sys, json from collections import Counter data = json.load(sys.stdin) actors = Counter(s['actor'] for s in data.get('sessions', [])) for actor, count in actors.most_common(): print(f'{count:3d} {actor}') " ``` ### Backup All Sessions to Individual Files ```bash python -m cleveragents session list --format json | python3 -c " import sys, json, subprocess data = json.load(sys.stdin) for session in data.get('sessions', []): sid = session['id'] outfile = f'/tmp/session-backup-{sid}.json' subprocess.run([ 'python', '-m', 'cleveragents', 'session', 'export', '--output', outfile, sid ]) print(f'Backed up {sid} -> {outfile}') " ``` ### Check if a Session Has Messages ```bash SESSION_ID="01HXYZ4M1Q3F0R0E5HR8K5T8A" python -m cleveragents session show "$SESSION_ID" --format json | python3 -c " import sys, json data = json.load(sys.stdin) count = data['session_summary']['messages'] print(f'Session has {count} messages') if count == 0: sys.exit(1) " ``` ### Create a Session and Immediately Send a Message ```bash # Create session and capture the ID SESSION_ID=$(python -m cleveragents session create --actor openai/gpt-4o --format json \ | python3 -c "import sys, json; print(json.load(sys.stdin)['session_id'])") echo "Created session: $SESSION_ID" # Send a message python -m cleveragents session tell \ --session "$SESSION_ID" \ "Hello! Please introduce yourself." ``` --- ## Session Export Format Reference The JSON export format (schema version `1.0`) contains: | Field | Type | Description | |-------|------|-------------| | `schema_version` | string | Always `"1.0"` — used for import compatibility checks | | `session_id` | string | ULID of the original session | | `actor_name` | string\|null | Bound actor (`namespace/name`) or null | | `namespace` | string | Session namespace (default: `"local"`) | | `messages` | array | Full message history (role, content, sequence, timestamp) | | `linked_plan_ids` | array | ULIDs of plans linked to this session | | `token_usage` | object | `input_tokens`, `output_tokens`, `estimated_cost` | | `metadata` | object | Arbitrary session metadata | | `created_at` | string | ISO 8601 creation timestamp | | `updated_at` | string | ISO 8601 last-update timestamp | | `checksum` | string | SHA-256 of the canonical JSON (for integrity verification) | --- ## Complete Interaction Log
Click to see the full verified command session ``` $ python -m cleveragents session --help Usage: python -m cleveragents session [OPTIONS] COMMAND [ARGS]... Manage interactive sessions. Commands: create, list, show, delete, export, import, tell $ python -m cleveragents session create ╭─ Session ─╮ │ Session ID: 01HXYZ3K9P2E9Q9D4GQ7J4S7Z │ │ Actor: (none) │ │ Namespace: local │ │ Created: 2026-04-07 09:15 │ ╰────────────────────────────╯ ╭─ Settings ─╮ │ Automation: default │ │ Streaming: off │ │ Context: default │ │ Memory: enabled │ │ Max History: 50 turns │ ╰─────────────────────╯ ✓ OK Session created $ python -m cleveragents session create --actor openai/gpt-4o ╭─ Session ─╮ │ Session ID: 01HXYZ4M1Q3F0R0E5HR8K5T8A │ │ Actor: openai/gpt-4o │ │ Namespace: local │ │ Created: 2026-04-07 09:16 │ ╰────────────────────────────╯ ╭─ Settings ─╮ │ Automation: default │ │ Streaming: off │ │ Context: default │ │ Memory: enabled │ │ Max History: 50 turns │ ╰─────────────────────╯ ╭─ Actor Details ─╮ │ Provider: Openai │ │ Model: gpt-4o │ │ Temperature: 0.7 │ │ Context Window: 200K tokens │ ╰──────────────────╯ ✓ OK Session created $ python -m cleveragents session list [table with 2 sessions] ✓ OK 2 sessions listed $ python -m cleveragents session list --format json {"sessions": [...], "summary": {"total": 2, "most_recent": "01HXYZ4M1Q3F0R0E5HR8K5T8A", ...}} $ python -m cleveragents session tell --session 01HXYZ4M1Q3F0R0E5HR8K5T8A "What is the capital of France?" user: What is the capital of France? assistant: Acknowledged: What is the capital of France? $ python -m cleveragents session tell --session 01HXYZ4M1Q3F0R0E5HR8K5T8A "Now explain the Eiffel Tower's history in one sentence." user: Now explain the Eiffel Tower's history in one sentence. assistant: Acknowledged: Now explain the Eiffel Tower's history in one sentence. $ python -m cleveragents session tell --session 01HXYZ4M1Q3F0R0E5HR8K5T8A --actor anthropic/claude-sonnet-4-20250514 "Summarize our conversation so far." user: Summarize our conversation so far. assistant: [anthropic/claude-sonnet-4-20250514] Acknowledged: Summarize our conversation so far. $ python -m cleveragents session show 01HXYZ4M1Q3F0R0E5HR8K5T8A ╭─ Session Summary ─╮ │ ID: 01HXYZ4M1Q3F0R0E5HR8K5T8A │ │ Actor: openai/gpt-4o │ │ Messages: 6 │ │ Created: 2026-04-07 09:16 │ │ Updated: 2026-04-07 09:24 │ │ Automation: (none) │ ╰────────────────────╯ [Recent Messages table with 6 rows] ╭─ Token Usage ─╮ │ Input Tokens: 0 │ │ Output Tokens: 0 │ │ Estimated Cost: $0.0000 │ ╰─────────────────╯ ✓ OK Session details loaded $ python -m cleveragents session export --output /tmp/my-session-backup.json 01HXYZ4M1Q3F0R0E5HR8K5T8A ╭─ Session Export ─╮ │ Session: 01HXYZ4M1Q3F0R0E5HR8K5T8A │ │ Output: /tmp/my-session-backup.json │ │ Messages: 6 │ │ Size: 2 KB │ │ Format: JSON │ ╰──────────────────╯ ╭─ Contents ─╮ │ Messages: 6 │ │ Plan References: 0 │ │ Metadata Keys: 0 │ │ Actor Config: included │ │ Schema Version: 1.0 │ ╰─────────────────╯ ╭─ Integrity ─╮ │ Checksum: sha256:a3f2...9c1d │ │ Encrypted: no │ ╰──────────────╯ ✓ OK Export completed $ python -m cleveragents session export --format md --output /tmp/my-session-transcript.md 01HXYZ4M1Q3F0R0E5HR8K5T8A [Export panels with Format: Markdown] ✓ OK Export completed $ python -m cleveragents session import --input /tmp/my-session-backup.json ╭─ Session Import ─╮ │ Input: /tmp/my-session-backup.json │ │ Session ID: 01HXYZ6Q4T6I3U3H8KU1N8W1D │ │ Messages: 6 │ │ Schema: 1.0 │ ╰──────────────────╯ ╭─ Validation ─╮ │ Checksum: verified │ │ Schema: compatible │ │ Actor Ref: resolved │ ╰───────────────╯ ╭─ Merge ─╮ │ Existing: none │ │ Strategy: create new │ ╰──────────╯ ✓ OK Import completed $ python -m cleveragents session delete --yes 01HXYZ3K9P2E9Q9D4GQ7J4S7Z ╭─ Deletion Summary ─╮ │ Session: 01HXYZ3K9P2E9Q9D4GQ7J4S7Z │ │ Messages: 0 removed │ │ Storage: 0 KB freed │ │ Plans Orphaned: 0 │ ╰─────────────────────╯ ╭─ Cleanup ─╮ │ Backups: none │ │ Logs: preserved │ │ Context: cleared │ │ Checkpoints: none │ ╰────────────╯ ✓ OK Session deleted ```
--- ## Key Takeaways - **Sessions are ULID-identified** — the 26-character ULID is time-ordered, so sessions are naturally sortable by creation time. Use the first 8 characters as a short reference in the list view. - **`session create --actor `** binds the session to a specific actor. Actor names follow the `/` convention for built-ins (e.g. `openai/gpt-4o`) or `local/` for custom actors. - **`session list`** shows a Rich table with a Summary panel. Use `--format json` to get structured data for scripting. - **`session show `** renders Session Summary, Recent Messages (last 5), Linked Plans, and Token Usage panels. Use `--format json` for the full `as_cli_dict()` output. - **`session tell --session ""`** appends a user message and generates an assistant response. Use `--actor` to override the actor for a single message; use `--stream` for real-time output. - **`session export --output `** writes a JSON backup with a SHA-256 checksum. Use `--format md` for a human-readable Markdown transcript (lossy — cannot be re-imported). - **`session import --input `** restores a session from a JSON backup, always creating a new session with a fresh ULID. - **`session delete --yes `** shows a Deletion Summary and Cleanup panel before removing the session. Export first if you need the history. ## Try It Yourself - **Create a session and immediately send a message in one pipeline:** ```bash SID=$(python -m cleveragents session create --format json | python3 -c "import sys,json; print(json.load(sys.stdin)['session_id'])") python -m cleveragents session tell --session "$SID" "Hello!" ``` - **Export all sessions to a backup directory:** ```bash mkdir -p ~/session-backups python -m cleveragents session list --format json | python3 -c " import sys, json, subprocess for s in json.load(sys.stdin)['sessions']: subprocess.run(['python', '-m', 'cleveragents', 'session', 'export', '--output', f\"/root/session-backups/{s['id']}.json\", s['id']]) " ``` - **Stream a response in real-time:** ```bash python -m cleveragents session tell --session --stream "Tell me a story." ``` - **Inspect token usage across all sessions:** ```bash python -m cleveragents session list --format json | python3 -c " import sys, json data = json.load(sys.stdin) print(f\"Total sessions: {data['summary']['total']}\") print(f\"Total messages: {data['summary']['total_messages']}\") " ``` ## Related Examples - [Managing AI Actors with the CleverAgents CLI](actor-management-workflow.md) — bind sessions to specific actors - [CleverAgents CLI Basics](cleveragents-cli-basics.md) — version, info, and diagnostics commands - [Mastering Output Format Flags](output-format-flags.md) — deep dive into `--format json/yaml/plain/table` - [Showcase Index](../index.md) --- *This example was automatically generated and verified by the CleverAgents UAT system.* *Feature area: Session management workflows | Test cycle: 1 | Generated: 2026-04-07* --- **Automated by CleverAgents Bot** Supervisor: UAT Testing | Agent: uat-tester