From c91c85532a74ad1f1ee8674e4d6eba644f8300ed Mon Sep 17 00:00:00 2001 From: Peter Steinberger Date: Thu, 15 Jan 2026 01:09:21 +0000 Subject: [PATCH] docs: add context concept page --- docs/concepts/context.md | 152 +++++++++++++++++++++++++++++++++ docs/concepts/session.md | 1 + docs/concepts/system-prompt.md | 2 + docs/docs.json | 9 ++ docs/token-use.md | 2 + 5 files changed, 166 insertions(+) create mode 100644 docs/concepts/context.md diff --git a/docs/concepts/context.md b/docs/concepts/context.md new file mode 100644 index 000000000..c9cb6c143 --- /dev/null +++ b/docs/concepts/context.md @@ -0,0 +1,152 @@ +--- +summary: "Context: what the model sees, how it is built, and how to inspect it" +read_when: + - You want to understand what “context” means in Clawdbot + - You are debugging why the model “knows” something (or forgot it) + - You want to reduce context overhead (/context, /status, /compact) +--- +# Context + +“Context” is **everything Clawdbot sends to the model for a run**. It is bounded by the model’s **context window** (token limit). + +Beginner mental model: +- **System prompt** (Clawdbot-built): rules, tools, skills list, time/runtime, and injected workspace files. +- **Conversation history**: your messages + the assistant’s messages for this session. +- **Tool calls/results + attachments**: command output, file reads, images/audio, etc. + +Context is *not the same thing* as “memory”: memory can be stored on disk and reloaded later; context is what’s inside the model’s current window. + +## Quick start (inspect context) + +- `/status` → quick “how full is my window?” view + session settings. +- `/context list` → what’s injected + rough sizes (per file + totals). +- `/context detail` → deeper breakdown: per-file, per-tool schema sizes, per-skill entry sizes, and system prompt size. +- `/cost on` → append per-reply usage line to normal replies. +- `/compact` → summarize older history into a compact entry to free window space. + +See also: [Slash commands](/tools/slash-commands), [Token use & costs](/token-use), [Compaction](/concepts/compaction). + +## Example output + +Values vary by model, provider, tool policy, and what’s in your workspace. + +### `/context list` + +``` +🧠 Context breakdown +Workspace: +Bootstrap max/file: 20,000 chars +Sandbox: mode=non-main sandboxed=false +System prompt (run): 38,412 chars (~9,603 tok) (Project Context 23,901 chars (~5,976 tok)) + +Injected workspace files: +- AGENTS.md: OK | raw 1,742 chars (~436 tok) | injected 1,742 chars (~436 tok) +- SOUL.md: OK | raw 912 chars (~228 tok) | injected 912 chars (~228 tok) +- TOOLS.md: TRUNCATED | raw 54,210 chars (~13,553 tok) | injected 20,962 chars (~5,241 tok) +- IDENTITY.md: OK | raw 211 chars (~53 tok) | injected 211 chars (~53 tok) +- USER.md: OK | raw 388 chars (~97 tok) | injected 388 chars (~97 tok) +- HEARTBEAT.md: MISSING | raw 0 | injected 0 +- BOOTSTRAP.md: OK | raw 0 chars (~0 tok) | injected 0 chars (~0 tok) + +Skills list (system prompt text): 2,184 chars (~546 tok) (12 skills) +Tools: read, edit, write, exec, process, browser, message, sessions_send, … +Tool list (system prompt text): 1,032 chars (~258 tok) +Tool schemas (JSON): 31,988 chars (~7,997 tok) (counts toward context; not shown as text) +Tools: (same as above) + +Session tokens (cached): 14,250 total / ctx=32,000 +``` + +### `/context detail` + +``` +🧠 Context breakdown (detailed) +… +Top skills (prompt entry size): +- frontend-design: 412 chars (~103 tok) +- oracle: 401 chars (~101 tok) +… (+10 more skills) + +Top tools (schema size): +- browser: 9,812 chars (~2,453 tok) +- exec: 6,240 chars (~1,560 tok) +… (+N more tools) +``` + +## What counts toward the context window + +Everything the model receives counts, including: +- System prompt (all sections). +- Conversation history. +- Tool calls + tool results. +- Attachments/transcripts (images/audio/files). +- Compaction summaries and pruning artifacts. +- Provider “wrappers” or hidden headers (not visible, still counted). + +## How Clawdbot builds the system prompt + +The system prompt is **Clawdbot-owned** and rebuilt each run. It includes: +- Tool list + short descriptions. +- Skills list (metadata only; see below). +- Workspace location. +- Time (UTC + converted user time if configured). +- Runtime metadata (host/OS/model/thinking). +- Injected workspace bootstrap files under **Project Context**. + +Full breakdown: [System Prompt](/concepts/system-prompt). + +## Injected workspace files (Project Context) + +By default, Clawdbot injects a fixed set of workspace files (if present): +- `AGENTS.md` +- `SOUL.md` +- `TOOLS.md` +- `IDENTITY.md` +- `USER.md` +- `HEARTBEAT.md` +- `BOOTSTRAP.md` (first-run only) + +Large files are truncated per-file using `agents.defaults.bootstrapMaxChars` (default `20000` chars). `/context` shows **raw vs injected** sizes and whether truncation happened. + +## Skills: what’s injected vs loaded on-demand + +The system prompt includes a compact **skills list** (name + description + location). This list has real overhead. + +Skill instructions are *not* included by default. The model is expected to `read` the skill’s `SKILL.md` **only when needed**. + +## Tools: there are two costs + +Tools affect context in two ways: +1) **Tool list text** in the system prompt (what you see as “Tooling”). +2) **Tool schemas** (JSON). These are sent to the model so it can call tools. They count toward context even though you don’t see them as plain text. + +`/context detail` breaks down the biggest tool schemas so you can see what dominates. + +## Commands, directives, and “inline shortcuts” + +Slash commands are handled by the Gateway. There are a few different behaviors: +- **Standalone commands**: a message that is only `/...` runs as a command. +- **Directives**: `/think`, `/verbose`, `/reasoning`, `/elevated`, `/model`, `/queue` are stripped before the model sees the message. + - Directive-only messages persist session settings. + - Inline directives in a normal message act as per-message hints. +- **Inline shortcuts** (allowlisted senders only): certain `/...` tokens inside a normal message can run immediately (example: “hey /status”), and are stripped before the model sees the remaining text. + +Details: [Slash commands](/tools/slash-commands). + +## Sessions, compaction, and pruning (what persists) + +What persists across messages depends on the mechanism: +- **Normal history** persists in the session transcript until compacted/pruned by policy. +- **Compaction** persists a summary into the transcript and keeps recent messages intact. +- **Pruning** removes old tool results from the *in-memory* prompt for a run, but does not rewrite the transcript. + +Docs: [Session](/concepts/session), [Compaction](/concepts/compaction), [Session pruning](/concepts/session-pruning). + +## What `/context` actually reports + +`/context` prefers the latest **run-built** system prompt report when available: +- `System prompt (run)` = captured from the last embedded (tool-capable) run and persisted in the session store. +- `System prompt (estimate)` = computed on the fly when no run report exists (or when running via a CLI backend that doesn’t generate the report). + +Either way, it reports sizes and top contributors; it does **not** dump the full system prompt or tool schemas. + diff --git a/docs/concepts/session.md b/docs/concepts/session.md index 27880e0df..e1b5fc348 100644 --- a/docs/concepts/session.md +++ b/docs/concepts/session.md @@ -90,6 +90,7 @@ Send these as standalone messages so they register. - `pnpm clawdbot sessions --json` — dumps every entry (filter with `--active `). - `clawdbot gateway call sessions.list --params '{}'` — fetch sessions from the running gateway (use `--url`/`--token` for remote gateway access). - Send `/status` as a standalone message in chat to see whether the agent is reachable, how much of the session context is used, current thinking/verbose toggles, and when your WhatsApp web creds were last refreshed (helps spot relink needs). +- Send `/context list` or `/context detail` to see what’s in the system prompt and injected workspace files (and the biggest context contributors). - Send `/stop` as a standalone message to abort the current run. - Send `/compact` (optional instructions) as a standalone message to summarize older context and free up window space. See [/concepts/compaction](/concepts/compaction). - JSONL transcripts can be opened directly to review full turns. diff --git a/docs/concepts/system-prompt.md b/docs/concepts/system-prompt.md index 75de873c1..55952d8e6 100644 --- a/docs/concepts/system-prompt.md +++ b/docs/concepts/system-prompt.md @@ -42,6 +42,8 @@ Large files are truncated with a marker. The max per-file size is controlled by `agents.defaults.bootstrapMaxChars` (default: 20000). Missing files inject a short missing-file marker. +To inspect how much each injected file contributes (raw vs injected, truncation, plus tool schema overhead), use `/context list` or `/context detail`. See [Context](/concepts/context). + ## Time handling The Time line is compact and explicit: diff --git a/docs/docs.json b/docs/docs.json index 0cf1606da..2d2e5387d 100644 --- a/docs/docs.json +++ b/docs/docs.json @@ -45,6 +45,14 @@ "source": "/messages/", "destination": "/concepts/messages" }, + { + "source": "/context", + "destination": "/concepts/context" + }, + { + "source": "/context/", + "destination": "/concepts/context" + }, { "source": "/minimax", "destination": "/providers/minimax" @@ -765,6 +773,7 @@ "concepts/agent", "concepts/agent-loop", "concepts/system-prompt", + "concepts/context", "token-use", "concepts/oauth", "concepts/agent-workspace", diff --git a/docs/token-use.md b/docs/token-use.md index 7dbb05f23..3fe2b5c04 100644 --- a/docs/token-use.md +++ b/docs/token-use.md @@ -34,6 +34,8 @@ Everything the model receives counts toward the context limit: - Compaction summaries and pruning artifacts - Provider wrappers or safety headers (not visible, but still counted) +For a practical breakdown (per injected file, tools, skills, and system prompt size), use `/context list` or `/context detail`. See [Context](/concepts/context). + ## How to see current token usage Use these in chat: