Skip to content
AugentaDocsOpen console ↗
Recall

Documentation

API reference
View Markdown

Recall

Retrieve relevant memory from a Workspace.

http
POST https://api.augenta.ai/v1/recall

Recall returns the memory in a Workspace that is relevant to a question. Call it before your model call and add the result to the prompt; see Add memory to your agent.

It searches every claim the Workspace holds once its experience is processed, including claims that have not joined an engram yet. It returns the matching claims and, when available, the summary of the engram the best match belongs to. Answer mode also writes an answer. One-shot Consolidate results are not stored, so Recall can't find them.

Modes

ModeHow to askWhat you getTimeout
Context?mode=contextRelevant memory, without a generated answer15 s
Answer?mode=answerA written answer, then the memory60 s

Context is the default when mode is left out, but such a request gets the 60 s limit. Send ?mode=context explicitly when your agent waits on the result.

Context mode suits code whose own model will read the memory. It does not call the answer model; retrieval can still use the configured embedding or query-processing models. Use answer mode when you want Augenta's model to write the answer.

Retrieval

RetrievalHow to askWhich claims come back
Deployment defaultomit retrievalUses the deployment's configured retrieval
Pool?retrieval=poolSearches every retained claim, ranked by meaning and by keyword
Constraint?retrieval=constraintThe claims your question's own phrases, terms, identifiers, times and quantities point to, ordered by how much each one narrows

Pool suits a question asked in someone's own words, such as an end user's message to your agent: send ?retrieval=pool for those. The default depends on the deployment, so name the retrieval you want. Constraint suits a question that names what it is about: a method, a component, an issue, a source. "What is subspace iteration" then returns claims about subspace iteration, not every claim that mentions a subspace or an iteration. A question that matches none of the Workspace's indexed phrases, terms, identifiers, times or quantities returns noMatch. Constraint returns only those claims: no engram or lineage block, because its constraints point to claims, not engrams. Retrieval combines with either mode.

Request

Authorizationstringrequired

AugentaKey <your key>. See Authentication.

X-Augenta-Contentstringdefault: content-v2

The response format to use. Send content-v3. Without this header you get content-v2, the older format, which calls each claim a note (note blocks, note_count, notes_truncated) and is otherwise the same. The default will become content-v3 and content-v2 will be removed. Any other value returns 406 unsupported_content. See Response versions.

Idempotency-Keystring

Required for stateful recall unless record: false. Any string up to 256 characters, such as a UUID. Retrying with the same key and query is safe: it records one activation, not two. The same key with a different query returns 409 idempotency_conflict.

querystringrequired

The question, up to 4,096 characters.

originstringdefault: manual

manual when a person asked; auto when your code recalls on its own, such as on every request. See Activations.

budget_tokensinteger

Context mode only. Roughly how many tokens of text you want back, from 100 to 8,000. Defaults to 6,000 for manual and 1,500 for auto.

workspacestring

Select one Workspace assigned to the key. Required with multiple assignments and inferred with exactly one. A key without assignments cannot use Recall.

recordbooleandefault: true

Set false for a read without recording reuse. It performs no activation lookup or write and ignores Idempotency-Key.

timezonestringdefault: UTC

The asker's IANA time zone, such as America/New_York. A time in the question ("what was done on October 13?", "yesterday") means that span of the asker's calendar, and reference_date is the asker's date. In a browser, send Intl.DateTimeFormat().resolvedOptions().timeZone. Workspace recall only.

Response

An answer-mode response, with X-Augenta-Content: content-v3:

json
{
  "workspace": "ws-platform",
  "mode": "answer",
  "reference_date": "2026-10-02",
  "claim_count": 14,
  "claims_truncated": false,
  "content": [
    { "type": "answer",  "text": "Checkout deploys through…" },
    { "type": "engram",  "text": "Checkout deploys via…", … },
    { "type": "claim",   "text": "Merging to main triggers…", … },
    { "type": "lineage", "text": "BORN (0->3 members)", … }
  ]
}

workspace is the authorized Workspace for a managed read. All Recall requests read Workspace memory. Returned metadata describes source lineage, such as the source, session and source sequences.

content is an ordered list of blocks. Every block has a type and a text:

typeWhat it is
answerThe written answer. Answer mode only; always first.
engramThe best matching claim's engram summary, when it belongs to one. Never under constraint retrieval.
claimOne retrieved statement, oldest first. Up to 100. Claims can come from different engrams or have no engram. A model wrote each from captured experience; it is not an archival copy.
lineageOne event in the matched engram's history, when available.

Three rules for reading it:

  1. Take the texts. For your own model, the engram text plus each claim text is the memory. The other fields are optional detail.
  2. To shrink it, drop lineage first. Claims are delivered in date order after retrieval and budget selection. Lower budget_tokens (context mode) so the server selects the evidence that fits, rather than cutting the list by its displayed order.
  3. Ignore unknown types. New block types may be added without notice.

reference_date is the latest date any returned claim was observed. Resolve "recently" against it, not against today. claim_count reports the selected evidence count before response limits; claims_truncated is true when some of that evidence was omitted. It is not a count of every claim in the Workspace.

Questions about a time

A time in the question selects claims by when they were recorded, not by dates their text mentions. "What was done on October 13?" reads the claims recorded on that day of the asker's calendar (timezone). With nothing else to search for, the claims are spread across every session and every active stretch of the day, so a busy session cannot crowd out the rest. With a topic as well ("what did we change in billing last week?"), they are the window's claims that best match it. A time nothing was recorded in is ignored, and the rest of the question is searched as usual.

Such a response carries a window, so you can tell the evidence from the whole record:

json
"window": {
  "from": "2026-10-13T04:00:00Z", "to": "2026-10-14T04:00:00Z", "timezone": "America/New_York",
  "claim_count": 868, "session_count": 8, "document_count": 3,
  "claims_shown": 96, "sessions_shown": 8, "selection": "coverage"
}

Here the response holds 96 of the 868 claims recorded that day, from all 8 sessions. In answer mode the model is told the same. Time windows are read by retrieval=constraint.

Full field definitions are in the API reference.

Streaming answers

An answer can take several seconds, most of it the model reasoning before it writes. To show the evidence and the answer as they arrive, send Accept: text/event-stream with mode=answer:

cURL
curl -N -X POST 'https://api.augenta.ai/v1/recall?mode=answer' \
  -H "Authorization: AugentaKey $AUGENTA_API_KEY" \
  -H 'Content-Type: application/json' \
  -H 'Accept: text/event-stream' \
  -H 'X-Augenta-Content: content-v3' \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"query": "How do we deploy the checkout service?"}'

The response is a stream of server-sent events:

EventDataWhen
evidenceThe response body without the answer: the claims and engram context retrieval selected.First, as soon as retrieval finishes.
status{"phase": "thinking"}, then {"phase": "answering"}When the model starts reasoning, and when it starts writing.
delta{"text": "…"}Each piece of the answer, in order.
doneThe full response body, the same one the JSON response would have.Last, when the answer is complete.
errorThe usual error body, plus status: the HTTP status the failure would have had.Last, instead of done, when the answer fails after the stream started.

A : keepalive comment arrives whenever 5 seconds pass with nothing else, so proxies do not close a quiet stream.

  • Join the delta texts to show the answer as it arrives; they add up exactly to the answer block in done. Replace what you built with done when it arrives.
  • Failures before the answer starts are not events. Authentication, validation, idempotency_conflict, at_capacity and an unavailable answerer return their usual HTTP status and error body. An empty Workspace returns the usual JSON noMatch body.
  • A stream that fails ends with one error event; an answer_failed error is retryable with the same Idempotency-Key. A stream that ends with neither done nor error was cut in transit; retry it the same way.
  • Context mode does not stream. It ignores the header and returns JSON. So does any Accept that does not name text/event-stream, including */*.
  • Closing the connection stops the answer. The activation was already recorded when the evidence was found.

Response versions

The X-Augenta-Content response header names the format the response uses. Ask for one with the same request header.

VersionMember blocksCounts
content-v3claimclaim_count, claims_truncated
content-v2 (current default, deprecated)notenote_count, notes_truncated

The two differ only in those names. Send X-Augenta-Content: content-v3 now, so nothing changes for you when the default moves to it.

Activations

A stateful recall with record: true records one activation when retrieval finds claims belonging to a real engram: a signal that the matched engram was useful. Claims outside engrams can be recalled without inventing an activation. Activations strengthen that engram the next time the Workspace consolidates. The question and answer themselves are not stored.

  • origin: "manual" counts fully. origin: "auto" counts a quarter, so code that recalls on every request doesn't outweigh deliberate questions.
  • Repeating a request with the same Idempotency-Key records only one activation.
  • The activation is recorded as soon as retrieval has found the evidence, before any answer is written. In answer mode, an answer that fails afterwards (502 answer_failed) keeps it, and retrying with the same key does not add a second.
  • A request refused before retrieval (authentication, validation, idempotency_conflict, an unavailable answerer) records nothing.

A new Workspace

A valid recall with no candidates returns 200, noMatch: true, empty content, and no score. Answer mode makes no model call in this case. Service and query failures still return errors.

Populated results have noMatch: false. Their score reports the actual retrieval method and raw value, with contributing dense and BM25 channel scores/ranks for whole-pool search. These are ranking evidence, not confidence probabilities; do not compare them across questions or Workspaces.