OpenClaw session search

When something was discussed in an earlier OpenClaw session, the sessions search tool finds it by the exact words used. It searches the user and assistant text in visible past sessions and returns a session key, a timestamp, a role and a short matching excerpt for each hit. The point is not the excerpt but what comes next: passing the returned session key, message id and session id together to the history tool reopens the matched context, including retained history from before a session reset. Here is how the anchored reads behave, who can see which sessions, what is redacted, how the index is maintained, and where memory search fits instead.

Reopening the matched context

• Without a message id, history returns the newest reset-relative tail; an explicit message id that remains in the current view, including a pre-reset row kept after a reset, keeps current-view behaviour and can include later post-reset turns.
• An explicit message id for a retained active-path row outside the current view opens that original closed interval and does not mix in later post-reset turns.
• Anchored reads bound the surrounding messages with a limit and cannot be combined with an offset; on SQLite transcript history a missing or off-path message returns empty history rather than the newest tail, and a session id that does not belong to the selected session key is rejected.
• The same rules apply in local embedded mode, with no Gateway running.

New user and assistant messages are indexed in the same transaction that persists them, so the index never lags live conversations; tool results, reasoning blocks, and images are excluded.

Who sees which sessions

Search uses the same configured session visibility rules as history. The default visibility of all lets unsandboxed callers search sessions across agents on the Gateway, including other users’ conversations; cross-agent access is on by default and governed by the agent-to-agent setting, which can be disabled to block ordinary cross-agent access or narrowed with an allow list of agent pairs, while a requester’s own native sub-agent and ACP child sessions stay reachable under the tree or all scopes. Set an explicit agent, tree or self scope when callers need less. Per-peer DM routing separates conversation context but does not restrict session-tool visibility. Results outside the caller’s effective scope are removed before result limits apply, sandboxed agents stay limited to the sessions they spawned when spawned-session visibility is enabled, incognito sessions are always excluded, and narrowing visibility away from all blocks ordinary cross-agent access. Excerpts are redacted before they return to the model, and results are bounded by count, excerpt length and total response size.

The index lifecycle

• OpenClaw stores a full-text index next to the transcript rows in each agent’s SQLite database; only the transcript’s active branch is searchable, and deleting a session removes its index entries in the same transaction.
• Transcripts that predate the index, such as sessions imported by the doctor command, and sessions whose active branch was rewound are reindexed by a background reconciliation that starts with the next search, so a response flagged as still indexing can be incomplete and is worth retrying once indexing finishes.
• Search uses SQLite’s Unicode word tokenizer with diacritic removal, so accented and unaccented spellings meet.

Use this tool for exact words or phrases from raw transcripts and OpenClaw memory search for durable memory files and semantic recall; OpenClaw sessions explains the keys and resets the search results point at.

Why the default is wide

The default scope exists so that one operator running several agents on one Gateway can find a conversation wherever it happened, and it assumes the callers are trusted to that degree. OpenClaw agent-to-agent messaging covers the agent-to-agent setting that governs the cross-agent half, and OpenClaw sandboxing explained the boundary that keeps a sandboxed agent inside the sessions it spawned.

On Diali

On Diali the index lives beside the transcripts on the assistant’s volume, so it survives releases with the rest of the session state, and the visibility rules apply to whoever you let talk to that assistant. Hosted OpenClaw on Diali is the assistant and Diali security describes the boundary around it.

• Exact words in, three keys out, the context reopened.
• Visibility defaults to all; narrow it when callers should see less.
• Indexed in the same transaction; reconciled in the background.