crystal_recall combines semantic and lexical retrieval. Identifier shortcuts and retrieval with reduced capabilities can avoid vector search; a vector call is not guaranteed on every request. Query named reference corpora with KB query.
When to use
Use recall when you need facts, lessons, or decisions relevant to a question. Start with the question you need answered, then narrow by store, category, or tags.
Modes prioritize stores and categories; use explicit filters when you need exclusions. Identifier shortcuts use a default maximum of three decisive matches before falling through to broader retrieval. This is separate from
limit.
Response
RawPOST /api/mcp/recall returns memories, assetContexts, messageMatches, degraded, retrieval, and diagnostics, with optional degradation and promotionCandidates. Memory results use memoryId and ranking metadata. Scores are ranking signals, not calibrated confidence or pure cosine similarity.
MCP recall bounds memory content to 600 characters and flags cut text with truncated. Use get memory to read the full resolved recall text. Message excerpts are bounded to 200 characters and asset excerpts to 300 on the hosted surface. Read the returned diagnostics instead of assuming every retrieval stage ran.
retrieval.messageMatchesAvailable is a lower bound capped at messageLimit + 1, not a total transcript count. retrieval.messageScan describes scan coverage. A bounded empty result cannot establish that no matching conversation exists; use transcript search for exact wording and time windows.
Unscoped reads still enforce visibility. agentPool controls relevance, not security. Cite returned sources when explaining a past decision; citation formatting is not mechanically enforced by the API.
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 a procedure
Request:Require decision records
Request:Include archived guidance
Request:Recall modes explained
Modes change ranking preferences. They do not exclude other categories; usecategories or stores for that.
Use preflight for action-oriented checks. Supply
limit explicitly when the result count matters across presets and transports.
Scope and recent-message exclusion
Pass the same conversation scope used when saving the information. AsessionKey supplies context; add scopeToSession: true to restrict durable recall to that session. Use projectId or repoSlug for project context. Removing a channel does not grant access to every private conversation.
agentPool is a relevance setting. If the service administrator has not configured an agent recall policy, every pool uses the account pool. It is not an access-control boundary.
Echo suppression means not returning the message you just sent. Pass the current turnId to exclude its recent captured user message. excludeRecentMessagesMs widens the time window; it does not erase messages. Use messageLimit: 0 when you only need durable memories.
The stdio API-key path forwards projectId, repoSlug, messageLimit, turnId, and excludeRecentMessagesMs to the HTTP backend. The stdio JWT path validates and ignores these controls and does not return messageMatches or retrieval.
Confidence and scoring
Storedconfidence expresses certainty recorded with the memory. Ranking combines signals such as text matches, identifiers, strength, freshness, and vector similarity when available. A ranking score is not a probability that a claim is true. Read the source and its age before relying on it.
Specific identifiers can find decisive matches without embedding the query. Other requests combine bounded lexical and vector candidates. Durable-memory lexical query analysis uses Latin letters and digits. Message scoring also recognizes Unicode words, but treats non-Latin particles and stop words as informative. There are no per-script stop-word lists, so common words can contribute to transcript matches. Do not assume equal keyword behavior for every writing system.
Errors and common mistakes
An empty result is not proof that nothing was saved. Check your scope and filters, inspect retrieval diagnostics, and try transcript search for exact wording. A successful response withdegraded: true means some retrieval work was reduced or unavailable; inspect the accompanying details.
Use a nonempty query and an integer limit from 1 to 20. Do not pass threshold as a supported MCP parameter. If content is truncated, read it with get memory. For authentication and throttling failures, see API errors.