# Provenance and traceability

The source object on every record - kinds, spans, trust, derivation, and traces.

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](/docs/agent-memory/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/architecture/tri-temporal-model.md) and [Supersession, decay, and forget](/docs/agent-memory/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/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: `spectron inspect trace:…`, `spectron entities history …` ([Surface, models, and security](/docs/agent-memory/architecture/surface-security-and-models.md)).

## Related topics

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