What is uploaded and limits
CtrlB Recall stores the transcript exposed by your coding agent's harness. The Claude Code plugin and Codex hooks upload new transcript lines at the end of each turn, before compaction, when subagents start or stop, and at session end. A tool call becomes searchable after the upload for its turn.
What a row carries
| Fields | Meaning |
|---|---|
session_id, parent_session, agent_id | Session and subagent identity. |
run_id, agent | Relay run and agent identity when attached to the record. |
user_name, host, harness | User from the key, machine and client (claude or codex). |
seq, block_idx, _timestamp | Transcript order, block position and timestamp. |
role, block_type | Speaker and content type: text, thinking, tool use, tool result or result. |
tool_name, tool_use_id, command, paths | Tool identity, shell command and paths reported by edit tools. |
body, body_len, truncated | Text, its original length and whether it was cut. |
is_error, is_summary | Error and summary flags. |
cwd, git_branch | Working directory and Git branch. |
input_tokens, output_tokens, cost_usd | Usage fields when the harness supplies them. |
Codex records user and assistant messages, reasoning summaries, tool calls and tool results from rollout files. Developer messages and encrypted reasoning are excluded. Token usage records become result rows. Codex rows carry no cost.
Upload and read sizes
| Item | Limit or default |
|---|---|
| Records per upload | 500; more returns status 400. |
| Upload body | 4 mebibytes (MiB); more returns status 413. |
| Stored text body | 64 kibibytes (KiB). |
| Search results | Default 10, maximum 25, over at most 500 candidate rows. |
| Search snippet | 300 characters around a hit. |
fetch_records | At most 50 rows per tool call; each body is cut at 4,000 characters. body_len gives its full stored length. |
next_actions | Default 3 subsequent tool calls, maximum 8. |
session_index | Default 10 sessions, maximum 40. |
| Sessions listing | Default 50 sessions, maximum 100 per page, over at most 366 days per listing. |
Retention and access
Hosted session records are ordinary logs dataset rows, kept according to your workspace's dataset retention. The 366-day listing window is a query limit, not a promise of retention. Local records stay in ctrlb.db until you remove the local data.
A Model Context Protocol (MCP) key acts as the user who generated it. Reads need relay.read and dataset access. Uploads need relay.write and write access to the sessions dataset. Searches show that user's rows unless the role has relay.read_all. By default, Viewers read, Editors read and write, and Admins also read across users and manage settings. Visitors cannot use these keys.
CtrlB fills user_name from the key. A record naming another user refuses the whole upload with status 403. A grant on the sessions dataset covers its paired Relay dataset. Writes use the configured sessions dataset; reads may name another dataset you can access.
Keys are accepted in the Authorization header while the workspace's MCP server is on. To generate or replace a key, go to the sidebar and, under AI operations, choose Connect. Relay limits covers claim visibility and settings permissions.
Hosted write tools are on by default. When they are off, every HTTP write made with an MCP key, including session uploads, is refused with status 403 and code MCP_WRITES_DISABLED. Ask your CtrlB administrator to turn them on.
Key error codes
| Code | Status | What to do |
|---|---|---|
MCP_MISSING_KEY | 401 | Send your key in the Authorization Bearer header. |
MCP_INVALID_KEY | 401 | Check that you supplied the complete MCP key, or generate a new one in Connect. |
MCP_KEY_EXPIRED | 401 | Generate a new key in Connect and update your connection. |
MCP_KEY_STALE | 401 | Your permissions changed. Fetch a new key in Connect. |
MCP_KEY_REVOKED | 401 | Ask your administrator to check your workspace membership and restore access if appropriate. |
MCP_WORKSPACE_MISMATCH | 403 | Use the URL and key from the same workspace. |
MCP_FORBIDDEN_ROLE | 403 | Visitors cannot use MCP keys. Ask your administrator for an appropriate role. |
MCP_AUTH_UNAVAILABLE | 503 | Authentication is temporarily unavailable. Retry the request. |
MCP_WRITES_DISABLED | 403 | Ask your CtrlB administrator to turn on write tools for the deployment. |
Secret replacement
Before upload, the plugin and Codex hooks replace text that looks like a secret with a fixed placeholder. Patterns cover:
- Private keys, cloud keys, API keys and tokens.
- JWTs, Authorization and Bearer values.
- Credential headers such as
X-API-Key,X-Auth-TokenandCookie. - Flags such as
--token,--api-keyand--password. - Assignments to names ending in
SECRET,TOKEN,PASSWORDorKEY, and passwords in URLs.
Example of text in a stored row, using an invented value that is not a real key:
Before upload: DEMO_API_KEY=invented-not-a-real-key
Stored row: DEMO_API_KEY=[REDACTED]
Pattern matching cannot catch every secret. Do not paste real credentials into a session. Records you upload yourself over HTTP and the harness's own OpenTelemetry (OTEL) export do not pass through the package's replacement step.
OpenTelemetry boundary
OTEL export uses the harness's event format. It does not create Recall rows, thinking blocks, keyed edit paths, run and agent columns, past-session uploads, Relay tools or edit checks. Recall tools and the app's transcript drawer do not read those events. Prompt and response text is exported as written. See Connect over HTTP or OpenTelemetry.
Search and local limits
The project instruction block and session-start rule ask agents to search; they do not force them. Codex must trust new or changed hooks through /hooks before they run. A project block only reaches sessions that read that project's file.
Local mode is for one machine and one user, with no team search or continuous hosted sync. Run Recall on your machine explains installation and migration.