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. 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. 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.
One-shot processing
{
"session": "hello-world",
"messages": [
{
"role": "user",
"content": "Production releases require owner approval. Record a rollback image digest before deployment."
}
]
}
The equivalent experience-envelope form:
{
"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:
{
"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 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.
{
"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:
{
"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. 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:
{
"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 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 and their lifecycle with Events.
query, budget_tokens and keep_recent apply only to Workspace mode. Accepted input keeps
processing if your client disconnects.
Parameters
See the endpoint reference for every parameter and attribute.
summaries: false(one-shot only) skips writing summaries and omitssummary,labelandlabelSupport. 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 with400 invalid_request.claims_limitdefaults to 100 and accepts 1–500.engrams_limit(same bounds) is one-shot only; a Workspace call that sends it gets400 invalid_request.- One-shot collections have
nextPageUrl: nulland atruncatedflag that istruewhen items were left out. Workspace collections carry anextPageUrlto 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. |