> Full SurrealDB documentation index: https://surrealdb.com/docs/llms.txt

# Extraction pipeline

How structured memory is extracted from conversation turns. Classification and extraction in SurrealDB Agent Memory.

Every conversation turn SurrealDB Agent Memory receives passes through an extraction pipeline that turns raw text into structured memory: entities, attributes, relations, actions, instructions, and uncertainties. Extraction is one structured-output model call per window of text, with no separate heuristic or escalation stage.

## How a turn is extracted

1. **Windowing** - The turn text is split into windows of up to 8,000 new characters, and each window after the first also repeats the last 256 characters of the one before, so that a fact on a window boundary is seen by both windows. A turn produces at most 10 windows, which cover its first 80,000 characters. Text beyond that limit is dropped, and the server logs a warning and counts the dropped bytes.

2. **One call per window** - Each window is sent to the extraction model as one structured-output call. Turn extraction uses the deployment's default model; document extraction on the worker uses the Context's `extraction` stage (see [Models per stage](/docs/agent-memory/memory-and-knowledge/tuning/models-per-stage.md)).

3. **Merge** - The results of all windows are sanitised, joined, and deduplicated when more than one window ran.

You do not choose a model per turn. Every turn takes the same path, whatever its length or difficulty.

The figure below shows how two turns of different lengths are split into windows.

<img src="~/assets/img/diagrams/light/am-extraction-windows-light.webp" darkSrc="~/assets/img/diagrams/am-extraction-windows.webp" alt="A 20,500-character turn becomes three windows: characters 0-8,000, then 7,744-16,000, then 15,744-20,500, each window after the first repeating the previous 256 characters. A 95,000-character turn becomes ten windows covering its first 80,000 characters, and the remaining 15,000 characters are dropped, logged and counted. Each window is one structured-output call to the extraction model, and the results are merged and deduplicated." />

## What extraction produces

The pipeline returns a structured diff nested under **`extraction`** on **`POST /facts`**, or under each entry in **`extractions`** on **`POST /facts/batch`**:

```json
{
  "turnId": "01k7e2q4w9",
  "entities": [
    {
      "id": "01k7e2q4xa",
      "name": "Alice Chen",
      "entityType": "person",
      "memoryCategory": "identity",
      "isNew": true
    }
  ],
  "attributes": [
    {
      "id": "01k7e2q4xb",
      "entityId": "01k7e2q4xa",
      "key": "role",
      "value": "CTO",
      "memoryCategory": "identity"
    }
  ],
  "relations": [
    {
      "subject": "Alice Chen",
      "label": "works_at",
      "object": "Acme",
      "memoryCategory": "identity"
    }
  ],
  "actions": [],
  "instructions": [
    {
      "id": "01k7e2q4xc",
      "label": "Bullet-point responses",
      "description": "Always respond using bullet points"
    }
  ],
  "uncertainties": [
    {
      "about": "job title",
      "reason": "User joked about being CEO, then appeared to correct themselves"
    }
  ],
  "corrections": []
}
```

Each extracted **entity**, **attribute**, **relation**, and **action** carries a **`memoryCategory`** - one of `identity`, `knowledge`, or `context`. Labels the model emits outside that set (for example `emotion`, `group`) are **bucketed as `context`** during extraction rather than failing the turn. Episodic transcript material stays on **sessions** and **turns**; **instructions** and **uncertainties** are stored separately. See [Memory categories](/docs/agent-memory/mental-model/memory-categories.md).

Nothing is written blindly: extractions pass through [reconciliation](/docs/agent-memory/memory-and-knowledge/reasoning/reconciliation-and-supersession.md) before they become durable memory.

**Chat synthesis is separate.** `/chat` and Workbench replies are generated *after* extraction and recall. The response model may add narrative colour, continue a well-known story, or answer from general knowledge - only the structured **`extraction`** diff (and reconciled graph records) are durable memory attributed to your turns. If you paste prose from a published book, extracted **entities** and **relations** reflect what you sent; any additional storytelling in the chat reply is not automatically stored unless the extractor captures it as fact.

**Resilience:** if the model output for a turn cannot be parsed, SurrealDB Agent Memory still stores the conversational chunk and returns a chunk-only diff - the session is not aborted. When only some windows fail, the facts from the other windows are kept. Provider and transport errors are returned as errors, and token budget exhaustion returns `429`.

## When extraction runs

For interactive agents, extraction on a turn completes **before the API returns**, so the next **`/query`**, **`/state`**, or **`/profile`** call reflects what was just said.

```bash
curl -sS "$SURREAL_MEMORY_URL/api/v1/$SURREAL_MEMORY_CONTEXT_ID/facts" \
  -H "Authorization: Bearer $SURREAL_MEMORY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "I'\''m Alice, CTO at Acme. Always respond in bullet points.",
    "infer": "full",
    "scope": ["org/acme/user/alice"]
  }'
```

The response includes nested **`extraction`** plus `sessionId` and `turnId`.

## When extraction is incomplete

If structured extraction cannot be validated, SurrealDB Agent Memory still retains the turn text. The content remains searchable and can be reprocessed; you are not left with a silent failure. Open **`uncertainty`** records flag cases where the pipeline could not commit to a single interpretation - see [Instructions and uncertainties](/docs/agent-memory/memory-and-knowledge/reasoning/instructions-and-uncertainties.md).

## Untrusted metadata in prompts

Document titles, section paths, retrieved hit text, and LLM-emitted identifiers are **sanitised** before they are interpolated into extraction, chat, elaboration, or consolidation prompts - control characters and newline-based framing attacks are collapsed or truncated. This complements the ingest-time **injection scanner** (which inspects chunk body text). Sub-threshold injection findings are stored as **`uncertainty`** records scoped to the same visibility as the write they describe.

## Related reading

- [Reconciliation and supersession](/docs/agent-memory/memory-and-knowledge/reasoning/reconciliation-and-supersession.md)
- [Provenance and traceability](/docs/agent-memory/mental-model/provenance-and-traceability.md)
- [Adding turns](/docs/agent-memory/memory-and-knowledge/sessions/adding-turns.md)
- [REST API - facts and sessions](/docs/agent-memory/reference/rest-api.md)
