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


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.