Skip to main content

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​

FieldsMeaning
session_id, parent_session, agent_idSession and subagent identity.
run_id, agentRelay run and agent identity when attached to the record.
user_name, host, harnessUser from the key, machine and client (claude or codex).
seq, block_idx, _timestampTranscript order, block position and timestamp.
role, block_typeSpeaker and content type: text, thinking, tool use, tool result or result.
tool_name, tool_use_id, command, pathsTool identity, shell command and paths reported by edit tools.
body, body_len, truncatedText, its original length and whether it was cut.
is_error, is_summaryError and summary flags.
cwd, git_branchWorking directory and Git branch.
input_tokens, output_tokens, cost_usdUsage 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​

ItemLimit or default
Records per upload500; more returns status 400.
Upload body4 mebibytes (MiB); more returns status 413.
Stored text body64 kibibytes (KiB).
Search resultsDefault 10, maximum 25, over at most 500 candidate rows.
Search snippet300 characters around a hit.
fetch_recordsAt most 50 rows per tool call; each body is cut at 4,000 characters. body_len gives its full stored length.
next_actionsDefault 3 subsequent tool calls, maximum 8.
session_indexDefault 10 sessions, maximum 40.
Sessions listingDefault 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​

CodeStatusWhat to do
MCP_MISSING_KEY401Send your key in the Authorization Bearer header.
MCP_INVALID_KEY401Check that you supplied the complete MCP key, or generate a new one in Connect.
MCP_KEY_EXPIRED401Generate a new key in Connect and update your connection.
MCP_KEY_STALE401Your permissions changed. Fetch a new key in Connect.
MCP_KEY_REVOKED401Ask your administrator to check your workspace membership and restore access if appropriate.
MCP_WORKSPACE_MISMATCH403Use the URL and key from the same workspace.
MCP_FORBIDDEN_ROLE403Visitors cannot use MCP keys. Ask your administrator for an appropriate role.
MCP_AUTH_UNAVAILABLE503Authentication is temporarily unavailable. Retry the request.
MCP_WRITES_DISABLED403Ask 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-Token and Cookie.
  • Flags such as --token, --api-key and --password.
  • Assignments to names ending in SECRET, TOKEN, PASSWORD or KEY, 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.