# 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](https://augenta.pages.dev/docs/agent-memory.md).

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

| Mode    | How to ask      | What you get                                | Timeout |
| ------- | --------------- | ------------------------------------------- | ------- |
| Context | `?mode=context` | Relevant memory, without a generated answer | 15 s    |
| Answer  | `?mode=answer`  | A written answer, then the memory           | 60 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

| Retrieval          | How to ask              | Which claims come back                                                                                                          |
| ------------------ | ----------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
| Deployment default | omit `retrieval`        | Uses the deployment's configured retrieval                                                                                      |
| Pool               | `?retrieval=pool`       | Searches every retained claim, ranked by meaning and by keyword                                                                 |
| Constraint         | `?retrieval=constraint` | The 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

**Authorization** (string, required)

`AugentaKey <your key>`. See [Authentication](https://augenta.pages.dev/docs/authentication.md).

**X-Augenta-Content** (string, optional)

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](https://augenta.pages.dev/docs/recall.md#response-versions).

**Idempotency-Key** (string, optional)

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`.

**query** (string, required)

The question, up to 4,096 characters.

**origin** (string, optional)

`manual` when a person asked; `auto` when your code recalls on its own, such as on every request. See [Activations](https://augenta.pages.dev/docs/recall.md#activations).

**budget_tokens** (integer, optional)

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`.

**workspace** (string, optional)

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

**record** (boolean, optional)

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

**timezone** (string, optional)

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`:

| `type`    | What it is                                                                                                                                                                           |
| --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `answer`  | The written answer. Answer mode only; always first.                                                                                                                                  |
| `engram`  | The best matching claim's engram summary, when it belongs to one. Never under constraint retrieval.                                                                                  |
| `claim`   | One 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. |
| `lineage` | One event in the matched engram's history, when available.                                                                                                                           |

Three rules for reading it:

1. **Take the `text`s.** 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](https://augenta.pages.dev/docs/api-reference/recall.md).

## 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`:

```bash 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:

| Event      | Data                                                                                    | When                                                                     |
| ---------- | --------------------------------------------------------------------------------------- | ------------------------------------------------------------------------ |
| `evidence` | The 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.                                      |
| `done`     | The full response body, the same one the JSON response would have.                      | Last, when the answer is complete.                                       |
| `error`    | The 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.

| Version                                    | Member blocks | Counts                            |
| ------------------------------------------ | ------------- | --------------------------------- |
| `content-v3`                               | `claim`       | `claim_count`, `claims_truncated` |
| `content-v2` (current default, deprecated) | `note`        | `note_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.
