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 with the same blend of association, wording, and recency you would expect from a good colleague who was actually listening.
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.
Eight pillars, two streams, one graph
The full operational model is the eight pillars (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.
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 - the conceptual spine.
Why agentic memory? - why embeddings-only and “big context” shortcuts break down.
Cookbooks - patterns for assistants, support bots, coding agents, and shared memory.