> ## 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.

# Context

> Context management for agent conversations

The `context` command manages conversation context for AI agents.

## Usage

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
praisonai context [OPTIONS] COMMAND [ARGS]...
```

## Commands

| Command   | Options                                    | Description                                          | Exit code                                    |
| --------- | ------------------------------------------ | ---------------------------------------------------- | -------------------------------------------- |
| `show`    | `--verbose`                                | Show current context                                 | `0`                                          |
| `add`     | —                                          | Add context from file or text                        | `0`                                          |
| `clear`   | —                                          | Clear current context                                | `0`                                          |
| `list`    | —                                          | List context sources                                 | `0`                                          |
| `stats`   | `--agent`, `--json`                        | Show token usage / cache statistics                  | `0`                                          |
| `compact` | `--agent <id>`, `--threshold`, `--dry-run` | Compact per-agent history in the process-local store | `0` on work done, `1` when empty or no match |
| `export`  | `OUTPUT`, `--agent`, `--format`            | Serialise the store to a file                        | `0` when written, `1` on a fully-empty store |

<Warning>
  `compact` and `export` operate on the **process-local** `get_global_store()`. That store is empty unless *this same process* populated it, so an ordinary `praisonai context compact` run over a store an agent run filled in another process will find nothing. See [Why is my store empty?](#why-is-my-store-empty) below.
</Warning>

## Examples

### Show current context

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
praisonai context show
```

### Add file to context

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
praisonai context add myfile.py
```

### Clear context

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
praisonai context clear
```

### Compact the store

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
praisonai context compact                 # compact every agent's history
praisonai context compact --agent agent-1 # compact one agent
praisonai context compact --dry-run       # show what would be compacted
```

`compact` cleans **per-agent** history only. It prints `Compaction complete (N agent(s)).` and exits `0` when work was done.

### Export the store

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
praisonai context export context.json           # snapshot to JSON
praisonai context export report.txt --format txt # human-readable summary
```

## Empty store

The CLI is explicit about empty-state situations instead of reporting false success:

| Situation                 | Command             | Result                                                                                      |
| ------------------------- | ------------------- | ------------------------------------------------------------------------------------------- |
| Fully empty store         | `compact`           | Exits `1`: "The context store is empty in this process."                                    |
| Shared-context-only store | `compact`           | Exits `1` — compaction cleans per-agent history only; shared context has nothing to compact |
| `--agent` matches nothing | `compact --agent X` | Exits `1` with a "no agent matching …" message                                              |
| Work actually done        | `compact`           | Prints `Compaction complete (N agent(s)).`, exits `0`                                       |
| Fully empty store         | `export`            | Exits `1`, writes no file                                                                   |
| Shared-context-only store | `export`            | Exits `0` — the snapshot serialises shared context                                          |

## Why is my store empty?

`get_global_store()` is an **in-memory singleton scoped to the current process**. The agent runtime does not write to it automatically — it only holds what a caller populated *in this process* via the [context API](/docs/features/context-api#populate-the-store). A separate CLI process cannot see a store an agent run filled elsewhere; move it across processes with `snapshot()` / `restore()`. See [Context Management API → Scope](/docs/features/context-api#scope-process-local-in-memory-opt-in).

<Note>
  This CLI `context compact` is **not** the runtime `ContextCompactor` (the `/context compact` slash command / `ExecutionConfig(context_compaction=True)`). The CLI operates on the process-local `get_global_store()`; the runtime compactor trims a live agent's `chat_history`. See [Context Compaction](/docs/features/context-compaction).
</Note>

## See Also

* [Context Management API](/docs/features/context-api) - Store scope, population, and snapshot/restore
* [Fast Context](/docs/cli/fast-context) - Fast context retrieval
* [Knowledge](/docs/cli/knowledge) - Knowledge base management