Recall tools
CtrlB Recall provides five Model Context Protocol (MCP) tools. They read stored records and make no model call. The agent uses them in the current session, after compaction, or in a new session.
To configure a connection by hand, see Connect another MCP client.
Every tool accepts optional dataset. It defaults to the workspace's sessions dataset, agent_sessions unless changed. Hosted calls act as your key's user and show your records unless you have relay.read_all. Local mode is for one user. No run id is needed.
Answers use JSON. Timestamps are microseconds since the Unix epoch. Examples below show tool names and arguments, not shell commands.
When the agent should search
The session-start hook injects this rule into Claude Code and Codex:
- Before the first grep, file read or shell command for a question about earlier work, call
search_sessionswithoutsession_id. - Use the current
session_idonly for this session's turns before compaction. A subagent uses its parent's id to search the parent's work. - After a command fails, call
find_commandbefore changing the command. Pass a returnedsession_idandseqtonext_actionsto see what followed. - Do not say that something was never said or done until you have searched.
The installer can also put the rule in CLAUDE.md or AGENTS.md. See Connect Claude Code and Connect Codex. Codex reads its project block even before you trust hooks with /hooks. The rule requests a search; it does not force one.
search_sessions
Whole-word, case-insensitive search over messages, thinking, tool calls (with their shell commands) and tool results, across current and past sessions and their subagents. Search is a word match in hosted and local mode alike.
| Argument | Meaning |
|---|---|
term | Required. A word or phrase; it needs a word of 3 to 50 letters, digits, . or +. |
session_id | Optional. Search one session; omit it to search this user's sessions. |
tool | Only rows of this tool, for example Bash. |
order | newest (default) or oldest. |
one_per_session | Keep the first hit of each session. |
limit, offset | 10 hits by default, at most 25. offset pages. |
Answer: {total, offset, capped_at, hits: [{session_id, parent_session, seq, role, block_type, tool_name, is_error, snippet}]}. The snippet is 300 characters around the hit. Read around a hit with fetch_records.
For earlier work in general, omit session_id. Pass the current session_id only to search this session's own turns before compaction. A subagent searching its parent's work passes the parent's session_id.
{"name": "search_sessions", "arguments": {"term": "migration", "order": "newest", "limit": 5}}
find_command
Every past tool call whose command contains the text, ignoring runs of whitespace, newest first.
| Argument | Meaning |
|---|---|
command | Required. Command text containing a word of 3 to 50 letters, digits, . or +, as for term. |
limit, offset | 10 by default, at most 25. |
Answer: {total, offset, occurrences: [{session_id, seq, tool_name, command}]}. Pass a session_id and seq to next_actions to see what happened.
{"name": "find_command", "arguments": {"command": "go test ./internal"}}
next_actions
What happened after one tool call: its result, then the next k tool calls and their results, skipping text and thinking.
| Argument | Meaning |
|---|---|
session_id, seq | Required. The tool call. |
k | Tool calls to follow: 3 by default, at most 8. |
tool | Only this tool's calls, for example Bash. |
Answer: {session_id, seq, events: [{seq, kind, tool_name, is_error, text}], skipped_text_records}, where kind is call or result.
{"name": "next_actions", "arguments": {"session_id": "5f1c9a2e-7d41-4b0e-9a8c-1e2f3a4b5c01", "seq": 12, "k": 3}}
fetch_records
The rows of one session with seq_from <= seq <= seq_to, in order.
| Argument | Meaning |
|---|---|
session_id, seq_from, seq_to | Required. |
Answer: {session_id, rows: [{ts, seq, block_idx, role, block_type, tool_name, tool_use_id, command, paths, is_error, body_len, body}]}. At most 50 rows; each body is cut at 4,000 characters and body_len gives the full length.
{"name": "fetch_records", "arguments": {"session_id": "5f1c9a2e-7d41-4b0e-9a8c-1e2f3a4b5c01", "seq_from": 10, "seq_to": 20}}
session_index
Call this to get oriented in a project without choosing a search term. It returns recent sessions, newest first, computed from the stored record.
| Argument | Meaning |
|---|---|
cwd | Optional. Sessions in this working directory or beneath it. |
branch | Optional. Sessions on this Git branch. |
limit | Default 10, maximum 40. |
since | Optional. Only rows at or after this timestamp, in microseconds. |
When both cwd and branch are supplied, sessions matching either filter are included. The filters use OR.
Answer: {sessions, expand, text}. Each session line gives its id, start, duration, cost when recorded, sequence range, first user message, edited files, last command and last assistant message. Use the sequence range with fetch_records to expand it.
{"name": "session_index", "arguments": {"cwd": "/work/app", "limit": 10}}
Use fetch_records after a search or index result when you need the surrounding messages. Use next_actions when you only need tool calls and results.