TECHNICAL DEEP DIVE

Agent Memory,
under the hood

Start in Studio Read the documentation Book a demo

Typed. Every fact is an attribute, a relation or an action.

Dated. A new value closes the old one instead of overwriting it.

Traceable. Every chat answer is traced to the facts behind it.

01 |ANATOMY

The six parts of an agentic system. One decides what the model knows.

1 The agent

LLM · tools · loop

2 The context window

Working memory - where the traditional agent forgets

Capture

Recall · inject

Agent Memory

3 The context layer

“What does the model need to know right now?”

gathers · filters · packages

4 Memory

Everything the agent learned

episodic · identity · knowledge · context · instructions · uncertainty

5 The knowledge graph

How everything is connected

entities · typed edges · properties

6 Storage

One multi-model database

documentgraphvectorfull-text

Agent Memory is the bottom four: the context layer, memory, the knowledge graph and storage.

02 |TYPED MEMORY

Conversations become typed facts. Reconciled in code, so the outcome is repeatable.

Agent Memory turns conversations and documents into typed facts about entities. Every fact is one of three primitives: an attribute (a key and value on an entity), a relation (a directed link between two entities) or an action (something an entity did, and when). Each fact records when it was true in the world, when it was learnt, its source and its confidence.

Source

Conversations and documents

Extracted into typed facts about entities

Attribute

A key and value on an entity

Relation

A directed link between two entities

Action

Something an entity did, and when

Every fact records

Fact record

When it was trueWhen it was learntSourceConfidence

Reconciler

Decides in code, not in a model

A conflict between sources of different kinds, or a hedged value against a stronger one, becomes an uncertainty row for review.

Each fact tagged by category

Identity

Knowledge

Context

Memory is organised into six categories. Each fact is tagged identity, knowledge or context, and conversations, instructions and uncertainties are kept as records of their own.

Episodic

The raw conversational record: sessions and turns as authored, in order. Extracted facts cite back to it.

Identity

Durable facts about who the user is: name, role, employer and preferences.

Knowledge

Things the user has learnt or shared: project facts, observations and references.

Context

What is going on now: active topics, recent intents and the working set for the current conversation.

Instructions

Behavioural memory, such as 'always answer in British English'. It is applied when the prompt is assembled rather than at retrieval.

Uncertainty

Explicit 'not yet known' rows, written when confidence is under the floor or sources contradict, so gaps stay visible.

03 |RECONCILIATION

Reconciled before it is stored. Four rules shape the outcome.

Decided in code

Reconciliation decisions are made in code, not by a model, so they are repeatable.

Contradictions stay visible

When sources of different kinds disagree, the conflict is recorded as uncertainty for review rather than resolved silently.

Confidence is respected

A value the model scores below the confidence floor, or below the current value, is held as uncertainty instead of replacing it.

Matched by name

Entities are matched by name, so differently named references to the same entity are not merged automatically. This is a stated trade-off.

04 |KNOWLEDGE GRAPH

One graph for conversations and documents. Cited back to the source passage.

One entity and relation graph is shared by conversations and documents. Documents are parsed (PDFs, and images, audio and video), chunked, extracted, linked by section and keyword, and cited back to the source passage.

chunk

text

embeddingvector

passage_id

source

kind

ref

span

trust

source

attribute

key

value

confidence

valid_from

source

entity

type

name

memory_category

relates_to

label

valid_from

valid_until

entity

type

name

memory_category

05 |TEMPORAL MEMORY

Three clocks. A changed fact is closed, never overwritten.

System time, known time and valid time each answer a different question, and each is queryable on its own.

System time

SurrealDB VERSION

Known time

as_of

Valid time

valid_from, valid_until

A changed value, on valid time

Earlier value

role: engineer

valid_until is set when the new value arrives

Current value

role: manager

valid_until is none while the value is current

Query

What did we believe on this date?

One query with as_of, answered from the chain of superseded rows.

System time

SurrealDB's VERSION history records when the datastore changed, so the datastore can be read as it was at an instant.

Known time

as_of reads the chain of beliefs: when Agent Memory first learnt a fact. 'What did we believe on this date' is one query.

Valid time

valid_from and valid_until record when a fact held in the world, independently of when it was learnt.

Supersession, not overwrite

A new value closes the validity of the old one by setting its valid_until. History is kept, so storage grows with it.

Forget and purge

forget retires a fact. purge removes its history as well, so erasure needs purge and not forget alone.

Visible to the next read

A new fact is reconciled when it is written and is visible to the very next read. Nothing is re-indexed overnight.

06 |PROVENANCE

Every answer walks back to its source. Its traces are stored as data.

Provenance is recorded on the facts themselves and in traces written to the tenant's own database, so any answer can be reconstructed from the records behind it.

Fact

A source object and a confidence

kind and trust, with ref and span or derived_from

Traced in the tenant's own database

Decision trace

Every write

Retrieval trace

Every ranked read

Response trace

Every answer

Audit events, exported through OpenTelemetry

DeletionsForgetsConfiguration changesBackground jobsDenied access

A source on every fact

Every fact has a source object with its kind and trust, plus a ref and span back to the passage, or derived_from for a fact the system inferred, together with a confidence.

Three kinds of trace

Writes record decision traces, ranked reads record retrieval traces, and chat and reflect answers record response traces, each linked to the facts it touched. The traces endpoint and the inspect MCP tool query them.

Kept in the tenant's database

Traces live in the tenant's own database. Retention is set per tenant: decision traces are kept indefinitely by default, retrieval and response traces for 90 days.

An audit-event stream

A separate stream, exported through OpenTelemetry, records writes, deletions, forgets, key and configuration changes, background jobs and denied access attempts.

07 |RECALL

Four tiers, one trace. Seven signals, one ranking.

A recall request goes through a four-tier router. The cheapest path that can answer is taken: a repeated chat question whose facts have not changed reuses the earlier answer.

Recall request

Routed through up to four tiers

The tier entered, and why, is recorded on the trace.

1 Structured seed reads

Typed facts read by key

Never terminal

2 Response cache

Reuses an answer whose facts are unchanged

Entity-aware invalidation

3 Hybrid retrieval

The fused ranker

Seven signals

4 Escalated fallback

HyDE and a doubled candidate pool

When tier 3 is thin

Tier 1 rows join the ranking as seeds

Fused ranker

One ranking over seven signals

Each signal's score is recorded on the trace.

VectorLexicalGraphSection linksPageRankGeoTrace features

The tiers are numbered by cost. The answer cache, tier 2, is checked first, and tier 1's reads then seed the ranking.

Tier 1 is never terminal

Structured seed reads over typed facts answer precisely but sparsely, so their rows join the ranking as seeds. They are never the final answer on their own.

Entity-aware invalidation

Answer reuse keys each chat answer on the facts it cited. Once one of those facts is superseded or forgotten, the answer is no longer reused.

Escalation

When hybrid retrieval comes back thin or low-confidence, tier 4 rewrites the query with HyDE and ranks over a doubled candidate pool.

Scores on the trace

The retrieval trace records each signal's score, so a result is a weighted combination that can be inspected rather than an opaque top-k.

RANKING

Seven signals, one score. Each result explains its score on the trace.

VECTOR

Vector

Finds passages, turns, audio and images by meaning, through embeddings.

LEXICAL

Lexical

Matches keywords, so exact terms survive paraphrase.

GRAPH

Graph

Follows relationships between entities to related facts, even when their wording differs.

SECTIONS

Section links

Section embeddings and links between documents surface related sections of related documents.

RANKING

PageRank

A graph walk biased towards the query's seed entities, scored as one feature of the ranking.

GEO

Geo

Within-radius and inside-polygon filters compose with the other signals, and nearer results score higher.

TRACES

Trace features

The history of what proved useful feeds back into the ranking.

08 |SUBSTRATE AND TENANCY

One instance, one transaction per fact. Isolation in two levels.

One SurrealDB instance

Graph, vector, document, relational and geospatial state live in one SurrealDB instance. Agent Memory is the stateless application tier on top of it.

One transaction per fact

Each fact, its edges and its history are written in one transaction, so a partial write never lands. A document's chunks become visible together once every batch has landed.

Two isolation levels

Isolation comes at two levels: the Context and, within it, Scope.

Contexts

A Context has its own namespace and database, and no API reads across Contexts.

Scope

Scopes are hierarchical partitions within a Context. Access comes from per-verb grants on each principal, and everything not granted is denied.

Grants only narrow

Principals hold per-verb grants, and a key can only narrow them, never widen them.

Read the product overview

THE PLATFORM

Everything an application and its agents know. Five surfaces, one engine.

Database

Document, graph, vector, time-series and relational in one engine.

Five data models as dotted tiles: documents, graph, vector, time-series and relational

Agent Memory

What an agent learns, with its source and its time, in the same engine.

A timeline of remembered facts, each with its source

Cloud

Managed clusters in the regions you choose, scaled on demand.

Clusters in three regions on a world map, each running or scaling

Studio

Query, explore and design the schema from the browser.

MCP

Every model that speaks MCP reaches the database and the memory directly.

Three models connected through MCP to the database and Agent Memory

IN PRODUCTION

Trusted at scale. Samsung, Nvidia, Verizon, Tencent, and Walmart run on SurrealDB.

14,000+

Developers building on SurrealDB Cloud

4M+

Developers building on SurrealDB worldwide

FROM THE TEAMS

SurrealDB gives us a foundation where we can unify semantic search, knowledge graphs, and AI-driven decision making without stitching together multiple systems. Collapsing responsibility into SurrealDB has become our default engineering posture.

Justin Foley

VP of Engineering, Later

GET STARTED

Build with Agent Memory. Create a context in Studio, then use it through the REST API, the Python and TypeScript SDKs or the MCP tools.

Start in Studio Read the documentation

Agent Memory, under the hood

The six parts of an agentic system. One decides what the model knows.

Conversations become typed facts. Reconciled in code, so the outcome is repeatable.

Episodic

Identity

Knowledge

Context

Instructions

Uncertainty

Reconciled before it is stored. Four rules shape the outcome.

Decided in code

Contradictions stay visible

Confidence is respected

Matched by name

One graph for conversations and documents. Cited back to the source passage.

Three clocks. A changed fact is closed, never overwritten.

System time

Known time

Valid time

Supersession, not overwrite

Forget and purge

Visible to the next read

Every answer walks back to its source. Its traces are stored as data.

A source on every fact

Three kinds of trace

Kept in the tenant's database

An audit-event stream

Four tiers, one trace. Seven signals, one ranking.

Tier 1 is never terminal

Entity-aware invalidation

Escalation

Scores on the trace

Seven signals, one score. Each result explains its score on the trace.

Vector

Lexical

Graph

Section links

PageRank

Geo

Trace features

One instance, one transaction per fact. Isolation in two levels.

One SurrealDB instance

One transaction per fact

Two isolation levels

Contexts

Scope

Grants only narrow

Everything an application and its agents know. Five surfaces, one engine.

Trusted at scale. Samsung, Nvidia, Verizon, Tencent, and Walmart run on SurrealDB.

Build with Agent Memory. Create a context in Studio, then use it through the REST API, the Python and TypeScript SDKs or the MCP tools.

Agent Memory,
under the hood