SurrealDB Agent Memory’s accuracy story depends on one invariant: no fact-bearing record is anonymous. Provenance is a structured field, not an afterthought in application logs.
The source object (conceptual)
Every fact-bearing record (entity, attribute, relation, instruction, uncertainty, …) carries a source object:
| Field | Role |
|---|---|
source.kind | turn, document, upsert, reflect, elaboration, consolidation, … |
source.ref | Originating turn, document, or trace identifier |
source.session_id, source.turn_at | When the record came from conversation |
source.valid_from, source.span: { start, end } | Valid-time anchor and quote position in the originating message or passage |
source.location | Optional geometry for where the fact was captured |
source.trust | Source prior - admin documents rank above casual turns |
source.derived_from | Lineage for reflections, elaborations, consolidations |
Some JSON examples in the docs show a flat source_turn field - that is the conversational shorthand for source.ref.
Why spans matter
source.span stores character positions in the originating turn or document passage. Citations are stored data, not best-effort model prose. That powers “jump to quote” in UIs and defensible audit; tiered reads are described in Coherence, retrieval, and cost tiers.
Multiple sources, one audit trail
When several sources support or contradict the same topic, SurrealDB Agent Memory does not flatten them into a single anonymous record. Each assertion keeps its own provenance. Cross-provenance disagreement becomes uncertainty; same-stream updates supersede with a chain you can replay.
Retrieval defaults return the current view with sources attached, traceable to originating bytes. as_of and entity history endpoints return what the system would have answered at an earlier instant - a correction appears as a transition in history, not a missing gap. See Tri-temporal model and Supersession, decay, and forget.
Traces complete the story
Extraction and reconciliation emit decision_trace nodes. Ranked reads emit retrieval_trace; /chat and /reflect emit response_trace. Together they answer “which source produced this belief?” and “which retrieval path led to this answer?” Full detail: Traces and memory evolution.
Practical surfaces
HTTP:
GET /api/v1/{ctx}/traces,GET /api/v1/{ctx}/traces/{id}(REST API).CLI:
spectron inspect trace:…,spectron entities history …(Surface, models, and security).