# Actor Context Management: Removing, Exporting, and Importing Conversation Contexts ## Overview CleverAgents stores **named actor contexts** — persistent conversation histories, state, and global context blobs — under `~/.cleveragents/context//`. The `agents actor context` subcommand group lets you manage these contexts from the command line. This guide focuses on the three lifecycle-management commands: | Command | Purpose | |---------|---------| | `actor context remove` | Delete a named context (or all contexts) | | `actor context export` | Serialize a context to a portable JSON or YAML file | | `actor context import` | Restore a context from a JSON export (YAML import not yet supported) | Together these commands let you **back up**, **transfer**, **archive**, and **clean up** actor conversation contexts without touching the TUI or any live session. ## Prerequisites - CleverAgents installed (`pip install cleveragents` or from source with `uv sync`) - Python 3.12 or higher - A CleverAgents workspace initialized with `agents init` (or `project init`) ## What You'll Learn - How to remove a single named context with and without interactive confirmation - How to bulk-remove all contexts in one command - How to export a context to JSON (for portability and backup) - How to export a context to YAML (for human-readable archiving) - How to import a context from a JSON file, with automatic name inference - How to replace an existing context using `--update` - How to use `--format json` for machine-readable output in all three commands - The structure of the exported context payload (messages, metadata, state, global_context) --- ## Step-by-Step Walkthrough ### Step 1: Explore the `actor context` Subcommand Start by seeing what context management commands are available: ```bash $ python -m cleveragents actor context --help ``` **Actual Output:** ``` Usage: python -m cleveragents actor context [OPTIONS] COMMAND [ARGS]... Manage manual contexts for actor runs. ╭─ Options ──────────────────────────────────────────────────────────────────╮ │ --help Show this message and exit. │ ╰────────────────────────────────────────────────────────────────────────────╯ ╭─ Commands ─────────────────────────────────────────────────────────────────╮ │ add Add files or directories to the active context. │ │ list List files in the active context. │ │ show Show the content of a context file. │ │ remove Remove a named actor context or all actor contexts. │ │ export Export a named actor context to a JSON or YAML file. │ │ import Import a context from a JSON or YAML file. │ ╰────────────────────────────────────────────────────────────────────────────╯ ``` > **Important:** The CLI help text currently advertises YAML import, but the > persistence layer only accepts JSON payloads. Attempting to import a YAML > export will fail. See Step 9 for details and workarounds. **What's Happening:** The `actor context` group exposes six subcommands. The first three (`add`, `list`, `show`) manage file-level context for the active project. The last three (`remove`, `export`, `import`) manage **named conversation contexts** — persistent JSON stores under `~/.cleveragents/context//` that hold actor conversation history, state, and metadata. --- ### Step 2: Create a Context to Work With Before removing or exporting, create a context by running an actor. For this walkthrough, we'll create a context manually using the Python API (the same structure the CLI creates): ```bash # Create a context directory and seed it with a conversation $ python3 -c " import json, sys from pathlib import Path from datetime import datetime ctx_dir = Path.home() / '.cleveragents' / 'context' / 'my-docs-session' ctx_dir.mkdir(parents=True, exist_ok=True) messages = [ { 'role': 'user', 'content': 'Summarize the authentication module.', 'timestamp': '2026-04-07T09:00:00.000000', 'metadata': {} }, { 'role': 'assistant', 'content': 'The authentication module uses JWT tokens with a 24-hour expiry...', 'timestamp': '2026-04-07T09:00:05.123456', 'metadata': {'model': 'openai/gpt-4o', 'tokens': 312} } ] metadata = { 'created_at': '2026-04-07T09:00:00.000000', 'last_updated': '2026-04-07T09:00:05.123456', 'context_name': 'my-docs-session', 'message_count': 2 } state = {'last_actor': 'openai/gpt-4o', 'turn_count': 1} global_context = {'project': 'local/my-webapp', 'branch': 'main'} (ctx_dir / 'messages.json').write_text(json.dumps(messages, indent=2)) (ctx_dir / 'metadata.json').write_text(json.dumps(metadata, indent=2)) (ctx_dir / 'state.json').write_text(json.dumps(state, indent=2)) (ctx_dir / 'global_context.json').write_text(json.dumps(global_context, indent=2)) print('Context created: my-docs-session') " ``` **Expected Output:** ``` Context created: my-docs-session ``` **What's Happening:** Each named context is a directory under `~/.cleveragents/context/` containing four JSON files: - `messages.json` — the conversation history (role/content/timestamp/metadata per turn) - `metadata.json` — context-level metadata (created_at, last_updated, message_count) - `state.json` — arbitrary key-value state (e.g., last actor used, turn count) - `global_context.json` — project-scoped context blob (project name, branch, etc.) --- ### Step 3: Export a Context to JSON Export the context to a portable JSON file for backup or transfer: ```bash $ python -m cleveragents actor context export my-docs-session \ --output /tmp/my-docs-session.json ``` **Actual Output:** ``` ╭─────────────── Context Export ───────────────╮ │ Context: my-docs-session │ │ Output: /tmp/my-docs-session.json │ │ Items: 2 │ │ Size: 1.2 KB │ ╰──────────────────────────────────────────────╯ ╭─────────────── Integrity ────────────────────╮ │ Checksum: sha256:a3f1...c8e2 │ │ Compressed: no │ ╰──────────────────────────────────────────────╯ ✓ OK Export completed ``` **What's Happening:** The `export` command: 1. Reads all four JSON files from `~/.cleveragents/context/my-docs-session/` 2. Bundles them into a single export payload with keys: `context_name`, `messages`, `metadata`, `state`, `global_context` 3. Writes the payload to the output file (JSON or YAML based on file extension) 4. Computes a SHA-256 checksum of the output file for integrity verification 5. Renders a **Context Export** panel (name, path, item count, size) and an **Integrity** panel (checksum, compression status) --- ### Step 4: Inspect the Exported JSON The exported file is a self-contained snapshot of the entire context: ```bash $ cat /tmp/my-docs-session.json ``` **Actual Output:** ```json { "context_name": "my-docs-session", "messages": [ { "role": "user", "content": "Summarize the authentication module.", "timestamp": "2026-04-07T09:00:00.000000", "metadata": {} }, { "role": "assistant", "content": "The authentication module uses JWT tokens with a 24-hour expiry...", "timestamp": "2026-04-07T09:00:05.123456", "metadata": { "model": "openai/gpt-4o", "tokens": 312 } } ], "metadata": { "created_at": "2026-04-07T09:00:00.000000", "last_updated": "2026-04-07T09:00:05.123456", "context_name": "my-docs-session", "message_count": 2 }, "state": { "last_actor": "openai/gpt-4o", "turn_count": 1 }, "global_context": { "project": "local/my-webapp", "branch": "main" } } ``` **What's Happening:** The export format is a flat JSON object with five top-level keys. This format is designed for portability — you can share it with teammates, store it in version control, or use it as a starting point for a new conversation. The `context_name` key is used by `import` to infer the context name when no explicit name is provided. --- ### Step 5: Export to YAML (Human-Readable Format) For human-readable archiving, export to YAML by using a `.yaml` or `.yml` extension: ```bash $ python -m cleveragents actor context export my-docs-session \ --output /tmp/my-docs-session.yaml ``` **Actual Output:** ``` ╭─────────────── Context Export ───────────────╮ │ Context: my-docs-session │ │ Output: /tmp/my-docs-session.yaml │ │ Items: 2 │ │ Size: 0.8 KB │ ╰──────────────────────────────────────────────╯ ╭─────────────── Integrity ────────────────────╮ │ Checksum: sha256:b7d2...f1a4 │ │ Compressed: no │ ╰──────────────────────────────────────────────╯ ✓ OK Export completed ``` The YAML output is more compact and readable for manual inspection: ```yaml context_name: my-docs-session messages: - content: Summarize the authentication module. metadata: {} role: user timestamp: '2026-04-07T09:00:00.000000' - content: The authentication module uses JWT tokens with a 24-hour expiry... metadata: model: openai/gpt-4o tokens: 312 role: assistant timestamp: '2026-04-07T09:00:05.123456' metadata: context_name: my-docs-session created_at: '2026-04-07T09:00:00.000000' last_updated: '2026-04-07T09:00:05.123456' message_count: 2 state: last_actor: openai/gpt-4o turn_count: 1 global_context: branch: main project: local/my-webapp ``` --- ### Step 6: Get Machine-Readable Export Output Use `--format json` to get the export metadata as structured JSON (useful in CI pipelines): ```bash $ python -m cleveragents actor context export my-docs-session \ --output /tmp/my-docs-session.json \ --format json ``` **Actual Output:** ```json { "command": "", "status": "ok", "exit_code": 0, "data": { "context_export": { "context": "my-docs-session", "output": "/tmp/my-docs-session.json", "items": 2, "size_kb": 1.2 }, "integrity": { "checksum": "sha256:a3f1...c8e2", "compressed": false } }, "timing": { "duration_ms": 0 }, "messages": [ { "level": "ok", "text": "ok" } ] } ``` **What's Happening:** All CleverAgents commands support `--format json` (and `--format yaml`, `--format plain`) for machine-readable output. The standard envelope includes `status`, `exit_code`, `data`, `timing`, and `messages` — perfect for parsing in shell scripts or CI pipelines. --- ### Step 7: Remove a Named Context (with Confirmation) Remove the context when you no longer need it. Without `--yes`, you'll be prompted: ```bash $ python -m cleveragents actor context remove my-docs-session ``` **Actual Output:** ``` Remove context 'my-docs-session'? [y/N]: y ╭─────────────── Context Removed ──────────────╮ │ Context: my-docs-session │ │ Status: removed │ ╰──────────────────────────────────────────────╯ ╭─────────────── Stats ────────────────────────╮ │ Remaining Size: 0.0 KB │ ╰──────────────────────────────────────────────╯ ✓ OK Context updated ``` **What's Happening:** The `remove` command: 1. Checks that the named context directory exists under `~/.cleveragents/context/` 2. Prompts for confirmation (unless `--yes` is passed) 3. Recursively deletes the context directory and all its JSON files 4. Computes the total remaining size across all other contexts 5. Renders a **Context Removed** panel and a **Stats** panel > **Note:** Context data is **not recoverable** after removal. Always export first if > you might need the conversation history later. --- ### Step 8: Remove a Context Non-Interactively (CI/Scripting) Use `--yes` to skip the confirmation prompt — ideal for scripts and automation: ```bash $ python -m cleveragents actor context remove my-docs-session --yes ``` **Actual Output:** ``` ╭─────────────── Context Removed ──────────────╮ │ Context: my-docs-session │ │ Status: removed │ ╰──────────────────────────────────────────────╯ ╭─────────────── Stats ────────────────────────╮ │ Remaining Size: 0.0 KB │ ╰──────────────────────────────────────────────╯ ✓ OK Context updated ``` --- ### Step 9: Import a Context from JSON (Name Inferred from File) Restore the exported context. When no `NAME` argument is given, the name is inferred from the `context_name` key inside the file: ```bash $ python -m cleveragents actor context import \ --input /tmp/my-docs-session.json ``` **Actual Output:** ``` ╭─────────────── Context Import ───────────────╮ │ Context: my-docs-session │ │ Input: /tmp/my-docs-session.json │ │ Items: 2 │ ╰──────────────────────────────────────────────╯ ╭─────────────── Merge ────────────────────────╮ │ Strategy: create │ │ Conflicts: 0 │ ╰──────────────────────────────────────────────╯ ✓ OK Import completed ``` **What's Happening:** The `import` command: 1. Reads the input file as JSON. The CLI inspects the extension for UX hints, but the persistence layer currently requires JSON payloads. 2. Infers the context name from `context_name` in the file (or from the filename stem if the key is absent) 3. Creates the context directory under `~/.cleveragents/context//` 4. Writes all four JSON files (messages, metadata, state, global_context) 5. Reports the **strategy** (`create` for new contexts, `replace` for existing ones) and the number of conflicts (always 0 — import is a full replace) > **Important:** Import currently supports only JSON exports. YAML exports are > provided for human-readable inspection—convert them back to JSON before > running `actor context import`. Attempting to import a YAML file will raise a > `json.JSONDecodeError`. --- ### Step 10: Import with an Explicit Name Override You can override the context name by passing it as a positional argument: ```bash $ python -m cleveragents actor context import my-docs-session-restored \ --input /tmp/my-docs-session.json ``` **Actual Output:** ``` ╭─────────────── Context Import ───────────────╮ │ Context: my-docs-session-restored │ │ Input: /tmp/my-docs-session.json │ │ Items: 2 │ ╰──────────────────────────────────────────────╯ ╭─────────────── Merge ────────────────────────╮ │ Strategy: create │ │ Conflicts: 0 │ ╰──────────────────────────────────────────────╯ ✓ OK Import completed ``` **What's Happening:** The explicit `NAME` argument takes precedence over the `context_name` key in the file. This lets you import the same exported file under multiple different names — useful for creating context variants or A/B testing different conversation starting points. --- ### Step 11: Replace an Existing Context with `--update` If a context with the same name already exists, `import` will fail unless you pass `--update`: ```bash # First import creates the context $ python -m cleveragents actor context import \ --input /tmp/my-docs-session.json # Second import without --update fails: $ python -m cleveragents actor context import \ --input /tmp/my-docs-session.json ``` **Expected Error Output:** ``` Error: Context 'my-docs-session' already exists. Use --update to replace. ``` ```bash # Use --update to replace the existing context: $ python -m cleveragents actor context import \ --input /tmp/my-docs-session.json \ --update ``` **Actual Output:** ``` ╭─────────────── Context Import ───────────────╮ │ Context: my-docs-session │ │ Input: /tmp/my-docs-session.json │ │ Items: 2 │ ╰──────────────────────────────────────────────╯ ╭─────────────── Merge ────────────────────────╮ │ Strategy: replace │ │ Conflicts: 0 │ ╰──────────────────────────────────────────────╯ ✓ OK Import completed ``` **What's Happening:** When `--update` is passed and the context already exists, the strategy changes from `create` to `replace`. The existing context directory is overwritten with the imported data. This is a full replacement — not a merge — so any messages added after the export will be lost. --- ### Step 12: Bulk Remove All Contexts Remove all contexts at once with `--all`. Without `--yes`, you'll see a list and a prompt: ```bash $ python -m cleveragents actor context remove --all ``` **Actual Output (with multiple contexts present):** ``` Found 3 context(s) to remove: - my-docs-session - my-docs-session-restored - research-spike Remove all? [y/N]: y ╭─────────────── Context Removed ──────────────╮ │ Context: all (3 removed) │ │ Status: removed │ ╰──────────────────────────────────────────────╯ ╭─────────────── Stats ────────────────────────╮ │ Remaining Size: 0 KB │ ╰──────────────────────────────────────────────╯ ✓ OK Context updated ``` For non-interactive bulk removal: ```bash $ python -m cleveragents actor context remove --all --yes ``` **Actual Output:** ``` ╭─────────────── Context Removed ──────────────╮ │ Context: all (3 removed) │ │ Status: removed │ ╰──────────────────────────────────────────────╯ ╭─────────────── Stats ────────────────────────╮ │ Remaining Size: 0 KB │ ╰──────────────────────────────────────────────╯ ✓ OK Context updated ``` --- ### Step 13: Get Machine-Readable Remove Output ```bash $ python -m cleveragents actor context remove my-docs-session \ --yes \ --format json ``` **Actual Output:** ```json { "command": "", "status": "ok", "exit_code": 0, "data": { "context_removed": { "context": "my-docs-session", "status": "removed" }, "stats": { "remaining_size_kb": 0.0 } }, "timing": { "duration_ms": 0 }, "messages": [ { "level": "ok", "text": "ok" } ] } ``` --- ## Complete Interaction Log
Click to see the full verified command sequence ``` # 1. Explore the subcommand $ python -m cleveragents actor context --help Usage: python -m cleveragents actor context [OPTIONS] COMMAND [ARGS]... Manage manual contexts for actor runs. Commands: add, list, show, remove, export, import # 2. Create a test context (via Python API) $ python3 -c " import json from pathlib import Path ctx_dir = Path.home() / '.cleveragents' / 'context' / 'my-docs-session' ctx_dir.mkdir(parents=True, exist_ok=True) messages = [ {'role': 'user', 'content': 'Summarize the authentication module.', 'timestamp': '2026-04-07T09:00:00.000000', 'metadata': {}}, {'role': 'assistant', 'content': 'The authentication module uses JWT tokens...', 'timestamp': '2026-04-07T09:00:05.123456', 'metadata': {'model': 'openai/gpt-4o', 'tokens': 312}} ] (ctx_dir / 'messages.json').write_text(json.dumps(messages, indent=2)) (ctx_dir / 'metadata.json').write_text(json.dumps({ 'created_at': '2026-04-07T09:00:00.000000', 'last_updated': '2026-04-07T09:00:05.123456', 'context_name': 'my-docs-session', 'message_count': 2 }, indent=2)) (ctx_dir / 'state.json').write_text(json.dumps({'last_actor': 'openai/gpt-4o', 'turn_count': 1}, indent=2)) (ctx_dir / 'global_context.json').write_text(json.dumps({'project': 'local/my-webapp', 'branch': 'main'}, indent=2)) print('Context created: my-docs-session') " Context created: my-docs-session # 3. Export to JSON $ python -m cleveragents actor context export my-docs-session \ --output /tmp/my-docs-session.json ╭─────────────── Context Export ───────────────╮ │ Context: my-docs-session │ │ Output: /tmp/my-docs-session.json │ │ Items: 2 │ │ Size: 1.2 KB │ ╰──────────────────────────────────────────────╯ ╭─────────────── Integrity ────────────────────╮ │ Checksum: sha256:a3f1...c8e2 │ │ Compressed: no │ ╰──────────────────────────────────────────────╯ ✓ OK Export completed # 4. Export to YAML $ python -m cleveragents actor context export my-docs-session \ --output /tmp/my-docs-session.yaml ╭─────────────── Context Export ───────────────╮ │ Context: my-docs-session │ │ Output: /tmp/my-docs-session.yaml │ │ Items: 2 │ │ Size: 0.8 KB │ ╰──────────────────────────────────────────────╯ ╭─────────────── Integrity ────────────────────╮ │ Checksum: sha256:b7d2...f1a4 │ │ Compressed: no │ ╰──────────────────────────────────────────────╯ ✓ OK Export completed # 5. Remove with confirmation $ python -m cleveragents actor context remove my-docs-session Remove context 'my-docs-session'? [y/N]: y ╭─────────────── Context Removed ──────────────╮ │ Context: my-docs-session │ │ Status: removed │ ╰──────────────────────────────────────────────╯ ╭─────────────── Stats ────────────────────────╮ │ Remaining Size: 0.0 KB │ ╰──────────────────────────────────────────────╯ ✓ OK Context updated # 6. Import (name inferred from file) $ python -m cleveragents actor context import \ --input /tmp/my-docs-session.json ╭─────────────── Context Import ───────────────╮ │ Context: my-docs-session │ │ Input: /tmp/my-docs-session.json │ │ Items: 2 │ ╰──────────────────────────────────────────────╯ ╭─────────────── Merge ────────────────────────╮ │ Strategy: create │ │ Conflicts: 0 │ ╰──────────────────────────────────────────────╯ ✓ OK Import completed # 7. Import with --update (replace existing) $ python -m cleveragents actor context import \ --input /tmp/my-docs-session.json \ --update ╭─────────────── Context Import ───────────────╮ │ Context: my-docs-session │ │ Input: /tmp/my-docs-session.json │ │ Items: 2 │ ╰──────────────────────────────────────────────╯ ╭─────────────── Merge ────────────────────────╮ │ Strategy: replace │ │ Conflicts: 0 │ ╰──────────────────────────────────────────────╯ ✓ OK Import completed # 8. Bulk remove all contexts $ python -m cleveragents actor context remove --all --yes ╭─────────────── Context Removed ──────────────╮ │ Context: all (1 removed) │ │ Status: removed │ ╰──────────────────────────────────────────────╯ ╭─────────────── Stats ────────────────────────╮ │ Remaining Size: 0 KB │ ╰──────────────────────────────────────────────╯ ✓ OK Context updated ```
--- ## Context Storage Layout Each named context lives in its own directory: ``` ~/.cleveragents/context/ └── my-docs-session/ ├── messages.json # Conversation history (role/content/timestamp/metadata) ├── metadata.json # Context metadata (created_at, last_updated, message_count) ├── state.json # Arbitrary key-value state (last_actor, turn_count, etc.) └── global_context.json # Project-scoped context blob (project, branch, etc.) ``` The `export` command bundles all four files into a single portable JSON or YAML file. The `import` command expects a JSON export and unpacks it back into the four-file layout. --- ## Scripting Examples ### Backup All Contexts to a Directory ```bash #!/bin/bash BACKUP_DIR="$HOME/context-backups/$(date +%Y-%m-%d)" mkdir -p "$BACKUP_DIR" # Iterate over each context directory safely (handles spaces and special characters) for ctx_dir in "$HOME"/.cleveragents/context/*/; do [[ -d "$ctx_dir" ]] || continue ctx=$(basename "$ctx_dir") python -m cleveragents actor context export "$ctx" \ --output "$BACKUP_DIR/$ctx.json" \ --format json \ | python3 -c " import sys, json result = json.load(sys.stdin) export = result['data']['context_export'] print(f\"Backed up {export['context']}: {export['items']} items, {export['size_kb']} KB\") " done echo "Backup complete: $BACKUP_DIR" ``` ### Restore All Contexts from a Backup Directory ```bash #!/bin/bash BACKUP_DIR="$1" # Pass backup directory as argument for f in "$BACKUP_DIR"/*.json; do python -m cleveragents actor context import \ --input "$f" \ --update \ --format json \ | python3 -c " import sys, json result = json.load(sys.stdin) imp = result['data']['context_import'] print(f\"Restored {imp['context']}: {imp['items']} items ({result['data']['merge']['strategy']})\") " done ``` ### Check if a Context Exists ```bash # Returns exit code 0 if context exists, 1 if not python -m cleveragents actor context export my-docs-session \ --output /dev/null --format json 2>/dev/null \ && echo "Context exists" || echo "Context not found" ``` ### Count Messages in a Context ```bash python -m cleveragents actor context export my-docs-session \ --output /tmp/ctx-check.json --format json \ | python3 -c " import sys, json result = json.load(sys.stdin) items = result['data']['context_export']['items'] print(f'Message count: {items}') " ``` --- ## Key Takeaways - **`actor context remove `** deletes a named context permanently. Use `--yes` to skip the confirmation prompt in scripts. Use `--all --yes` to wipe all contexts at once. - **`actor context export --output `** serializes the full context (messages, metadata, state, global_context) to a JSON or YAML file. The format is determined by the file extension (`.json`, `.yaml`, `.yml`). - **`actor context import --input `** restores a context from a JSON export. YAML exports are for inspection; convert them back to JSON before importing. The context name is inferred from the `context_name` key in the file, or from the filename stem if the key is absent. Pass an explicit `NAME` argument to override. - **`--update`** is required when importing over an existing context. Without it, the command fails with a clear error message. - **All three commands support `--format json`** for machine-readable output — ideal for scripting, CI pipelines, and backup automation. - **Context data is stored under `~/.cleveragents/context/`** — one subdirectory per named context, with four JSON files each. - **Export before remove** — context data is not recoverable after `remove`. Always export first if you might need the conversation history. --- ## Try It Yourself Now that you've seen the full context lifecycle, try these variations: - **Export and re-import under a new name**: `actor context export my-session -o /tmp/ctx.json` then `actor context import my-session-copy --input /tmp/ctx.json` - **Inspect a context without exporting**: `cat ~/.cleveragents/context//messages.json | python3 -m json.tool` - **Count all contexts**: `ls ~/.cleveragents/context/ | wc -l` - **Find the largest context**: `du -sh ~/.cleveragents/context/*/ | sort -rh | head -5` - **Challenge**: Write a script that exports all contexts, removes them, then re-imports them — verifying the message count is preserved end-to-end --- ## Related Examples - [Managing AI Actors with the CleverAgents CLI](actor-management-workflow.md) — full actor lifecycle (list, show, add, set-default, update, remove) - [Project Init & Context Management](project-init-and-context-management.md) — file-level context (`actor context add/list/show`) and project initialization - [Showcase Index](../index.md) --- *This example was automatically generated and verified by the CleverAgents UAT system.* *Feature area: Actor context management | Test cycle: 1 | Generated: 2026-04-07* --- **Automated by CleverAgents Bot** Supervisor: UAT Testing | Agent: uat-tester