crystal_search_messages performs lexical transcript search without embedding the query. Use recall for durable context and recent for recency.
When to use
Use lexical search when you remember a word or phrase from a conversation. Use recall for related durable knowledge, recent to read the latest messages without a query, or why did we to look for recorded reasons.
Use explicit UTC timestamps when you need an unambiguous date window.
Responses by surface
HTTP pagination contains
limit, offset, returned, hasMore, and nextOffset. Follow nextOffset while hasMore is true, within the offset bound. A scoped full page can report more until a subsequent short page confirms the end. Use HTTP or stdio when you need pagination metadata; the hosted response cannot prove completeness.
If retrieval degrades, HTTP can report that keyword search was skipped and recent messages were searched instead. Bounded candidate scans and visibility can also limit results.
Scope and validation
Omittingchannel and sessionKey applies bounded unscoped visibility, not unrestricted access to private transcripts. Channels partition one account; separate accounts provide the security boundary.
MCP schemas validate numeric limits and field types. Raw HTTP clamps numeric limits and accepts additional time aliases. Do not assume the same malformed input behaves identically across transports.
Raw messages remain until you delete them on every tier. Expired TTL stamps do not currently remove messages from search.
Examples
Examples use placeholder IDs. Replace them with IDs returned by your account. MCP examples show the JSON tool arguments and the JSON inside the tool result, not the outer MCP envelope.Find wording
Request:score is the lexical match score; relevance is the normalized ranking signal. When a result matches subject labels, it also includes subjects, for example "subjects": ["backup"]. Scores are not confidence percentages.
Search one session in a time window
Request:Scope and time windows
Pass a channel to target its conversation scope, and asessionKey for a specific session. Search each intended scope explicitly when investigating multiple conversations; omitting scope is not an unrestricted cross-conversation search.
Use Date.now() - 7 * 24 * 60 * 60 * 1000 for a rolling seven-day lower bound in JavaScript. Milliseconds are required, not Unix seconds. For calendar windows use ISO timestamps with a timezone. Keep the same query, scope, and window while paging.
How results are found
Search uses bounded text-index candidates and can fall back to recent-message candidates. It does not embed the query. Results preserve transcript wording, subject to redaction and transport excerpt limits. Readturns on raw HTTP when paired conversation context helps.