# Consolidate

> Extract claims and engrams from input in one call, or add input to a Workspace and get its claims back.

`POST /v1/consolidate` extracts claims from your input. It runs in one of two modes:

| Request             | What happens                                                                                                                                                                | Typical use                                                                                           |
| ------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------- |
| Omit `workspace`    | **One-shot.** Only this input is processed: its claims are grouped into engrams and returned, and nothing is stored.                                                        | Trying the API; summarizing a conversation you hold yourself.                                         |
| Include `workspace` | **Workspace.** The input is stored as experiences, and the call returns once their claims are extracted and searchable by Recall. Engrams form from them in the background. | Adding input when you need its extracted claims, or recalled context for a question, in the response. |

Send chat messages in the OpenAI or Anthropic format with a `session` name, or send
[experience envelopes](https://augenta.pages.dev/docs/experiences.md#the-envelope). Message text is read in full. Tool calls and
tool results are accepted and checked, but claims are never extracted from them and they are
not [billed](https://augenta.pages.dev/docs/billing.md#exactly-what-is-measured). Reasoning signatures and encrypted or redacted
content are dropped before extraction too. Media (images, audio,
files) and a tool result without its matching tool call are refused before processing starts.

> Note:
>
> To give an agent memory turn by turn, don't call Workspace Consolidate on every turn. It holds the
> request open while a model extracts the input's claims, and only a few calls run at a time. Add
> each turn with [Experiences](https://augenta.pages.dev/docs/experiences.md), which answers as soon as the turn is stored, and read
> memory with [Recall](https://augenta.pages.dev/docs/recall.md); see [Add memory to your agent](https://augenta.pages.dev/docs/agent-memory.md).

## One-shot processing

```json
{
  "session": "hello-world",
  "messages": [
    {
      "role": "user",
      "content": "Production releases require owner approval. Record a rollback image digest before deployment."
    }
  ]
}
```

The equivalent experience-envelope form:

```json
{
  "experiences": [
    {
      "src": "service",
      "sid": "release-runbook",
      "type": "doc",
      "data": {
        "documentId": "release-runbook",
        "text": "Production releases require owner approval. Record a rollback image digest before deployment.",
        "capturedAt": "2026-10-28T12:00:00Z"
      }
    }
  ]
}
```

A completed one-shot result:

```json
{
  "experiences": [
    {
      "id": "exp_222222222222222222222222",
      "status": "consolidated",
      "claimIds": [
        "clm_111111111111111111111111"
      ],
      "object": "experience"
    }
  ],
  "engrams": {
    "object": "list",
    "data": [
      {
        "object": "engram",
        "id": "eng_333333333333333333333333",
        "summary": "Production releases need owner approval and a recorded rollback image digest.",
        "label": "releases \u00b7 rollback",
        "labelSupport": 1,
        "memoryClass": "semantic",
        "status": "active",
        "strength": 1.5,
        "heatShare": 1,
        "claimCount": 1,
        "claimTokenCount": 15,
        "bornAt": "2026-10-28T12:00:00Z",
        "updatedAt": "2026-10-28T12:00:00Z",
        "claims": {
          "object": "list",
          "data": [
            {
              "id": "clm_111111111111111111111111",
              "text": "Production releases require owner approval and a recorded rollback image digest.",
              "experience": "exp_222222222222222222222222",
              "at": "2026-10-28T12:00:00Z",
              "object": "claim"
            }
          ],
          "nextPageUrl": null,
          "truncated": false
        }
      }
    ],
    "nextPageUrl": null,
    "truncated": false
  },
  "timing": {
    "firstClaimMs": 12,
    "firstEngramMs": 17,
    "totalMs": 21
  },
  "usage": {
    "tokensSent": 13,
    "tokensSentSource": "estimate:utf8-bytes/3.5"
  },
  "extractedClaims": {
    "object": "list",
    "data": [
      {
        "id": "clm_111111111111111111111111",
        "text": "Production releases require owner approval and a recorded rollback image digest.",
        "experience": "exp_222222222222222222222222",
        "at": "2026-10-28T12:00:00Z",
        "object": "claim"
      }
    ],
    "nextPageUrl": null,
    "truncated": false
  },
  "extractedClaimsComplete": true,
  "events": []
}
```

Nothing is stored. IDs identify objects within this result only: they can't be looked up, and the
same input sent again need not produce the same IDs. `session` names the conversation; in
one-shot mode it is not kept.

## Workspace processing

Include `workspace` to add the input to that Workspace's memory. In this mode the messages are
stored as an experience under `session`, so later calls and [Recall](https://augenta.pages.dev/docs/recall.md) can use them. Send
each message once, with a `seq` that counts up across the whole conversation: when the
conversation continues, send only the new messages under the same `session`, numbered on from the
last `seq` you sent.

```json
{
  "workspace": "ws-research",
  "session": "hello-world",
  "messages": [
    {
      "role": "user",
      "content": "Production releases require owner approval. Record a rollback image digest before deployment.",
      "seq": 0
    }
  ],
  "query": "What is required before production releases?"
}
```

The next call in this conversation numbers its messages from `"seq": 1`. Without `seq`, every call
numbers its messages from 0, so a later call reuses numbers an earlier call stored and is refused
with `409 conflict`; the messages stored first stay. A retry of the same request is accepted.

Experience envelopes use the same request:

```json
{
  "workspace": "ws-research",
  "experiences": [
    {
      "src": "service",
      "sid": "release-runbook",
      "type": "doc",
      "data": {
        "documentId": "release-runbook",
        "text": "Production releases require owner approval. Record a rollback image digest before deployment.",
        "capturedAt": "2026-10-28T12:00:00Z"
      }
    }
  ]
}
```

The call returns once the input's claims are extracted, stored and searchable by
[Recall](https://augenta.pages.dev/docs/recall.md). It doesn't wait for them to be grouped into engrams: consolidation runs in the
background, and `GET /v1/experiences/{id}` reports `consolidated` once it covers the experience.
A `query` runs Recall after the claims are stored, so it already finds them, and returns `context`:

```json
{
  "workspace": "ws-research",
  "operation": "op_5f2c9a7e1b3d4c6a8e0f2b4d",
  "experiences": [
    {
      "id": "exp_222222222222222222222222",
      "status": "processed",
      "object": "experience"
    }
  ],
  "usage": {
    "tokensSent": 27,
    "tokensSentSource": "estimate:source-chars/3.5",
    "modelInputTokens": null,
    "modelOutputTokens": null
  },
  "context": {
    "memory": [
      {
        "type": "claim",
        "text": "Production releases require owner approval and a recorded rollback image digest.",
        "timestamp": "2026-10-28T12:00:00Z",
        "question": false,
        "frame": {},
        "metadata": {
          "src": "service",
          "sid": "hello-world"
        }
      }
    ],
    "messages": [
      {
        "role": "user",
        "content": "Production releases require owner approval. Record a rollback image digest before deployment."
      }
    ],
    "budget_tokens": 6000,
    "tokensEstimated": 48,
    "tokenEstimateSource": "estimate:utf8-bytes/3.5",
    "memoryTruncated": false
  },
  "timing": {
    "firstClaimMs": 2140,
    "firstEngramMs": null,
    "totalMs": 2910
  },
  "extractedClaims": {
    "object": "list",
    "data": [
      {
        "id": "clm_111111111111111111111111",
        "text": "Production releases require owner approval and a recorded rollback image digest.",
        "experience": "exp_222222222222222222222222",
        "at": "2026-10-28T12:00:00Z",
        "object": "claim"
      }
    ],
    "nextPageUrl": null
  },
  "extractedClaimsComplete": true
}
```

| Field                     | What it holds                                                                                                                                                                                  |
| ------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `experiences`             | One reference per experience, with `status` `processed`, or `superseded` when a newer revision of the same document was already stored. Poll `GET /v1/experiences/{id}` to see `consolidated`. |
| `extractedClaims`         | The claims extracted from this call's input. Follow `extractedClaims.nextPageUrl` unchanged for more; `include: []` leaves it out.                                                             |
| `extractedClaimsComplete` | `true` when extraction covered all of the input.                                                                                                                                               |
| `context.memory`          | The [Recall](https://augenta.pages.dev/docs/recall.md#response) blocks for `query`, within `budget_tokens` (default 6,000). Empty when no `query` is sent. Add their `text` to your model's prompt.   |
| `context.messages`        | The last `keep_recent` (default 6) of the messages you sent, kept whole with their tool calls. Your own messages, returned for convenience: memory is not inserted into them.                  |
| `context.memoryTruncated` | `true` when blocks were left out to fit `budget_tokens`.                                                                                                                                       |
| `timing.firstEngramMs`    | Always `null` in Workspace mode, which returns before engrams form.                                                                                                                            |

The response has no `engrams` or `events`. Once the experiences are consolidated, read the engrams
with [Engrams](https://augenta.pages.dev/docs/engrams.md) and their lifecycle with [Events](https://augenta.pages.dev/docs/events.md).

`query`, `budget_tokens` and `keep_recent` apply only to Workspace mode. Accepted input keeps
processing if your client disconnects.

## Parameters

See [the endpoint reference](https://augenta.pages.dev/docs/api-reference/consolidate.md) for every parameter and attribute.

* `summaries: false` (one-shot only) skips writing summaries and omits `summary`, `label` and
  `labelSupport`. A Workspace's summaries follow its own settings.
* `include`: one-shot mode defaults to `["claims", "extractedClaims"]`; send a subset, or `[]`.
  Workspace mode accepts only `"extractedClaims"`, its default; `[]` leaves it out, and `"claims"`
  is refused with `400 invalid_request`.
* `claims_limit` defaults to 100 and accepts 1–500. `engrams_limit` (same bounds) is one-shot
  only; a Workspace call that sends it gets `400 invalid_request`.
* One-shot collections have `nextPageUrl: null` and a `truncated` flag that is `true` when items
  were left out. Workspace collections carry a `nextPageUrl` to follow unchanged.

## Streaming

Send `stream: true` or `Accept: text/event-stream` to receive progress and provisional claims as
they are extracted, then one completed result. One-shot streams also send engram previews as they
form. Previews carry the available
labels and extractive summaries, without extra summarization calls. They have `preview_` IDs and
may be replaced; only the completed result is final. A Workspace stream sends no engram previews.
A stream that ends with an `error` event has no completed result. Use streaming for long inputs: a
JSON request that runs past its deadline (about 90 seconds) fails with `operation_timeout`.

## Common errors

| Code                | HTTP | Action                                                                                                                       |
| ------------------- | ---- | ---------------------------------------------------------------------------------------------------------------------------- |
| `invalid_request`   | 400  | Correct the input; `message` names the problem.                                                                              |
| `at_capacity`       | 429  | Wait `Retry-After` seconds, then send the same request.                                                                      |
| `operation_timeout` | 504  | Send the request again with `stream: true`.                                                                                  |
| `conflict`          | 409  | This `session` already stored other messages under these `seq` numbers. Number new messages on from the last `seq` you sent. |
| `cursor_stale`      | 409  | The Workspace changed while the result was read; send the same request again.                                                |
