This page sketches the lifecycle from a user message to durable, queryable state in SurrealDB, and how a later question is answered cheaply first, with expensive paths only when needed.
Think of it as teaching an agent to remember the way people do: capture what was said (episodic), pull out who someone is and what they know (identity and knowledge), note what matters right now (context), link "cat" to manuals and prior turns (association in one graph), and when someone says "I used to have a cat", close the old fact instead of treating both versions as current.
For pillars, categories, hybrid retrieval, trace feedback, and tri-temporal semantics, see the overview hub and Principles and goals.
End-to-end write path
User message (or uploaded file)
│
▼
Session / ingest
(turn record or async document job)
│
▼
┌───────────────────────────────┐
│ Extraction (LLM) │ Typed entities, attributes, relations
└───────────────┬───────────────┘
▼
┌───────────────────────────────┐
│ Reconciliation (one function)│ Dedup, scope, supersession, uncertainty
└───────────────┬───────────────┘
▼
┌───────────────────────────────┐
│ SurrealDB substrate │ Graph + vectors + docs + geometry
│ + decision_trace nodes │ Linked to considered / created records
└───────────────────────────────┘Sessions and turns remain the conversational unit of work. Documents enter the multi-modal Knowledge ingest pipeline instead of the turn path; extracted facts reconcile through the same pipeline.
Reconciliation in one sentence
New extractions never “win” by accident: they are merged, superseded, or rejected into uncertainty using the same rules whether the source was a turn or a document (source.kind and trust decide how they combine).
Read path: tiered resolution
Reads go through four tiers after a small query-understanding step. Cheaper steps run first (fewest tokens, lowest latency), and a more costly step runs only when the cheaper ones cannot answer confidently:
Response reuse (
cache, tier 2) is checked first. When a priorresponse_tracefor a similar question still cites current facts, its answer is reused (reused_fromlinks the new trace).Structured lookup (
direct, tier 1) reads the attribute or relation a question maps to in the graph. These rows do not end the request: they are added as seeds to tier 3.Hybrid retrieval (
hybrid, tier 3) - BM25, vectors, graph hops, keyword bridges and trace-derived features fused into one ranking, together with the tier 1 seeds.Escalation (
escalated, tier 4) rewrites the query (HyDE) and re-ranks, only when tier 3 is thin or low-confidence.
Each tier emits retrieval_trace metadata so you can see which tier answered and why. Full detail: Coherence, retrieval, and cost tiers.
What is stored on each fact
Beyond value and scope, expect source.*, valid_from / valid_until, confidence, and edges into decision_trace records. The invariants are: provenance is mandatory, supersession is non-destructive, and uncertainty is representable.
Integration shapes
You can let SurrealDB Agent Memory drive /chat, or you can own the loop and call ingest + /query yourself via the REST API and Integrations.