How it works in five minutes

From a message to structured substrate state – extraction, reconciliation, traces, and tiered reads.

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 pretending both versions are 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 (pattern + 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 still reconcile identically.

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 tell the story).

Read path: tiered resolution

Reads climb a four-tier ladder after a small query-understanding step. Spectron always tries the cheapest tier first (fewest tokens, lowest latency) and only escalates when the current tier cannot answer confidently:

Structured lookup when the question maps to a key in the graph.
Semantic response reuse when a prior response_trace still cites current facts (reused_from links the new trace).
Hybrid retrieval + synthesis – BM25, vectors, graph hops, keyword bridges, trace-derived features fused into one ranking, then LLM synthesis.
Broader sweep 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 Spectron drive /chat, or you can own the loop and call ingest + /query yourself via the REST API and Integrations.