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

# What is SurrealDB Agent Memory?

A memory and knowledge layer for AI agents. One SurrealDB substrate, provenance-first, trace-aware, and tri-temporal.

SurrealDB Agent Memory is a memory and knowledge layer for AI agents. It runs as an application tier in front of SurrealDB. Documents, turns, entities, attributes, relations, embeddings, and traces all live in one multi-model database, and each write is an ACID transaction.

That single-substrate choice avoids stitching a **relational database**, a **vector index**, and a **graph store** by hand - with dual writes, sync jobs, and drift when those stores disagree. Documents, graph edges, and index entries share that transactional core. A write that touches a record, its relations, and its embeddings commits atomically under snapshot isolation.

## Designed like human memory

You already know how memory feels. Hear the word **cat** and you do not store one flat sentence - you bring up a web of associations: a pet on the sofa, a lion on a documentary, a sports nickname, even a distant link like “Richard the Lionheart”. SurrealDB Agent Memory aims for that shape in software: one **entity** (`Cat` or `Animal/cat`) linked to images, facts, documents, and things people said, so recall can follow meaning and connection, not only text similarity.

Human memory also cares about **time and who it is about**. The same word “cat” in four short sentences is four different kinds of memory:

| What someone says | How you read it | What SurrealDB Agent Memory models |
| --- | --- | --- |
| “I have a cat.” | A **present** fact about **this** person | Scoped **identity** / **knowledge**, valid **now** |
| “I saw a cat last night.” | A **past episode** tied to the speaker | **Episodic** turn plus extracted fact with **valid time** in the past |
| “House cats weigh about 4 kg.” | A **general** fact, not about the speaker | Broader-scope **knowledge** (or **authoritative** if it came from a manual) |
| “I used to have a cat.” | Something **true before**, not now | **Supersession** - old belief kept, end dated with `valid_until` |

You do not need a special mental model for “vector database” versus “graph database”. SurrealDB Agent Memory is the layer that turns chat and documents into **structured, time-aware beliefs** agents can trust - then retrieves them by a blend of association, wording, and recency.

## What problem it solves

An agent that only keeps the current window forgets everything when the session ends. The usual stand-ins are:

- Truncating an ever-growing chat transcript, or
- Embedding turns into a vector index with no structured reconciliation, no contradiction handling, and no audit trail you can query.

SurrealDB Agent Memory extracts structured entities, attributes, and relations, attaches provenance (`source.kind`, spans, trust, derivation), runs everything through one reconciler, and stores traces of retrieval and decisions as graph nodes that feed back into ranking and consolidation.

## What SurrealDB Agent Memory is *not*

SurrealDB Agent Memory is **not** a vector database, a chat-log archive, a hand-authored knowledge graph, a context-window manager, a full agent runtime, or an observability SaaS. See [Principles and goals](/docs/agent-memory/architecture/principles-and-goals.md).

## Eight pillars, two streams, one graph

The full operational model is the **[eight pillars](/docs/agent-memory/architecture/eight-pillars-and-categories.md)** (authoritative and experiential knowledge, reflection, elaboration, consolidation, calibration, collective memory, and the trace layer). The first two pillars are often described as two **streams** of knowledge because they answer different questions:

- **Authoritative** - manuals, policies, product data, repos - via **document** ingest (`source.kind = "document"`).
- **Experiential** - what people and agents said - via turns and related paths (`source.kind = "turn"`, `reflect`, `elaboration`, `consolidation`, …).

Both streams land in the **same** `entity` / `relation` graph. **Authority** is expressed by **reconciliation and trust**, not by copying records between silos. When chat disagrees with a curated document, the reconciler records **uncertainty** and supersession metadata - it does not silently overwrite curated truth.

Read more in [Unified substrate and authority](/docs/agent-memory/mental-model/two-layer-architecture.md).

## Contexts

A **Context** is the hard **isolation** unit: its own SurrealDB namespace/database, keys, and quotas. End-user HTTP paths are rooted at `/api/v1/{context_id}/…`.

## Where next?

- [Eight pillars and six categories](/docs/agent-memory/architecture/eight-pillars-and-categories.md) - the conceptual spine.
- [Why agentic memory?](/docs/agent-memory/welcome/why-agentic-memory.md) - why embeddings-only and “big context” shortcuts break down.
- [Cookbooks](/docs/agent-memory/cookbooks.md) - patterns for assistants, support bots, coding agents, and shared memory.