---
title: "Provenance and traceability"
description: "The source object carried on every record. Kinds, spans, trust, derivation, and traces."
canonical_url: "https://surrealdb.com/docs/agent-memory/learn/mental-model/provenance-and-traceability"
section: "Agent Memory"
surrealdb_version: "4.x"
last_modified: "2026-11-18T02:09:16Z"
---

> Full SurrealDB documentation index: https://surrealdb.com/docs/llms.txt

# Provenance and traceability

The source object carried on every record. Kinds, spans, trust, derivation, and traces.

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](/docs/agent-memory/learn/architecture/coherence-retrieval-and-tiers.md).

## 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](/docs/agent-memory/learn/architecture/tri-temporal-model.md) and [Supersession, decay, and forget](/docs/agent-memory/learn/mental-model/memory-lifecycle.md).

## 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](/docs/agent-memory/learn/architecture/traces-and-evolution.md).

## Practical surfaces

- HTTP: `GET /api/v1/{ctx}/traces`, `GET /api/v1/{ctx}/traces/{id}` ([REST API](/docs/agent-memory/reference/rest-api.md)).
- CLI: `surreal memory inspect trace:…`, `surreal memory entities history …` ([Surface, models, and security](/docs/agent-memory/learn/architecture/surface-security-and-models.md)).

## Related topics

- [Tri-temporal model](/docs/agent-memory/learn/architecture/tri-temporal-model.md)
- [Supersession, decay, and forget](/docs/agent-memory/learn/mental-model/memory-lifecycle.md)
- [Unified substrate and authority](/docs/agent-memory/learn/mental-model/two-layer-architecture.md)
