--- title: "SurrealDB Agent Memory use case" description: "Shared memory for every agent and every person in your organisation: cited, kept current, and isolated with scopes, grants and lenses." url: https://surrealdb.com/explore/agent-memory-use-case --- # One memory for your agents and your people. Shared where it should be, private where it must be. SurrealDB Agent Memory 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. [Contact us to discuss a pilot](https://surrealdb.com/contact) [See isolation in action](https://surrealdb.com/explore/agent-memory-use-case#isolation) 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. 01 ### 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. 02 ### 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. 03 ### 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 memory**Learnt automatically, but private to one agent, one laptop or one session. **Wikis and prompt files**Shared, but written by hand and quick to go stale. **SurrealDB Agent Memory**Learnt 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. 01 ### Remember Policies, specs, tickets and conversations become entities, relations and facts. Each one cites the passage or session it came from. 02 ### 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. 03 ### Recall Vector, keyword and graph search are fused into one ranking. Answers come back with citations, and every read records a trace. 04 ### 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 underneath**Graph, 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 in**Upload 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 worlds**Use 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. 01 ### Scopes mirror your organisation Paths for org, team, project, customer or user. Each record is tagged when it is written. 02 ### 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. 03 ### Agents act for a person Delegation lets a shared agent read with one user's access. It can narrow access, never widen it. 04 ### Every answer is traced Writes, searches and answers record a trace linked to the facts they used, in your own database. 05 ### History you can audit Superseded facts keep their dates. Forget retires a fact, purge erases it, and a scoped forget erases a whole subtree. 06 ### 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. [Contact us to discuss a pilot](https://surrealdb.com/contact) ## Explore more - [**What is agent memory?** The six categories of agent memory, what each one stores, and where it sits in an AI stack.](https://surrealdb.com/explore/what-is-agent-memory) - [**Company brain** One pricing decision is followed through ingest, per-person permissions and time.](https://surrealdb.com/explore/company-brain) - [**Credit downgrade exposure** An agent traces a counterparty downgrade three entities out and recalls the decisions behind each limit.](https://surrealdb.com/explore/use-case-credit-downgrade)