recall | Brain Docs

Signature

POST/v1/recallAPI keybeta

// HTTP client
brain.recall(input: http.RecallInput): Promise<http.RecallResult>

// wire client
client.recall(request: RecallRequest): Promise<RecallAnswer>

The membership shape

recall resolves how many memories answer the cue, not a page of ranked hits:

`answerKind`	Meaning	`memories`
`None`	Brain has nothing to say — a "don't know".	empty
`Single`	Exactly one memory answers.	one entry
`Many`	Several memories answer.	several entries

The casing differs by transport: the HTTP client returns lowercase ("single" / "many" / "none"), the wire client returns capitalized ("Single" / "Many" / "None"). Match the transport you are using.

Request fields

ParameterTypeRequired

querystringrequired

The cue to recall against.

max_resultsnumberoptional

Cap on returned memories.

subjectstringoptional

Name of the subject to resolve facts about.

Build with RecallBuilder(cueText), which defaults to 10 results and mints the requestId. Key fields:

ParameterTypeRequired

cueTextstringrequired

The cue to recall against.

subjectNamestringoptional

Subject to resolve facts about (.subject(name)). Empty for none.

maxResultsnumberoptional

Cap on returned memories (.maxResults(n), default 10).

kindFilterMemoryKindWire[] | nulloptional

Restrict to certain memory kinds (.kinds([...])).

asOfRecordTimeUnixNanosbigint | nulloptional

Resolve against record-time state as of an instant (.asOf(nanos), bi-temporal).

confidenceThresholdnumberoptional

Minimum confidence (.confidence(t)).

salienceFloornumberoptional

Minimum salience (.salience(f)).

includeEdges / includeGraph / includeTextbooleanoptional

Toggle edge, graph-enrichment, and text payloads (.edges(), .graph(), .text()).

tracebooleanoptional

Opt into the per-stage read-pipeline trace on the final frame (.trace()). This is the read-side knob.

actAsActAs | nulloptional

Run as an effective identity (.actAs(namespace, agentId)); requires the canActAs grant.

Response

RecallResult:

FieldTypePresence

answer_kind"single" | "many" | "none"always

The membership verdict.

memories[]MemoryHit[]always

The supporting memories. Empty when answer_kind is "none".

Each MemoryHit carries memory_id, text, similarity_score, confidence, salience, kind, and created_at_unix_nanos.

RecallAnswer:

FieldTypePresence

answerKind"Single" | "Many" | "None"always

The membership verdict, taken from the final streamed frame.

memories[]MemoryResult[]always

Every streamed frame's memories concatenated.

MemoryResult carries memoryId, text, similarityScore, confidence, salience, kind, fusedScore, rerankScore, contributingRetrievers, timestamps, and (when requested) edges and graph.

Examples

const answer = await brain.recall({ query: "where does the user live?" });

if (answer.answer_kind === "none") {
  console.log("don't know");
} else {
  console.log(answer.memories[0].text);
}

import { RecallBuilder } from "@brain-db/sdk";

const answer = await client.recall(
  new RecallBuilder("where does the user live?").maxResults(5).build(),
);

if (answer.answerKind === "None") {
  console.log("don't know");
} else {
  console.log(answer.memories[0].text);
}

Streamed frames (wire only)

recall drains the streamed RECALL_RESP frames for you. For the raw frames — cumulative counts, estimatedRemaining, per-frame isFinal — use recallFrames, which returns RecallResponseFrame[]:

const frames = await client.recallFrames(
  new RecallBuilder("recent decisions").build(),
);
for (const f of frames) console.log(f.cumulativeCount, f.isFinal);