SurrealDB Agent Memory

One memory for your agents and your people. Shared where it should be, private where it must be.

Documents, conversations and agent sessions become cited facts in one knowledge graph. Every agent recalls what the organisation already knows, and every read stays inside the access you grant.

The problem

Every agent starts from zero. And what it learns, it keeps to itself.

The knowledge your agents need is already written down, or was learnt yesterday by another agent. It is just not anywhere they can reach, trust and share safely.

Agents forget between sessions

A support agent asks the customer the same questions again. A coding agent reads the same 30 files to rediscover the bug a teammate fixed on Monday. You pay again in tokens and in time.

Knowledge is scattered and goes stale

The answer is split across a wiki, a policy PDF, a ticket and a chat thread. They disagree, and a vector store returns all of them with no sense of which one is current.

Shared memory without access control is a risk

Put every agent on one memory and a customer's details can reach another customer's chat. Keep them apart and nothing is shared at all.

Per-agent memoryLearnt automatically, but private to one agent, one laptop or one session.

Wikis and prompt filesShared, but written by hand and quick to go stale.

SurrealDB Agent MemoryLearnt automatically, shared by scope, kept current and cited.

The solution

One database for what your organisation knows. Remembered, reconciled and recalled.

Agent Memory turns documents and agent sessions into typed entities, relations and facts. Each fact keeps its source, its corrections and its history.

Remember

Policies, specs, tickets and conversations become entities, relations and facts. Each one cites the passage or session it came from.

Reconcile

A newer fact supersedes the old one instead of sitting beside it. When two sources disagree, the conflict is flagged for review, not guessed.

Recall

Vector, keyword and graph search are fused into one ranking. Answers come back with citations, and every read records a trace.

Isolate

Scopes partition the data, grants decide who can read or write each scope, and a lens narrows a read further. Nothing leaks past a grant.

Fact · Acme refund window

1 March to 1 September · superseded

30 days from delivery

Source: refund-policy.pdf, version 3

From 1 September · current

14 days from delivery

Source: refund-policy.pdf, version 4. The old fact is kept, so you can ask what was true on any date.

Solution architecture

Knowledge and agent sessions in. Cited, permission-aware answers out.

One Agent Memory Context sits between your sources and everything that asks. People and agents use the same memory, and agents write back what they learn.

Authoritative knowledge

Policies and handbooks

Product docs and specs

Tickets and postmortems

PDFs, slides and images

Experience

Agent sessions and chat turns

Facts your apps remember

Ingest
and extract

Agent Memory Context

Knowledge graphentities, relations

Hybrid searchvector, keyword, graph

Facts with historywhat was true, and when

Scopes and grantswho may read what

Tracesevery answer cites its sources

Built on SurrealDB · one transaction per fact

MCP
or REST

Where people and agents ask

Customer support agents

Personal assistants

Multi-agent workflows

Claude Code, Cursor and other MCP clients

Your own apps, through the REST API

One database underneathGraph, vector, document and relational data in SurrealDB. One system to secure and audit, instead of a vector store, a graph and a cache.

How data gets inUpload through the API, the CLI or MCP, and re-ingest a document when it changes. Built-in connectors are not part of the current release.

Scope partitions data, a Context partitions worldsUse scopes inside one product. Use a separate Context when nothing from A may ever appear in B.

Where it fits

One memory model. Many kinds of agent.

Customer support agent

Policies and the product catalogue as documents, plus memory per customer from every past conversation. Each customer's memory stays isolated.

org/acme/customer/c-118

Personal assistant

Preferences, projects and instructions that carry across sessions, and can be forgotten when the user's situation changes.

org/acme/user/alice

Multi-agent workflows

Agents on one task read and write a shared project scope, while each keeps its own private notes. Read-only workers get read-only keys.

org/acme/project/q3-research

Coding agents

Conventions, decisions and fixes learnt in one engineer's session reach the next engineer's agent, next to the team's specs and runbooks.

org/acme/team/eng

Isolation

Same memory, same question. Each asker sees only what they are granted.

Every record carries a scope, a path such as org/acme/team/eng. Every caller acts as a principal whose grants name the scopes it may read. A lens narrows one read inside that grant. It can never widen it.

Asker

Lens

How to read the map

Circles are scopes. A circle inside another is a narrower path, such as team/eng inside org/acme.
Tint is the grant. org/acme tints only the outer ring. org/acme/team/eng/* tints that circle and all inside it.
Dashed ring is the lens. It keeps its own circle and the rings around it, and dims the rest. It never reaches past the tint.
Dots are records. The numbers match the list below. A filled dot is returned.

Alice · Acme engineer

Grants · memory:read

The request

Records in the Context returned

Struck-through records are shown here only to make the boundary visible. The API never returns them: a read outside a grant comes back empty, not refused, so nothing about hidden records leaks.

Scope

Where a fact lives

Set at write time, on each fact, session and document. Scopes are assigned at ingest to match who may read the source today. Agent Memory does not read source permissions itself.

Grant

Who may do what, where

Per verb: read, write or manage. org/acme covers that node only, and org/acme/* covers the whole subtree. A key can carry less than its principal, never more.

Delegation

Acting on behalf of someone

An agent can read with a person's access. The effective access is the intersection of both principals' grants, so delegation narrows and never widens.

In code

Write with a scope. Read with a lens.

Four REST calls cover the whole loop. Each request authenticates with a Context API key, and the key's grants decide what it can touch.

1 · Upload a document

Parsed, chunked, extracted and embedded in the background. The scope is set here, at ingest.

curl -X POST "$AGENT_MEMORY_ENDPOINT/api/v1/acme/documents" \
  -H "Authorization: Bearer $AGENT_MEMORY_API_KEY" \
  -F "file=@refund-policy.pdf" \
  -F 'metadata={
    "title": "Refund policy",
    "scopes": [["org/acme"]],
    "labels": ["dept=finance"]
  }'

2 · Remember what an agent learnt

Extracted into entities and facts, reconciled against what is already known, and visible on the next read.

curl -X POST "$AGENT_MEMORY_ENDPOINT/api/v1/acme/facts" \
  -H "Authorization: Bearer $AGENT_MEMORY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "The e2e suite needs make seed before it runs.",
    "infer": "full",
    "scopes": [["org/acme/team/eng"]]
  }'

3 · Recall with a lens

Hybrid search over facts and passages, narrowed to the team's region. Org-wide facts at org/acme still match.

curl -X POST "$AGENT_MEMORY_ENDPOINT/api/v1/acme/query" \
  -H "Authorization: Bearer $AGENT_MEMORY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "How do I run the e2e suite?",
    "k": 5,
    "lens": [["org/acme/team/eng"]]
  }'

# Returns ranked hits with their sources, the retrieval
# tier, queryMs and a trace you can audit later.

4 · Act on behalf of a person

A shared agent reads with the asking user's access, and gets a block ready for its system prompt.

curl -X POST "$AGENT_MEMORY_ENDPOINT/api/v1/acme/context" \
  -H "Authorization: Bearer $SUPPORT_AGENT_KEY" \
  -H "X-Spectron-On-Behalf-Of: $ALICE_PRINCIPAL_ID" \
  -H "Content-Type: application/json" \
  -d '{ "query": "What is our refund window?", "k": 5 }'

# Effective access = agent's grants ∩ Alice's grants
{ "context": "…", "tier": "hybrid", "queryMs": 42 }

Nested arrays matter: [["a", "b"]] means a and b, while ["a", "b"] means a or b. The same Context also serves MCP at /mcp on the same host, so Claude Code, Cursor and other MCP clients read and write the same memory.

Trust

Permission-aware and cited. By design.

Scopes mirror your organisation

Paths for org, team, project, customer or user. Each record is tagged when it is written.

Grants per action

A key can read, write or manage only the scopes it is granted. Everything else is denied, and empty scope sees nothing.

Agents act for a person

Delegation lets a shared agent read with one user's access. It can narrow access, never widen it.

Every answer is traced

Writes, searches and answers record a trace linked to the facts they used, in your own database.

History you can audit

Superseded facts keep their dates. Forget retires a fact, purge erases it, and a scoped forget erases a whole subtree.

Hard isolation when you need it

Each Context is its own SurrealDB namespace and database, with its own keys. Nothing crosses that boundary.

Bring us one agent and its knowledge. We will help you plan a pilot.

Tell us what your agents need to remember, who should see it, and where it lives today. We will work out the scopes, the grants and the first use case with you.

One memory for your agents and your people. Shared where it should be, private where it must be.

Every agent starts from zero. And what it learns, it keeps to itself.

Agents forget between sessions

Knowledge is scattered and goes stale

Shared memory without access control is a risk

One database for what your organisation knows. Remembered, reconciled and recalled.

Remember

Reconcile

Recall

Isolate

Knowledge and agent sessions in. Cited, permission-aware answers out.

One memory model. Many kinds of agent.

Customer support agent

Personal assistant

Multi-agent workflows

Coding agents

Same memory, same question. Each asker sees only what they are granted.

Alice · Acme engineer

Where a fact lives

Who may do what, where

Acting on behalf of someone

Write with a scope. Read with a lens.

1 · Upload a document

2 · Remember what an agent learnt

3 · Recall with a lens

4 · Act on behalf of a person

Permission-aware and cited. By design.

Scopes mirror your organisation

Grants per action

Agents act for a person

Every answer is traced

History you can audit

Hard isolation when you need it

Bring us one agent and its knowledge. We will help you plan a pilot.

Explore more