AI agents have a memory problem: most of what they know lives either in the current context window, in local siloed memory solutions, or in an external retrieval system.
That works up to a point. But once an agent needs to remember information across sessions, distinguish current facts from old ones, understand relationships between entities, or explain where a fact came from, storing conversation history or embedding chunks into a vector database stops being enough.
Today, we’re introducing SurrealDB Agent Memory, a memory and knowledge layer for AI agents built on SurrealDB. It takes conversations, documents, and structured data and turns them into persistent, queryable memory: entities, attributes, relationships, instructions, source information, embeddings, and retrieval traces stored together in SurrealDB.
The goal is fairly simple: give agents persistent state that can change over time without losing track of what changed, when it changed, or why.
How we benchmark Agent Memory
Memory benchmarks are easy to quote and hard to compare. Scores can vary significantly depending on the answering model, judge model, number of retrieved results, and which settings are enabled. So we’ve published our results, methodology, and configuration on a dedicated benchmarks page.
On BEAM 1M, a long-term memory benchmark based on conversations of around one million tokens, Agent Memory scores:
77.2% mean score
57.1% strict accuracy, where an answer only counts if it is fully correct
82.9% of questions scoring at least 0.5
We report strict accuracy alongside the mean because partially correct answers can raise the average. Strict accuracy shows how often the system produced a fully correct answer, which is an important distinction for production use.
We also document where our run differs from the reference setup. The 77.2% result uses Agent Memory’s own retrieval and prompting pipeline rather than the paper’s top-5 baseline, enables ten retrieval and chat settings that are not on by default, and uses a different judge model from the authors’ reference implementation. Our weakest category is event ordering, at 49.7%. Temporal reasoning remains an area we are actively working to improve.
Our reporting follows four rules:
- 1.
Name the models. Every result identifies both the answering and grading models.
- 2.
Show strict accuracy alongside the mean. We don’t report only the more favorable aggregate.
- 3.
Avoid ranking claims. Different models, judges, retrieval settings, and configurations can make leaderboards compare setups rather than systems.
- 4.
Document every deviation. Any departure from the benchmark’s reference methodology is listed explicitly.
Where other vendors publish per-question results, we calculate strict accuracy from those files using the same method. The benchmarks page also documents eleven practices that can materially affect scores and shows which apply to each published result, including ours.
We’ll publish our per-question results and run configuration so the numbers can be independently checked. Results for BEAM 10M and LoCoMo are available on the same page.
From retrieval to structured, evolving memory
The simplest implementation of agent memory is to store previous messages, generate embeddings, and retrieve the most similar chunks when the agent needs context. That works for basic recall, but it becomes harder to manage as information changes over time.
If a user first says: "I work at Pied Piper as VP of Engineering*" and later says: "I’ve moved to Hooli as CTO"*, both statements may be relevant to the question “Where does this person work?”. Similarity alone does not tell the system which one is current. SurrealDB Agent Memory treats this as a state-management problem, not just a retrieval problem.
When new information arrives, it is first extracted into structured memory such as entities, attributes, relationships, instructions, and uncertainties. That structured information is then reconciled against what the system already knows.
Reconciliation determines whether the new information should be added, update an existing fact, supersede an older one, or remain uncertain because sources disagree. So instead of storing a growing collection of disconnected chunks, Agent Memory maintains an evolving model of what is currently believed, what was true previously, and how that state changed over time.
This makes it possible to answer both: "Gilfoyle’s role now is CTO" and "Gilfoyle's role last year was VP of Engineering". The older fact is not deleted. It remains part of the historical record while the newer fact becomes current.
Every fact keeps its source
A useful memory system should be able to answer more than “What do I know?”. It should also be able to answer:"Where did I learn this?". Fact-bearing records in Agent Memory carry structured provenance. This can include the originating conversation or document, the location of the source text, the source type, its trust level, and lineage when a fact was derived from other information. This means an application can trace a stored fact back to the conversation turn or document passage that produced it.
That is useful when debugging an agent, but it also changes how applications can present answers. Instead of simply generating a response and hoping the retrieved context was correct, applications can expose the underlying sources that contributed to it. Agent Memory also stores retrieval, reconciliation, and response traces, making it possible to inspect which records were considered and how a stored belief changed.
Time is part of the data model
Facts often have more than one relevant timestamp. Something may have been true in January, mentioned in March, and stored by the database in April.
Agent Memory uses a tri-temporal model to distinguish different notions of time, including when information was valid in the real world, when the system knew about it, and the database's own transaction history.
This lets applications ask questions such as:
What is true now?
What did we believe last month?
What was true at a specific point in time?
When was this information corrected?
Without temporal modelling, older and newer facts tend to become competing chunks in the retrieval layer. With temporal state, the database itself can distinguish current information from historical information.
Documents and conversations in one graph
Agents typically need two types of information: authoritative knowledge (policies, documentation, repositories, product data, manuals, and other curated sources) and experiential knowledge (what users said, decisions made during previous sessions, preferences, observations, and things the agent itself has learned). Agent Memory stores both in one SurrealDB substrate rather than maintaining separate databases for documents, conversations, vectors, and relationships.
Because SurrealDB supports multiple data models in the same database, documents, entities, relations, embeddings, and traces can be stored and queried together under the same transactional system. That means a retrieval query can combine several different signals rather than requiring application code to join results from separate systems, improving accuracy, retrieval latency, and LLM token usage.
Retrieval is hybrid
Not every memory question is a semantic-search problem. Finding a paraphrased passage benefits from vector search. Finding an exact product ID benefits from full-text search. Finding something related to a particular customer, person, or project can benefit from graph relationships.
Agent Memory supports hybrid retrieval across these different signals. Vector similarity, full-text search, graph structure, and other ranking inputs can contribute to the same retrieval process. It also uses a tiered read path.
Simple questions can resolve directly against structured memory. Previously generated responses can sometimes be reused when the facts they depended on remain current. More complex questions can escalate to broader hybrid retrieval and model synthesis.
This is useful because asking “What timezone does this user prefer?” should not necessarily require the same retrieval and inference path as “Summarise everything relevant to this customer's current project.”
Memory has a lifecycle
Not everything an agent learns should remain equally important forever. Agent Memory separates three different operations:
Supersession handles information that has been replaced. The previous fact remains in history but is no longer current.
Decay reduces the importance of information as it becomes less relevant, while allowing frequently useful memories to be reinforced.
Forget removes information from the agent's active working set when explicit removal is required.
Keeping these concepts separate prevents a common problem where “old,” “wrong,” and “deleted” all end up meaning the same thing. They are not the same thing, and applications often need different behaviour for each.
Scoping memory to the right user, team, or agent
Memory is only useful if the agent retrieves the right information for the current situation. SurrealDB Agent Memory uses scopes to partition memory within a Context. A scope is a hierarchical path such as: org/piedpiper/user/gilfoyle or org/piedpiper/project/thebox. This lets applications decide which memories belong to an organisation, user, team, project, or another boundary that makes sense for the product.
For example, a customer-support agent might store company-wide policies at: org/piedpiper while Gilfoyle's preferences and previous interactions live under: org/piedpiper/user/hooli
When the agent is working with Gilfoyle, it can retrieve both the organisation-level knowledge and Gilfoyle's own memory without exposing another user's information. Session scopes are also propagated to the records created during that session, so new memories remain attributed to the right part of the application.
Scopes are different from permissions. Scope determines where a memory belongs; grants determine who is allowed to read or write it. Together, they provide a practical way to build multi-user and multi-tenant agents without maintaining a separate memory database for every user.
For stronger isolation, Agent Memory uses Contexts. A useful rule is: scopes partition data within the same application; Contexts separate entirely different memory environments.
Built on SurrealDB
Agent Memory runs as an application layer in front of SurrealDB. A Context provides the isolation boundary for a memory environment, with its own SurrealDB namespace and database. Within a Context, conversations, documents, entities, relationships, embeddings, traces, and other memory state live together.
Contexts are managed through SurrealDB Studio, where developers can work with conversations, inspect known entities, upload documents, explore the knowledge graph, and see what the system retrieved and learned during individual interactions.
Applications can integrate through the REST API, MCP, Python and TypeScript SDKs, or adapters for agent frameworks including LangChain, OpenAI Agents, and Vercel AI SDK.
A basic workflow looks like this:
Remember: Send a conversation turn, document, or fact to Agent Memory.
Extract: Convert unstructured input into entities, attributes, relationships, instructions, and other structured state.
Reconcile: Compare that information with existing memory and decide what is new, what changed, and where uncertainty exists.
Store: Write the resulting state, provenance, embeddings, relationships, and traces into SurrealDB.
Recall: Query memory through structured lookups or hybrid retrieval, scoped to the relevant user, agent, organisation, or application.
That creates a loop in which the agent's state can continue evolving between conversations instead of being reconstructed from scratch every time.
Memory as persistent application state
We think agent memory becomes much easier to reason about once it is treated less like a cache around an LLM and more like persistent application state. Agents need to know what is currently true, what used to be true, where information came from, which sources should be trusted, and how different pieces of information relate to one another. Those are fundamentally data problems.
SurrealDB Agent Memory brings those capabilities together in one layer: structured memory, document knowledge, graph relationships, temporal history, provenance, reconciliation, and retrieval, backed by SurrealDB.
The result is agents that do not simply retrieve previous text, but can can maintain a persistance, queryable shared memory layer of what it has learned - and update that layer as the world changes. Get started with Agent Memory or explore the documentation.
