SurrealDB Agent Memory’s accuracy 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.
Default trust by source
source.trust comes from the kind of source that wrote the record:
source.kind | Default trust | Written by |
|---|---|---|
upsert | 0.95 | Triples sent to POST /facts with infer: "triples" |
document | 0.80 | Document uploads |
turn | 0.50 | Conversation turns |
reflect | 0.40 | Persisted reflections |
consolidation | 0.35 | Background consolidation |
elaboration | 0.30 | Background elaboration |
Every turn has the same trust. The role recorded on a turn, such as user or assistant, does not change it, and Agent Memory has no setting that weights one speaker above another. To give a statement more weight than a document, write it as triples. Where a triple carries no confidence, its trust is also its starting confidence.
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 is what “jump to quote” in UIs is built on; 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:
surreal memory inspect trace:…,surreal memory entities history …(Surface, models, and security).