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
Windowing - The turn text is split into windows of up to 8,000 characters, with a 256-character overlap so that a fact on a window boundary is seen by both windows. A turn produces at most 10 windows. Text beyond that limit is dropped, and the server logs a warning and counts the dropped bytes.
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
extractionstage (see Models per stage).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.
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:
{
"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.
Nothing is written blindly: extractions pass through reconciliation 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.
curl -sS "$SPECTRON_URL/api/v1/$SPECTRON_CONTEXT_ID/facts" \
-H "Authorization: Bearer $SPECTRON_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.
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.