This section explains how SurrealDB Agent Memory works. The mental model comes first, then each step a fact goes through, from ingest to retrieval, and last the architecture underneath. If context windows and embeddings are new to you, start with How an AI model remembers.
Concepts
Contexts and scope - where memory is stored, and who can read which part of it
Sessions and turns - the unit of a conversation
Memory categories - the six kinds of experiential memory
Supersession, decay, and forget - how a fact changes and ends
Provenance and traceability - where each fact came from
Unified substrate and authority - how documents and conversations meet in one graph
Agent Memory stores two kinds of material in one SurrealDB graph, the Authoritative and Experiential pillars from Eight pillars and six categories:
Authoritative - manuals, policies, product data, structured uploads (
source.kind = "document", higher default trust).Experiential - conversation, sessions, and derived facts (
source.kind = "turn", reflections, elaborations, consolidations).
The sections below are organised by what you do with them: ingest, retrieve, reason and tune.
Ingest
Authoritative
Experiential
Remember -
POST /factsand/facts/batchSessions - containers for turns (creating, adding turns)
Retrieve
Unified read path over facts and document passages:
Recalling memories -
/query,/context,/chat
HTTP tables: REST API and Surface, models, and security.
Reasoning
How writes are extracted, reconciled, and time-stamped - for both documents and turns:


