Skip to content

Docs

Sign In

Welcome

How it works in five minutes

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

A message or a file passes through extraction and reconciliation before anything is stored, as the figure below shows.

The write path. A user message, sent with POST /facts, /chat or MCP remember, becomes a session turn. An uploaded file, sent with POST /documents, becomes an asynchronous document job chunked by section. Both go to extraction, an LLM step that runs one structured-output call per window and produces entities, attributes, relations, actions, instructions and uncertainties. Reconciliation, one function in one ACID transaction per write, matches each entity by its type and name, supersedes a value with the same scope and provenance, and records an uncertainty for a value with different provenance or below the confidence floor. The result is stored in SurrealDB as graph, vectors, documents and geometry, with a decision_trace linked to the records the write considered and created.The write path. A user message, sent with POST /facts, /chat or MCP remember, becomes a session turn. An uploaded file, sent with POST /documents, becomes an asynchronous document job chunked by section. Both go to extraction, an LLM step that runs one structured-output call per window and produces entities, attributes, relations, actions, instructions and uncertainties. Reconciliation, one function in one ACID transaction per write, matches each entity by its type and name, supersedes a value with the same scope and provenance, and records an uncertainty for a value with different provenance or below the confidence floor. The result is stored in SurrealDB as graph, vectors, documents and geometry, with a decision_trace linked to the records the write considered and created.

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:

  1. Response reuse (cache, tier 2) is checked first. When a prior response_trace for a similar question still cites current facts, its answer is reused (reused_from links the new trace).

  2. 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.

  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.

  4. Escalation (escalated, tier 4) rewrites the query (HyDE) and re-ranks, only when tier 3 is thin or low-confidence.

The figure below shows the same four tiers in execution order, with the conditions for each exit.

The read path in execution order. Query understanding classifies and embeds the question. Tier 2 response reuse returns a prior answer when a previous query has cosine similarity of at least 0.92 and its cited facts are still current, exiting with tier cache. On a miss, tier 1 structured reads look up attributes and relations in the graph without an LLM; they never end the request and their rows join tier 3 as seeds. Tier 3 fuses vector, BM25 and graph signals over 256 candidates and exits with tier hybrid unless it escalates. It escalates when the classifier asks for full context, when fewer than k / 2 hits came back, or when the top fused score is below 0.40 and the best vector cosine is below 0.80. Tier 4 rewrites the query with HyDE, doubles the pool to 512, re-ranks and exits with tier escalated. Tier 2 runs on /chat only, and is skipped on /query, /context, /reflect and the MCP read tools, when the session already has prior turns, when bypassCache is true, and when the read has a time or location filter.The read path in execution order. Query understanding classifies and embeds the question. Tier 2 response reuse returns a prior answer when a previous query has cosine similarity of at least 0.92 and its cited facts are still current, exiting with tier cache. On a miss, tier 1 structured reads look up attributes and relations in the graph without an LLM; they never end the request and their rows join tier 3 as seeds. Tier 3 fuses vector, BM25 and graph signals over 256 candidates and exits with tier hybrid unless it escalates. It escalates when the classifier asks for full context, when fewer than k / 2 hits came back, or when the top fused score is below 0.40 and the best vector cosine is below 0.80. Tier 4 rewrites the query with HyDE, doubles the pool to 512, re-ranks and exits with tier escalated. Tier 2 runs on /chat only, and is skipped on /query, /context, /reflect and the MCP read tools, when the session already has prior turns, when bypassCache is true, and when the read has a time or location filter.

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.

Next steps

Was this page helpful?

Previous

The accuracy promise

Next

Principles and goals