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

# Unified substrate and authority

One SurrealDB graph for authoritative and experiential knowledge. Provenance and reconciliation in one place, rather than two silos.

SurrealDB Agent Memory stores authoritative and experiential knowledge in one SurrealDB graph. The eight pillars, especially Authoritative and Experiential, show up as records and edges, not as two databases.

> One multi-model SurrealDB substrate - documents, turns, entities, attributes, relations, embeddings, traces, and (where enabled) geometry - with provenance explaining which stream produced a record and reconciliation deciding how streams combine.

"Layers" are still a useful picture for authority: curated organisational truth versus conversational input. Both streams are records and edges in the same database, updated under ACID transactions.

## Two streams of truth (not two databases)

| Stream | Typical `source.kind` | What it holds | Default trust |
| --- | --- | --- | --- |
| **Authoritative** | `document` (and operator `upsert`) | Manuals, policies, product data, repos, structured exports | High - vetted sources |
| **Experiential** | `turn`, plus `reflect`, `elaboration`, `consolidation`, … | What users and agents said; synthesised or background-minted facts | Lower - must earn promotion |

Retrieval, elaboration, and consolidation see one `entity` / `relation` graph. Hybrid rankers fuse vectors, BM25, graph structure, keyword bridges, geo predicates, and trace-derived features without cross-store joins. A question like "semantically close to X, mentioning Y, linked to entity Z, valid as of last March" is one query over one engine.

## How authority is enforced

When an experiential assertion disagrees with authoritative material, the reconciler:

1. **Does not** silently overwrite curated records.
2. Records the experiential assertion with provenance intact.
3. Surfaces **`uncertainty`** (and/or conflict metadata) so you can see the gap.

That is how the **Authoritative** pillar wins over casual assertions: **authority is a reconciliation policy** applied within one database.

## Why this matters

- **Transactions** across “what the user said” and “what the handbook says” can be reasoned about **together**.
- **Contradictions** become first-class records you can query, not cosine-distance accidents.
- **[Traces](/docs/agent-memory/architecture/traces-and-evolution.md)** link decisions back to the sources considered.

## Related reading

- [Eight pillars and six categories](/docs/agent-memory/architecture/eight-pillars-and-categories.md)
- [Principles and goals](/docs/agent-memory/architecture/principles-and-goals.md)
- [Authority when pillars meet](/docs/agent-memory/reasoning/authority-hierarchy.md) - how curated and experiential streams interact in APIs today