Persistent Context Management - ChatCLI
Skip to main content
While session management (/session) saves the conversation history, context management (/context) saves the content of your working environment. It is the most powerful feature for those working on multiple projects or who frequently need to consult the same codebase. A Context is a named “snapshot” of one or more files and directories, processed and saved to disk for reuse at any time.

​
The Lifecycle of a Context

Context usage follows a simple and powerful flow:
1

Create (/context create)

You define a set of files and folders, process them with a specific mode (e.g., smart, chunked), and save the result with a name.
2

Attach (/context attach)

You “attach” one or more saved contexts to your current conversation session.
3

Use

While attached, the context content is automatically sent to the AI with all your prompts, providing deep and continuous knowledge about your project.
4

Detach (/context detach)

When you no longer need the context, you detach it to free up space in the AI prompt.

​
Context Management Commands

Here are all the available subcommands for managing your contexts.

​
create: Create a New Context

Creates and saves a new context from files and directories. Syntax:
Options: Example:

​
attach and detach: Attach and Detach from Session

These commands control which contexts are active in your current conversation.

​
Advanced Chunk Attachment

If a context was created with --mode=chunked, you can attach specific parts of it: Example:

​
--rag: Semantic Retrieval (don’t dump raw data)

The problem: injecting whole files blows the context window on any non-trivial codebase. The --rag flag fixes it: instead of the raw dump, it embeds the context’s passages and, each turn, injects only the top-K most relevant to the current question. For documentation or code/infra corpora, prefer --mode knowledge: same principle, but with no API key required (keyless BM25), an index card in the prompt and the @knowledge tool for the agent to investigate.
How it works:
1

Segmentation

Files are split into line-aware, overlapping passages (~300 tokens each) — a fine grain, distinct from the token-budget chunk. IDs are content hashes, so unchanged files skip re-embedding.
2

Embed once, cache on disk

Passages are embedded lazily and persisted per context; edited/removed passages are pruned (never serve stale text).
3

Retrieve at prompt time

The turn’s query is embedded and the top-K passages by cosine (with a relevance floor) are injected.
Requires an embedding provider (CHATCLI_EMBED_PROVIDER — voyage, openai or bedrock). Set the provider after ChatCLI was already running? /reload rebuilds and rewires it on the spot. Without one, --rag falls back transparently to whole content, with a warning.
Auto-RAG for large contexts: when an embedding provider is configured, a context of 32 KiB or more attached with no explicit flag is automatically upgraded to semantic retrieval (top-8 passages per turn) — the same default the agent-side @context tool has always used. The upgrade is announced at attach time; opt out per call with --full/-f or globally with CHATCLI_ATTACH_AUTO_RAG=off. Small contexts and no-embeddings setups keep the verbatim whole-content behavior, unchanged.
Cache-aware: the retrieved content is query-driven, so it is injected in the prompt’s volatile zone — never poisoning the cached prefix. And --rag cannot be combined with --chunk(s) (semantic vs. manual selection are contradictory).
In a synthetic measurement, the injected block dropped to 44% of the raw size while still retrieving the right passage from a synonym query — on large contexts the saving is far greater. It reuses the same vindex primitive as RAG + HyDE — provider-agnostic, OS-agnostic. The only env knob is the auto-upgrade gate CHATCLI_ATTACH_AUTO_RAG (on by default).

​
list, show, and inspect: View Contexts

These commands help you understand what is in your saved contexts.

​
Other Management Commands

Permanently deletes a context.
Combines multiple contexts into a new one, removing duplicate files.
Exports a context to a JSON file, making backup and sharing easier.
Imports a context from a JSON file.
Re-indexes a context from the paths it was built from. Every file carries a stamp (size, mtime, content hash) since the last scan: an unchanged corpus is reported as up to date and nothing is rebuilt — retrieval caches and vectors stay valid — while an edited, added or removed file triggers a rebuild in which only the passages that actually changed are re-embedded (passage ids are content hashes). A touch without an edit is not a change. Contexts created before source paths were recorded adopt the paths of the files they hold on their first refresh or watch (persisted from then on); one /context update <name> <paths> still re-records them explicitly.
Keeps a context in step with its source paths through the filesystem watcher: directories are watched recursively (noise directories such as node_modules and .git skipped, new subdirectories picked up), bursts of events settle for 1.5 s and collapse into one refresh, and the outcome is printed at the next prompt as context <name> refreshed: N changed, M added, K removed. Watches live for the session (and per tenant on the gateway) and stop at exit.
Shows global statistics about all your contexts (total count, size, etc.).
Prefix budget. The system prefix (mode card, attachments, digests, skills, tool catalog) may take half the window before it degrades, in a declared order: skill bodies fold into read-on-demand pointers, knowledge digests shrink to their compact card, whole-content attachments fold into an index card that lists the files and how to pull them (/context attach <name> --rag). When the provider can count tokens (see Cost tracking → Token counting by provider), the report also prints the provider-counted size of the live history and refreshes the learned ratio from it. The report shows the budget, its usage and what folded; nothing folds while the prefix fits. The chat prefix is also reserved from the compaction budget, and the footer ctx N% is now the projection for the next request (it may read above 100% right before an auto-compact).Answers “what is in my context right now, and what does each part cost”. Lists every section of the last assembled system prompt (mode banner, attached contexts, skills, MCP catalog, workspace memory, recall blocks, dynamic context — cached-prefix sections marked with ●), the conversation history by role with compacted summaries and @recall-recoverable segments, and the totals: system prompt, history, projected next request as a share of the model window, and the point where auto-compact fires. Token figures use the chars/token ratio learned from the provider’s real usage reports for the active model (the default 4 until the first report), so they converge with the ctx% the footer shows.
Displays a help screen specific to context commands.

​
Next Steps

You now know the most powerful automation and context management features of ChatCLI. To wrap up, let’s document the features that ensure portability and tool integration in scripts.

Non-Interactive Mode

Use ChatCLI in scripts, automations, and CI/CD pipelines.

Session Management

Save and restore complete conversation histories.