Session Search: Find and Reopen Past Conversations
Learn how to use sessions_search to find text in past session transcripts and reopen matching contexts. This guide covers search visibility, output structure, and index lifecycle.
Read this when
- You need to find something discussed in an earlier session
- You want to understand session search privacy or indexing
Session search
sessions_search looks through the user and assistant text in your previous sessions. Each result provides a sessionKey, timestamp, role, and a short matching excerpt. When you need the full conversation, pass the returned sessionKey to sessions_history.
Visibility and output
Search follows the same session visibility rules as sessions_history. Results that fall outside the caller's visible session tree are filtered out before result limits are applied. Sandboxed agents stay limited to sessions they created when spawned-session visibility is active.
Excerpts are redacted before being returned to the model. Results are also constrained by count, excerpt length, and total response size.
Index lifecycle
OpenClaw keeps a full-text index next to the transcript rows in each agent's SQLite database. New user and assistant messages get indexed in the same transaction that stores them, so the index always matches live conversations; tool results, reasoning blocks, and images are left out. Only the active branch of the transcript is searchable.
Transcripts that existed before the index (for instance, sessions imported by openclaw doctor) and sessions whose active branch was rewound are reindexed by a background reconciliation that begins with the next search. A response with indexing: true might therefore be incomplete; retry after indexing finishes. Deleting a session removes its index entries in the same transaction.
Search currently uses SQLite's Unicode word tokenizer with diacritic removal. Trigram tokenization for CJK substring matching is planned as a future improvement.
Session search vs. memory search
Use sessions_search for exact words or phrases from raw session transcripts. Use memory_search for durable memory files and semantic recall. The experimental session-memory corpus is the semantic counterpart to this exact transcript search.