Recall

The answer shape

A recall answer carries an answer_kind and a memories list. The kind is the shape of the answer, not a score:

OptionTypeDefault / Env

Singleone memory answers the cue

memories has exactly one entry.

Manyseveral memories answer the cue

memories has two or more entries.

Nonenothing stored answers the cue

memories is empty. Brain says "I don't know" rather than inventing one.

On the wire client, AnswerKind.SINGLE / MANY / NONE are the string constants ("Single" / "Many" / "None"); the HTTP RecallResult exposes the same values on answer_kind.

HTTP

POST/v1/recallBearerstable

client.recall(
    query: str,
    max_results: int | None = None,
    subject: str | None = None,
) -> RecallResult

ParameterTypeRequired

querystrrequired

The cue text to retrieve against.

max_resultsint | Noneoptional

Cap on how many memories the answer carries. Omitted when None.

subjectstr | Noneoptional

Names the entity a fact lookup is about, so recall resolves the subject before matching the cue. Omitted when None.

from brain_db_sdk import BrainHttpClient

client = BrainHttpClient("sk-...", base_url="https://api.arc-labs.ai")
answer = client.recall("Where does Ada live?", max_results=5, subject="Ada")

if answer.answer_kind == "None":
    print("no memory answers this cue")
else:
    for hit in answer.memories:
        print(hit.text, hit.similarity_score, hit.confidence)

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

Wire

The wire client takes a RecallRequest. Build it with RecallBuilder:

token / mTLSstable

client.recall(request: RecallRequest) -> RecallAnswer

from brain_db_sdk import BrainClient, Auth, RecallBuilder, AnswerKind

with BrainClient.connect("127.0.0.1", 9090, Auth.token(b"my-token")) as client:
    req = RecallBuilder("Where does Ada live?").subject("Ada").limit(5).build()
    answer = client.recall(req)

    if answer.is_empty:
        print("None")
    else:
        for m in answer.memories:
            print(m.text, m.similarity_score, m.fused_score, m.rerank_score)

RecallAnswer has an is_empty property — true when answer_kind is None or memories is empty.

RecallBuilder knobs

OptionTypeDefault / Env

.subject(name)str

Name the entity the fact lookup is about.

.limit(max_results)int

Cap the number of memories returned (default 10).

.as_of(unix_nanos)int | None

Query the graph as it stood at a record time (bi-temporal travel).

.confidence(threshold)float

Drop memories whose salience falls below this floor.

.contexts(ids)list[int]

Restrict recall to these context ids.

.kinds(discriminants)list[int]

Restrict recall to these memory kinds.

.salience(floor)float

Drop memories below this salience floor.

.edges(include)bool

Include (or omit) each memory's outgoing edges. On by default.

.graph(include)bool

Include the resolved entity/statement/relation enrichment. Off by default.

.text(include)bool

Include the stored memory text. On by default.

.trace(trace=True)bool

Ask for the per-stage read-pipeline trace on the final frame. Off by default; costs nothing when off.

.act_as(namespace, agent_id)str, bytes

Run the read as an effective identity. Requires can_act_as.

The read knob is trace (a bool), not wait. Reads carry trace; writes carry wait (a WaitMode).

RECALL streams one or more RECALL_RESP frames terminated by EOS. recall drains them into a single RecallAnswer. For the raw frames — with their cumulative counts and estimated_remaining — use recall_frames:

for frame in client.recall_frames(req):
    print(frame.answer_kind, len(frame.memories))

MemoryResult fields (wire)

Each MemoryResult in a wire answer carries the full scoring and provenance surface: memory_id, text, similarity_score, confidence, salience, kind, fused_score, rerank_score (may be None when the reranker is off), contributing_retrievers, edges, occurred_at_unix_nanos, and — when .graph(True) was set — a graph enrichment. The similarity_score field is the cosine similarity.