Index Agentica

Give an agent durable memory with SurrealDB Agent Memory

Connect an agent to SurrealDB Agent Memory over MCP or the Python/TypeScript SDKs: Context + Bearer key, remember/recall/forget, provenance and supersession, and what the free Sandbox actually needs.

Type
Guide
Author
Agentica Author
Published
Updated
Last verified
Difficulty
intermediate
Time
35 min

Prerequisites

What you get

SurrealDB Agent Memory is a managed memory and knowledge layer in front of SurrealDB. Conversations, documents and structured data become entities, attributes, relations, instructions and sources. Fact-bearing records keep provenance (where a fact came from) and a tri-temporal timeline. When a newer fact replaces an older one, the old value is superseded, not deleted, so you can still answer "what did we believe then?".

Each Context is an isolation boundary with its own SurrealDB namespace and database. The Context host serves:

Authentication for both is Authorization: Bearer <api-key>. Each key is bound to one Context, so MCP tools can omit context_id. There is no OAuth on this path.

SurrealDB reports a 77.2% mean score on BEAM 1M (and 57.1% strict accuracy) on the product page and launch blog. Treat that as their published figure, not an independent re-run.

Plans and signup

From the product page (2026-11-06):

PlanPriceTokens
SandboxFree, no card3 million, one-off
Lite$30/mo1 million / month
Standard$300/mo10 million / month
Plus$1,100/mo40 million / month
EnterpriseAnnualCustom; self-hosted and air-gapped listed

Tokens count every language-model and embedding call the Context makes, including background work such as consolidation.

Sandbox is free, but Context creation is a human step. You sign in to SurrealDB Studio, open organisation → Contexts, create a Context, then create an API key (sp-…, shown once). This guide does not walk a live signup. Without a Context host and key you can still wire an MCP client or SDK against the documented shapes; the offline checks below do that.

Agent Memory itself is not open source today. SurrealDB underneath is source-available under Business Source License 1.1; the client SDKs are open source (Apache-2.0 or MIT). Self-hosted and air-gapped deployment is listed on Enterprise.

Connect over MCP

The install docs show Streamable HTTP at /mcp with a Bearer header and --oauth no:

npx -y @smithery/cli@latest install-mcp \
  "https://<your-context-host>/mcp" \
  --header "Authorization: Bearer <your-api-key>" \
  --oauth no

Or configure a client by hand:

{
  "mcpServers": {
    "agent-memory": {
      "url": "https://<your-context-host>/mcp",
      "headers": {
        "Authorization": "Bearer <your-api-key>"
      }
    }
  }
}

Some product-page snippets also show an X-Spectron-Context header. The rename from the project name Spectron is still partial: env vars stay SPECTRON_* and some headers stay X-Spectron-*. The MCP install page says the Bearer key alone is enough because the key is bound to one Context.

The seven tools

From the MCP tools reference:

ToolNeedsDoes
remembermemory:writePersist text (or triples); reconciles (supersession / uncertainty). REST: POST .../facts
recallmemory:readRanked hits over facts and document passages. REST: POST .../query
contextmemory:readMarkdown block for a system prompt. REST: POST .../context
reflectmemory:read (+ write if persist)Synthesise patterns; optional persist. REST: POST .../reflect
forgetmemory:forgetSoft-delete matches from current retrieval; purge: true erases. REST: POST .../forget
uploadmemory:writeIngest a document (base64); processing is async. REST: POST .../documents
inspectmemory:readFetch entity / trace / document by ref. REST: GETs under entities, traces, documents

remember input (docs):

{
  "text": "I just got promoted to CTO.",
  "session_id": "sess_abc123",
  "scope": [["org/acme/user/alice"]],
  "labels": ["source=onboarding"],
  "infer": "full",
  "observed_at": "2026-05-12T10:00:00Z"
}

infer is full (default, LLM extraction), triples (caller-supplied, no LLM), preview (dry run) or none (literal store).

recall takes query, optional k (default 10, max 50), mode (hybrid | vector | bm25 | graph), and a read lens. Writes use scope / scopes; an unknown field such as sending scope on a read is ignored without error, so a mis-named read can search everything the key can see.

Tool failures return isError: true with HTTP 200 on the transport. JSON-RPC error is for protocol faults only.

Connect with an SDK

pip install surrealdb-memory==1.0.0b1
# or: pip install 'surrealdb[memory]'
npm i @surrealdb/memory@1.0.0-alpha.11

Python (surrealdb-memory 1.0.0b1), against a fake transport so nothing leaves the box:

from surrealdb_memory import Memory

memory = Memory(
    context="your-context-id",
    endpoint="https://<your-context-host>",
    api_key="sp-...",
)
memory.remember(
    "I was just promoted to CTO.",
    infer="full",
    scopes="org/acme/user/alice",
    labels=["source=onboarding"],
)
hits = memory.recall("What is Alice's role?", k=10, mode="hybrid", lens="org/acme/user/alice")
memory.forget("anything about my previous role")          # soft
memory.forget("erase permanently", purge=True)            # permanent

Offline, with the real client and a stub transport, those calls became:

So a plain scope string is normalised to the DNF form the wire docs describe. The transport sends Authorization: Bearer … from the client’s API key.

TypeScript (@surrealdb/memory 1.0.0-alpha.11) mirrors the same verbs (remember, recall, forget, reflect, chat, …) and ships OpenAPI-generated path types under /api/v1/{context_id}/....

Hosted quickstart env vars still use the Spectron names:

export SPECTRON_URL="https://<your-context-host>"
export SPECTRON_CONTEXT_ID="<your-context-id>"
export SPECTRON_API_KEY="sp-..."

Register scope paths before scoped writes (agent-memory scopes create … or the Cloud admin API).

Provenance, supersession and forget

What was and wasn’t tested

Tested offline on 2026-11-06:

Not tested:

Related reading

For how this sits next to Mem0, LangMem, Zep and others, see Memory layers for AI agents. For wiring any remote MCP server into a harness, see Connect an agent to a remote MCP server.

Directory entries in this guide

Related

Sources

Machine-readable