Skip to main content

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.

The session-start hook injects this rule into Claude Code and Codex:

  1. Before the first grep, file read or shell command for a question about earlier work, call search_sessions without session_id.
  2. Use the current session_id only for this session's turns before compaction. A subagent uses its parent's id to search the parent's work.
  3. After a command fails, call find_command before changing the command. Pass a returned session_id and seq to next_actions to see what followed.
  4. 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.

ArgumentMeaning
termRequired. A word or phrase; it needs a word of 3 to 50 letters, digits, . or +.
session_idOptional. Search one session; omit it to search this user's sessions.
toolOnly rows of this tool, for example Bash.
ordernewest (default) or oldest.
one_per_sessionKeep the first hit of each session.
limit, offset10 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.

ArgumentMeaning
commandRequired. Command text containing a word of 3 to 50 letters, digits, . or +, as for term.
limit, offset10 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.

ArgumentMeaning
session_id, seqRequired. The tool call.
kTool calls to follow: 3 by default, at most 8.
toolOnly 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.

ArgumentMeaning
session_id, seq_from, seq_toRequired.

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.

ArgumentMeaning
cwdOptional. Sessions in this working directory or beneath it.
branchOptional. Sessions on this Git branch.
limitDefault 10, maximum 40.
sinceOptional. 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.