# What is SurrealDB Agent Memory?

SurrealDB Agent Memory as a memory and knowledge layer - one SurrealDB substrate, provenance-first, trace-aware, tri-temporal.

SurrealDB Agent Memory is a **memory and knowledge layer for AI agents**. It runs as a **horizontally scalable application tier** in front of **SurrealDB**; every durable thing you care about - documents, turns, entities, attributes, relations, embeddings, **and traces** - lives in **one** multi-model database with **ACID** semantics per write.

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.

On SurrealDB, documents, graph edges, and index entries share one transactional core, so a write that touches a record, its relations, and its embeddings commits **atomically** under snapshot isolation - not as best-effort coordination across separate engines.

## 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 richness 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 with the same blend of association, wording, and recency you would expect from a good colleague who was actually listening.

## What problem it solves

Most agents **do not retain memory between sessions**, or they approximate memory by:

- Truncating ever-growing chat transcripts, or
- Embedding turns into a vector index with **no** structured reconciliation, **no** contradiction handling, and **no** defensible audit trail.

SurrealDB Agent Memory instead **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.