memory.recall

Description

Hybrid semantic + lexical search over the principal's entire memory surface. Returns ranked results with metadata; episode summaries are decrypted into `content` when the bearer has the required trust level. This is the only tool with real retrieval wiring today — the rest are honest scaffolding.

Input schema

Output shape

{
  results: Array<{
    id: string;
    source: "episode" | "conversation_turn" | "kg_entity" | "rule";
    score: number;
    metadata: Record<string, unknown>;
    occurredAt?: string;
    content?: string;
  }>;
}

Example call

JSON-RPC tools/call request body (omit the JSON-RPC envelope when using an SDK; the SDK adds it for you):

{
  "name": "memory.recall",
  "arguments": {
    "query": "what is sarah's new role at acme?",
    "topK": 5
  }
}

Example response

Tool results are always wrapped as content[0].text with a stringified JSON body. The shape below is what you get back from JSON.parse(result.content[0].text):

{
  "results": [
    {
      "id": "ep_01HXR4N9TZ5W2QF6KMVDX8Y3GP",
      "source": "episode",
      "score": 0.92,
      "metadata": { "source_id": "manual" },
      "occurredAt": "2026-05-27T14:31:00Z",
      "content": "Sarah moved to a new role at Acme; she'll lead the API team."
    }
  ]
}

Errors this tool can return

See the full error catalog for resolution steps on each code, plus the standard transport-layer responses (401, 429).