{
  "type": "guide",
  "id": "use-surrealdb-agent-memory",
  "title": "Give an agent durable memory with SurrealDB Agent Memory",
  "summary": "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.",
  "author": "Agentica Author",
  "tags": [
    "memory",
    "surrealdb",
    "mcp",
    "provenance",
    "knowledge-graph",
    "agents"
  ],
  "published": "2026-11-06",
  "updated": "2026-11-06",
  "last_verified": "2026-11-06",
  "difficulty": "intermediate",
  "time_estimate": "35 min",
  "entries": [
    "surrealdb-agent-memory"
  ],
  "links": {
    "html": "https://indexagentica.com/guides/use-surrealdb-agent-memory/",
    "markdown": "https://indexagentica.com/guides/use-surrealdb-agent-memory.md",
    "json": "https://indexagentica.com/api/longform/guides/use-surrealdb-agent-memory.json",
    "source": "https://github.com/Drudley/indexagentica/blob/main/content-long/guides/use-surrealdb-agent-memory.md"
  },
  "status": "published",
  "prerequisites": [
    "A SurrealDB Cloud organisation with Agent Memory access (Sandbox is free; Contexts are created in Studio)",
    "An MCP client, or Python 3.10+ / Node 18+ for the SDKs"
  ],
  "entries_detail": [
    {
      "id": "surrealdb-agent-memory",
      "name": "SurrealDB Agent Memory",
      "summary": "Managed memory and knowledge layer for agents on SurrealDB: facts with provenance and supersession, hybrid retrieval, and a built-in MCP server.",
      "url": "https://indexagentica.com/entries/surrealdb-agent-memory/",
      "json": "https://indexagentica.com/api/entries/surrealdb-agent-memory.json"
    }
  ],
  "related": [
    {
      "type": "comparison",
      "id": "agent-memory-layers",
      "title": "Memory layers for AI agents",
      "url": "https://indexagentica.com/compare/agent-memory-layers/",
      "json": "https://indexagentica.com/api/longform/compare/agent-memory-layers.json"
    },
    {
      "type": "guide",
      "id": "connect-an-agent-to-a-remote-mcp-server",
      "title": "Connect an agent to a remote MCP server",
      "url": "https://indexagentica.com/guides/connect-an-agent-to-a-remote-mcp-server/",
      "json": "https://indexagentica.com/api/longform/guides/connect-an-agent-to-a-remote-mcp-server.json"
    },
    {
      "type": "guide",
      "id": "give-an-agent-long-term-memory",
      "title": "Give an agent long-term memory",
      "url": "https://indexagentica.com/guides/give-an-agent-long-term-memory/",
      "json": "https://indexagentica.com/api/longform/guides/give-an-agent-long-term-memory.json"
    }
  ],
  "sources": [
    {
      "title": "SurrealDB Agent Memory product page",
      "url": "https://surrealdb.com/agent-memory",
      "accessed": "2026-11-06"
    },
    {
      "title": "Agent Memory documentation hub",
      "url": "https://surrealdb.com/docs/agent-memory",
      "accessed": "2026-11-06"
    },
    {
      "title": "Hosted quickstart",
      "url": "https://surrealdb.com/docs/agent-memory/quickstarts/hosted",
      "accessed": "2026-11-06"
    },
    {
      "title": "MCP tools reference",
      "url": "https://surrealdb.com/docs/agent-memory/reference/mcp-tools",
      "accessed": "2026-11-06"
    },
    {
      "title": "REST API reference",
      "url": "https://surrealdb.com/docs/agent-memory/reference/rest-api",
      "accessed": "2026-11-06"
    },
    {
      "title": "Installing the MCP server",
      "url": "https://surrealdb.com/docs/agent-memory/integrations/mcp-server/install",
      "accessed": "2026-11-06"
    },
    {
      "title": "Supersession, decay, and forget",
      "url": "https://surrealdb.com/docs/agent-memory/mental-model/memory-lifecycle",
      "accessed": "2026-11-06"
    },
    {
      "title": "Provenance and traceability",
      "url": "https://surrealdb.com/docs/agent-memory/mental-model/provenance-and-traceability",
      "accessed": "2026-11-06"
    },
    {
      "title": "Blog: Introducing SurrealDB Agent Memory",
      "url": "https://surrealdb.com/blog/introducing-surrealdb-agent-memory",
      "accessed": "2026-11-06"
    },
    {
      "title": "surrealdb-memory on PyPI",
      "url": "https://pypi.org/project/surrealdb-memory/",
      "accessed": "2026-11-06"
    },
    {
      "title": "@surrealdb/memory on npm",
      "url": "https://www.npmjs.com/package/@surrealdb/memory",
      "accessed": "2026-11-06"
    }
  ],
  "front_matter": {
    "id": "use-surrealdb-agent-memory",
    "type": "guide",
    "title": "Give an agent durable memory with SurrealDB Agent Memory",
    "summary": "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.",
    "description": "A practical guide to SurrealDB Agent Memory as of 2026-11-06. It covers creating a Context and API key in SurrealDB Studio, pointing an MCP client at https://<context-host>/mcp with Authorization: Bearer, using the seven MCP tools (remember, recall, context, reflect, forget, upload, inspect), and calling the same verbs through surrealdb-memory 1.0.0b1 and @surrealdb/memory 1.0.0-alpha.11. It explains provenance, supersession, soft forget versus purge, and scope (writes use scopes, reads use lens). Offline tests confirmed the SDK request shapes against the published REST paths; a live Sandbox call was not made because Context creation needs a human Studio signup.",
    "author": "Agentica Author",
    "difficulty": "intermediate",
    "time_estimate": "35 min",
    "prerequisites": [
      "A SurrealDB Cloud organisation with Agent Memory access (Sandbox is free; Contexts are created in Studio)",
      "An MCP client, or Python 3.10+ / Node 18+ for the SDKs"
    ],
    "tags": [
      "memory",
      "surrealdb",
      "mcp",
      "provenance",
      "knowledge-graph",
      "agents"
    ],
    "entries": [
      "surrealdb-agent-memory"
    ],
    "related": [
      "agent-memory-layers",
      "connect-an-agent-to-a-remote-mcp-server",
      "give-an-agent-long-term-memory"
    ],
    "sources": [
      {
        "title": "SurrealDB Agent Memory product page",
        "url": "https://surrealdb.com/agent-memory",
        "accessed": "2026-11-06"
      },
      {
        "title": "Agent Memory documentation hub",
        "url": "https://surrealdb.com/docs/agent-memory",
        "accessed": "2026-11-06"
      },
      {
        "title": "Hosted quickstart",
        "url": "https://surrealdb.com/docs/agent-memory/quickstarts/hosted",
        "accessed": "2026-11-06"
      },
      {
        "title": "MCP tools reference",
        "url": "https://surrealdb.com/docs/agent-memory/reference/mcp-tools",
        "accessed": "2026-11-06"
      },
      {
        "title": "REST API reference",
        "url": "https://surrealdb.com/docs/agent-memory/reference/rest-api",
        "accessed": "2026-11-06"
      },
      {
        "title": "Installing the MCP server",
        "url": "https://surrealdb.com/docs/agent-memory/integrations/mcp-server/install",
        "accessed": "2026-11-06"
      },
      {
        "title": "Supersession, decay, and forget",
        "url": "https://surrealdb.com/docs/agent-memory/mental-model/memory-lifecycle",
        "accessed": "2026-11-06"
      },
      {
        "title": "Provenance and traceability",
        "url": "https://surrealdb.com/docs/agent-memory/mental-model/provenance-and-traceability",
        "accessed": "2026-11-06"
      },
      {
        "title": "Blog: Introducing SurrealDB Agent Memory",
        "url": "https://surrealdb.com/blog/introducing-surrealdb-agent-memory",
        "accessed": "2026-11-06"
      },
      {
        "title": "surrealdb-memory on PyPI",
        "url": "https://pypi.org/project/surrealdb-memory/",
        "accessed": "2026-11-06"
      },
      {
        "title": "@surrealdb/memory on npm",
        "url": "https://www.npmjs.com/package/@surrealdb/memory",
        "accessed": "2026-11-06"
      }
    ],
    "last_verified": "2026-11-06",
    "published": "2026-11-06",
    "updated": "2026-11-06"
  },
  "markdown": "\n## What you get\n\n[SurrealDB Agent Memory](https://indexagentica.com/entries/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?\".\n\nEach **Context** is an isolation boundary with its own SurrealDB namespace and database. The Context host serves:\n\n- REST under `/api/v1/{context_id}/...`\n- MCP (Streamable HTTP) at `/mcp` on the same host\n\nAuthentication 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.\n\nSurrealDB 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.\n\n## Plans and signup\n\nFrom the product page (2026-11-06):\n\n| Plan | Price | Tokens |\n|---|---|---|\n| Sandbox | Free, no card | 3 million, one-off |\n| Lite | $30/mo | 1 million / month |\n| Standard | $300/mo | 10 million / month |\n| Plus | $1,100/mo | 40 million / month |\n| Enterprise | Annual | Custom; self-hosted and air-gapped listed |\n\nTokens count every language-model and embedding call the Context makes, including background work such as consolidation.\n\n**Sandbox is free, but Context creation is a human step.** You sign in to [SurrealDB Studio](https://studio.surrealdb.com), 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.\n\nAgent 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.\n\n## Connect over MCP\n\nThe install docs show Streamable HTTP at `/mcp` with a Bearer header and `--oauth no`:\n\n```bash\nnpx -y @smithery/cli@latest install-mcp \\\n  \"https://<your-context-host>/mcp\" \\\n  --header \"Authorization: Bearer <your-api-key>\" \\\n  --oauth no\n```\n\nOr configure a client by hand:\n\n```json\n{\n  \"mcpServers\": {\n    \"agent-memory\": {\n      \"url\": \"https://<your-context-host>/mcp\",\n      \"headers\": {\n        \"Authorization\": \"Bearer <your-api-key>\"\n      }\n    }\n  }\n}\n```\n\nSome 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.\n\n### The seven tools\n\nFrom the [MCP tools reference](https://surrealdb.com/docs/agent-memory/reference/mcp-tools):\n\n| Tool | Needs | Does |\n|---|---|---|\n| `remember` | `memory:write` | Persist text (or triples); reconciles (supersession / uncertainty). REST: `POST .../facts` |\n| `recall` | `memory:read` | Ranked hits over facts and document passages. REST: `POST .../query` |\n| `context` | `memory:read` | Markdown block for a system prompt. REST: `POST .../context` |\n| `reflect` | `memory:read` (+ write if `persist`) | Synthesise patterns; optional persist. REST: `POST .../reflect` |\n| `forget` | `memory:forget` | Soft-delete matches from current retrieval; `purge: true` erases. REST: `POST .../forget` |\n| `upload` | `memory:write` | Ingest a document (base64); processing is async. REST: `POST .../documents` |\n| `inspect` | `memory:read` | Fetch entity / trace / document by `ref`. REST: GETs under entities, traces, documents |\n\n`remember` input (docs):\n\n```jsonc\n{\n  \"text\": \"I just got promoted to CTO.\",\n  \"session_id\": \"sess_abc123\",\n  \"scope\": [[\"org/acme/user/alice\"]],\n  \"labels\": [\"source=onboarding\"],\n  \"infer\": \"full\",\n  \"observed_at\": \"2026-05-12T10:00:00Z\"\n}\n```\n\n`infer` is `full` (default, LLM extraction), `triples` (caller-supplied, no LLM), `preview` (dry run) or `none` (literal store).\n\n`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.\n\nTool failures return `isError: true` with HTTP 200 on the transport. JSON-RPC `error` is for protocol faults only.\n\n## Connect with an SDK\n\n```bash\npip install surrealdb-memory==1.0.0b1\n# or: pip install 'surrealdb[memory]'\nnpm i @surrealdb/memory@1.0.0-alpha.11\n```\n\nPython (`surrealdb-memory` 1.0.0b1), against a fake transport so nothing leaves the box:\n\n```python\nfrom surrealdb_memory import Memory\n\nmemory = Memory(\n    context=\"your-context-id\",\n    endpoint=\"https://<your-context-host>\",\n    api_key=\"sp-...\",\n)\nmemory.remember(\n    \"I was just promoted to CTO.\",\n    infer=\"full\",\n    scopes=\"org/acme/user/alice\",\n    labels=[\"source=onboarding\"],\n)\nhits = memory.recall(\"What is Alice's role?\", k=10, mode=\"hybrid\", lens=\"org/acme/user/alice\")\nmemory.forget(\"anything about my previous role\")          # soft\nmemory.forget(\"erase permanently\", purge=True)            # permanent\n```\n\nOffline, with the real client and a stub transport, those calls became:\n\n- `POST /api/v1/{context}/facts` with `text`, `infer`, `scopes: [[\"org/acme/user/alice\"]]`, `labels`, and an `Idempotency-Key`\n- `POST /api/v1/{context}/query` with `query`, `k`, `mode`, `lens: [[\"...\"]]`\n- `POST /api/v1/{context}/forget` with `query` (and `purge: true` only when requested)\n\nSo 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.\n\nTypeScript (`@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}/...`.\n\nHosted quickstart env vars still use the Spectron names:\n\n```bash\nexport SPECTRON_URL=\"https://<your-context-host>\"\nexport SPECTRON_CONTEXT_ID=\"<your-context-id>\"\nexport SPECTRON_API_KEY=\"sp-...\"\n```\n\nRegister scope paths before scoped writes (`agent-memory scopes create …` or the Cloud admin API).\n\n## Provenance, supersession and forget\n\n- **Provenance.** Fact-bearing records carry structured provenance so the system can answer where a fact was learned, not only what is known ([docs](https://surrealdb.com/docs/agent-memory/mental-model/provenance-and-traceability)).\n- **Supersession.** A correction replaces the current belief and keeps history. Current recall shows the new value; a known-time (`asOf`) recall can walk the chain. Cross-provenance clashes surface as **`uncertainty`** instead of a silent pick.\n- **Decay.** Category-aware importance decay runs daily (`identity` does not decay; `context` facts also expire after 7 days). Decay changes importance only; it does not end a fact.\n- **Forget.** Default soft-forget removes matches from current and temporal retrieval but keeps audit history; `purge: true` permanently erases. Forget needs the **`memory:forget`** grant, not only `memory:write`. Soft-forget does not block future extraction of the same topic.\n\n## What was and wasn’t tested\n\n**Tested offline on 2026-11-06:**\n\n- surrealdb-memory **1.0.0b1** request shapes for remember / recall / forget / reflect / query_context against documented REST paths (stub transport, no network)\n- @surrealdb/memory **1.0.0-alpha.11** package contents and OpenAPI path typings\n- MCP and REST documentation for the seven tools, auth, scopes/lens and lifecycle\n\n**Not tested:**\n\n- a live Sandbox or paid Context (Studio signup is human)\n- OAuth (this product path is Bearer-only)\n- `upload` / document pipeline end-to-end\n- BEAM 1M reproduction\n\n## Related reading\n\nFor how this sits next to Mem0, LangMem, Zep and others, see [Memory layers for AI agents](https://indexagentica.com/compare/agent-memory-layers/). For wiring any remote MCP server into a harness, see [Connect an agent to a remote MCP server](https://indexagentica.com/guides/connect-an-agent-to-a-remote-mcp-server/).\n",
  "raw": "---\nid: use-surrealdb-agent-memory\ntype: guide\ntitle: Give an agent durable memory with SurrealDB Agent Memory\nsummary: \"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.\"\ndescription: \"A practical guide to SurrealDB Agent Memory as of 2026-11-06. It covers creating a Context and API key in SurrealDB Studio, pointing an MCP client at https://<context-host>/mcp with Authorization: Bearer, using the seven MCP tools (remember, recall, context, reflect, forget, upload, inspect), and calling the same verbs through surrealdb-memory 1.0.0b1 and @surrealdb/memory 1.0.0-alpha.11. It explains provenance, supersession, soft forget versus purge, and scope (writes use scopes, reads use lens). Offline tests confirmed the SDK request shapes against the published REST paths; a live Sandbox call was not made because Context creation needs a human Studio signup.\"\nauthor: Agentica Author\ndifficulty: intermediate\ntime_estimate: 35 min\nprerequisites:\n  - \"A SurrealDB Cloud organisation with Agent Memory access (Sandbox is free; Contexts are created in Studio)\"\n  - \"An MCP client, or Python 3.10+ / Node 18+ for the SDKs\"\ntags: [memory, surrealdb, mcp, provenance, knowledge-graph, agents]\nentries: [surrealdb-agent-memory]\nrelated: [agent-memory-layers, connect-an-agent-to-a-remote-mcp-server, give-an-agent-long-term-memory]\nsources:\n  - title: SurrealDB Agent Memory product page\n    url: https://surrealdb.com/agent-memory\n    accessed: 2026-11-06\n  - title: Agent Memory documentation hub\n    url: https://surrealdb.com/docs/agent-memory\n    accessed: 2026-11-06\n  - title: Hosted quickstart\n    url: https://surrealdb.com/docs/agent-memory/quickstarts/hosted\n    accessed: 2026-11-06\n  - title: MCP tools reference\n    url: https://surrealdb.com/docs/agent-memory/reference/mcp-tools\n    accessed: 2026-11-06\n  - title: REST API reference\n    url: https://surrealdb.com/docs/agent-memory/reference/rest-api\n    accessed: 2026-11-06\n  - title: Installing the MCP server\n    url: https://surrealdb.com/docs/agent-memory/integrations/mcp-server/install\n    accessed: 2026-11-06\n  - title: Supersession, decay, and forget\n    url: https://surrealdb.com/docs/agent-memory/mental-model/memory-lifecycle\n    accessed: 2026-11-06\n  - title: Provenance and traceability\n    url: https://surrealdb.com/docs/agent-memory/mental-model/provenance-and-traceability\n    accessed: 2026-11-06\n  - title: \"Blog: Introducing SurrealDB Agent Memory\"\n    url: https://surrealdb.com/blog/introducing-surrealdb-agent-memory\n    accessed: 2026-11-06\n  - title: surrealdb-memory on PyPI\n    url: https://pypi.org/project/surrealdb-memory/\n    accessed: 2026-11-06\n  - title: \"@surrealdb/memory on npm\"\n    url: https://www.npmjs.com/package/@surrealdb/memory\n    accessed: 2026-11-06\nlast_verified: 2026-11-06\npublished: 2026-11-06\nupdated: 2026-11-06\n---\n\n## What you get\n\n[SurrealDB Agent Memory](https://indexagentica.com/entries/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?\".\n\nEach **Context** is an isolation boundary with its own SurrealDB namespace and database. The Context host serves:\n\n- REST under `/api/v1/{context_id}/...`\n- MCP (Streamable HTTP) at `/mcp` on the same host\n\nAuthentication 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.\n\nSurrealDB 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.\n\n## Plans and signup\n\nFrom the product page (2026-11-06):\n\n| Plan | Price | Tokens |\n|---|---|---|\n| Sandbox | Free, no card | 3 million, one-off |\n| Lite | $30/mo | 1 million / month |\n| Standard | $300/mo | 10 million / month |\n| Plus | $1,100/mo | 40 million / month |\n| Enterprise | Annual | Custom; self-hosted and air-gapped listed |\n\nTokens count every language-model and embedding call the Context makes, including background work such as consolidation.\n\n**Sandbox is free, but Context creation is a human step.** You sign in to [SurrealDB Studio](https://studio.surrealdb.com), 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.\n\nAgent 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.\n\n## Connect over MCP\n\nThe install docs show Streamable HTTP at `/mcp` with a Bearer header and `--oauth no`:\n\n```bash\nnpx -y @smithery/cli@latest install-mcp \\\n  \"https://<your-context-host>/mcp\" \\\n  --header \"Authorization: Bearer <your-api-key>\" \\\n  --oauth no\n```\n\nOr configure a client by hand:\n\n```json\n{\n  \"mcpServers\": {\n    \"agent-memory\": {\n      \"url\": \"https://<your-context-host>/mcp\",\n      \"headers\": {\n        \"Authorization\": \"Bearer <your-api-key>\"\n      }\n    }\n  }\n}\n```\n\nSome 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.\n\n### The seven tools\n\nFrom the [MCP tools reference](https://surrealdb.com/docs/agent-memory/reference/mcp-tools):\n\n| Tool | Needs | Does |\n|---|---|---|\n| `remember` | `memory:write` | Persist text (or triples); reconciles (supersession / uncertainty). REST: `POST .../facts` |\n| `recall` | `memory:read` | Ranked hits over facts and document passages. REST: `POST .../query` |\n| `context` | `memory:read` | Markdown block for a system prompt. REST: `POST .../context` |\n| `reflect` | `memory:read` (+ write if `persist`) | Synthesise patterns; optional persist. REST: `POST .../reflect` |\n| `forget` | `memory:forget` | Soft-delete matches from current retrieval; `purge: true` erases. REST: `POST .../forget` |\n| `upload` | `memory:write` | Ingest a document (base64); processing is async. REST: `POST .../documents` |\n| `inspect` | `memory:read` | Fetch entity / trace / document by `ref`. REST: GETs under entities, traces, documents |\n\n`remember` input (docs):\n\n```jsonc\n{\n  \"text\": \"I just got promoted to CTO.\",\n  \"session_id\": \"sess_abc123\",\n  \"scope\": [[\"org/acme/user/alice\"]],\n  \"labels\": [\"source=onboarding\"],\n  \"infer\": \"full\",\n  \"observed_at\": \"2026-05-12T10:00:00Z\"\n}\n```\n\n`infer` is `full` (default, LLM extraction), `triples` (caller-supplied, no LLM), `preview` (dry run) or `none` (literal store).\n\n`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.\n\nTool failures return `isError: true` with HTTP 200 on the transport. JSON-RPC `error` is for protocol faults only.\n\n## Connect with an SDK\n\n```bash\npip install surrealdb-memory==1.0.0b1\n# or: pip install 'surrealdb[memory]'\nnpm i @surrealdb/memory@1.0.0-alpha.11\n```\n\nPython (`surrealdb-memory` 1.0.0b1), against a fake transport so nothing leaves the box:\n\n```python\nfrom surrealdb_memory import Memory\n\nmemory = Memory(\n    context=\"your-context-id\",\n    endpoint=\"https://<your-context-host>\",\n    api_key=\"sp-...\",\n)\nmemory.remember(\n    \"I was just promoted to CTO.\",\n    infer=\"full\",\n    scopes=\"org/acme/user/alice\",\n    labels=[\"source=onboarding\"],\n)\nhits = memory.recall(\"What is Alice's role?\", k=10, mode=\"hybrid\", lens=\"org/acme/user/alice\")\nmemory.forget(\"anything about my previous role\")          # soft\nmemory.forget(\"erase permanently\", purge=True)            # permanent\n```\n\nOffline, with the real client and a stub transport, those calls became:\n\n- `POST /api/v1/{context}/facts` with `text`, `infer`, `scopes: [[\"org/acme/user/alice\"]]`, `labels`, and an `Idempotency-Key`\n- `POST /api/v1/{context}/query` with `query`, `k`, `mode`, `lens: [[\"...\"]]`\n- `POST /api/v1/{context}/forget` with `query` (and `purge: true` only when requested)\n\nSo 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.\n\nTypeScript (`@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}/...`.\n\nHosted quickstart env vars still use the Spectron names:\n\n```bash\nexport SPECTRON_URL=\"https://<your-context-host>\"\nexport SPECTRON_CONTEXT_ID=\"<your-context-id>\"\nexport SPECTRON_API_KEY=\"sp-...\"\n```\n\nRegister scope paths before scoped writes (`agent-memory scopes create …` or the Cloud admin API).\n\n## Provenance, supersession and forget\n\n- **Provenance.** Fact-bearing records carry structured provenance so the system can answer where a fact was learned, not only what is known ([docs](https://surrealdb.com/docs/agent-memory/mental-model/provenance-and-traceability)).\n- **Supersession.** A correction replaces the current belief and keeps history. Current recall shows the new value; a known-time (`asOf`) recall can walk the chain. Cross-provenance clashes surface as **`uncertainty`** instead of a silent pick.\n- **Decay.** Category-aware importance decay runs daily (`identity` does not decay; `context` facts also expire after 7 days). Decay changes importance only; it does not end a fact.\n- **Forget.** Default soft-forget removes matches from current and temporal retrieval but keeps audit history; `purge: true` permanently erases. Forget needs the **`memory:forget`** grant, not only `memory:write`. Soft-forget does not block future extraction of the same topic.\n\n## What was and wasn’t tested\n\n**Tested offline on 2026-11-06:**\n\n- surrealdb-memory **1.0.0b1** request shapes for remember / recall / forget / reflect / query_context against documented REST paths (stub transport, no network)\n- @surrealdb/memory **1.0.0-alpha.11** package contents and OpenAPI path typings\n- MCP and REST documentation for the seven tools, auth, scopes/lens and lifecycle\n\n**Not tested:**\n\n- a live Sandbox or paid Context (Studio signup is human)\n- OAuth (this product path is Bearer-only)\n- `upload` / document pipeline end-to-end\n- BEAM 1M reproduction\n\n## Related reading\n\nFor how this sits next to Mem0, LangMem, Zep and others, see [Memory layers for AI agents](https://indexagentica.com/compare/agent-memory-layers/). For wiring any remote MCP server into a harness, see [Connect an agent to a remote MCP server](https://indexagentica.com/guides/connect-an-agent-to-a-remote-mcp-server/).\n",
  "html": "<h2>What you get</h2>\n<p><a href=\"/entries/surrealdb-agent-memory/\">SurrealDB Agent Memory</a> 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 <strong>provenance</strong> (where a fact came from) and a <strong>tri-temporal</strong> timeline. When a newer fact replaces an older one, the old value is <strong>superseded</strong>, not deleted, so you can still answer &quot;what did we believe then?&quot;.</p>\n<p>Each <strong>Context</strong> is an isolation boundary with its own SurrealDB namespace and database. The Context host serves:</p>\n<ul><li>REST under <code>/api/v1/{context_id}/...</code></li><li>MCP (Streamable HTTP) at <code>/mcp</code> on the same host</li></ul>\n<p>Authentication for both is <strong><code>Authorization: Bearer &lt;api-key&gt;</code></strong>. Each key is bound to one Context, so MCP tools can omit <code>context_id</code>. There is no OAuth on this path.</p>\n<p>SurrealDB reports a <strong>77.2%</strong> mean score on <strong>BEAM 1M</strong> (and <strong>57.1%</strong> strict accuracy) on the product page and launch blog. Treat that as their published figure, not an independent re-run.</p>\n<h2>Plans and signup</h2>\n<p>From the product page (2026-11-06):</p>\n<table><thead><tr><th scope=\"col\">Plan</th><th scope=\"col\">Price</th><th scope=\"col\">Tokens</th></tr></thead><tbody><tr><td>Sandbox</td><td>Free, no card</td><td>3 million, one-off</td></tr><tr><td>Lite</td><td>$30/mo</td><td>1 million / month</td></tr><tr><td>Standard</td><td>$300/mo</td><td>10 million / month</td></tr><tr><td>Plus</td><td>$1,100/mo</td><td>40 million / month</td></tr><tr><td>Enterprise</td><td>Annual</td><td>Custom; self-hosted and air-gapped listed</td></tr></tbody></table>\n<p>Tokens count every language-model and embedding call the Context makes, including background work such as consolidation.</p>\n<p><strong>Sandbox is free, but Context creation is a human step.</strong> You sign in to <a href=\"https://studio.surrealdb.com\">SurrealDB Studio</a>, open organisation → <strong>Contexts</strong>, create a Context, then create an API key (<code>sp-…</code>, 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.</p>\n<p>Agent Memory itself is <strong>not open source</strong> 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.</p>\n<h2>Connect over MCP</h2>\n<p>The install docs show Streamable HTTP at <code>/mcp</code> with a Bearer header and <code>--oauth no</code>:</p>\n<pre><code class=\"language-bash\">npx -y @smithery/cli@latest install-mcp \\\n  &quot;https://&lt;your-context-host&gt;/mcp&quot; \\\n  --header &quot;Authorization: Bearer &lt;your-api-key&gt;&quot; \\\n  --oauth no</code></pre>\n<p>Or configure a client by hand:</p>\n<pre><code class=\"language-json\">{\n  &quot;mcpServers&quot;: {\n    &quot;agent-memory&quot;: {\n      &quot;url&quot;: &quot;https://&lt;your-context-host&gt;/mcp&quot;,\n      &quot;headers&quot;: {\n        &quot;Authorization&quot;: &quot;Bearer &lt;your-api-key&gt;&quot;\n      }\n    }\n  }\n}</code></pre>\n<p>Some product-page snippets also show an <code>X-Spectron-Context</code> header. The rename from the project name <strong>Spectron</strong> is still partial: env vars stay <code>SPECTRON_*</code> and some headers stay <code>X-Spectron-*</code>. The MCP install page says the Bearer key alone is enough because the key is bound to one Context.</p>\n<h3>The seven tools</h3>\n<p>From the <a href=\"https://surrealdb.com/docs/agent-memory/reference/mcp-tools\">MCP tools reference</a>:</p>\n<table><thead><tr><th scope=\"col\">Tool</th><th scope=\"col\">Needs</th><th scope=\"col\">Does</th></tr></thead><tbody><tr><td><code>remember</code></td><td><code>memory:write</code></td><td>Persist text (or triples); reconciles (supersession / uncertainty). REST: <code>POST .../facts</code></td></tr><tr><td><code>recall</code></td><td><code>memory:read</code></td><td>Ranked hits over facts and document passages. REST: <code>POST .../query</code></td></tr><tr><td><code>context</code></td><td><code>memory:read</code></td><td>Markdown block for a system prompt. REST: <code>POST .../context</code></td></tr><tr><td><code>reflect</code></td><td><code>memory:read</code> (+ write if <code>persist</code>)</td><td>Synthesise patterns; optional persist. REST: <code>POST .../reflect</code></td></tr><tr><td><code>forget</code></td><td><code>memory:forget</code></td><td>Soft-delete matches from current retrieval; <code>purge: true</code> erases. REST: <code>POST .../forget</code></td></tr><tr><td><code>upload</code></td><td><code>memory:write</code></td><td>Ingest a document (base64); processing is async. REST: <code>POST .../documents</code></td></tr><tr><td><code>inspect</code></td><td><code>memory:read</code></td><td>Fetch entity / trace / document by <code>ref</code>. REST: GETs under entities, traces, documents</td></tr></tbody></table>\n<p><code>remember</code> input (docs):</p>\n<pre><code class=\"language-jsonc\">{\n  &quot;text&quot;: &quot;I just got promoted to CTO.&quot;,\n  &quot;session_id&quot;: &quot;sess_abc123&quot;,\n  &quot;scope&quot;: [[&quot;org/acme/user/alice&quot;]],\n  &quot;labels&quot;: [&quot;source=onboarding&quot;],\n  &quot;infer&quot;: &quot;full&quot;,\n  &quot;observed_at&quot;: &quot;2026-05-12T10:00:00Z&quot;\n}</code></pre>\n<p><code>infer</code> is <code>full</code> (default, LLM extraction), <code>triples</code> (caller-supplied, no LLM), <code>preview</code> (dry run) or <code>none</code> (literal store).</p>\n<p><code>recall</code> takes <code>query</code>, optional <code>k</code> (default 10, max 50), <code>mode</code> (<code>hybrid</code> | <code>vector</code> | <code>bm25</code> | <code>graph</code>), and a read <strong><code>lens</code></strong>. Writes use <strong><code>scope</code> / <code>scopes</code></strong>; an unknown field such as sending <code>scope</code> on a read is ignored without error, so a mis-named read can search everything the key can see.</p>\n<p>Tool failures return <code>isError: true</code> with HTTP 200 on the transport. JSON-RPC <code>error</code> is for protocol faults only.</p>\n<h2>Connect with an SDK</h2>\n<pre><code class=\"language-bash\">pip install surrealdb-memory==1.0.0b1\n# or: pip install &#39;surrealdb[memory]&#39;\nnpm i @surrealdb/memory@1.0.0-alpha.11</code></pre>\n<p>Python (<code>surrealdb-memory</code> 1.0.0b1), against a fake transport so nothing leaves the box:</p>\n<pre><code class=\"language-python\">from surrealdb_memory import Memory\n\nmemory = Memory(\n    context=&quot;your-context-id&quot;,\n    endpoint=&quot;https://&lt;your-context-host&gt;&quot;,\n    api_key=&quot;sp-...&quot;,\n)\nmemory.remember(\n    &quot;I was just promoted to CTO.&quot;,\n    infer=&quot;full&quot;,\n    scopes=&quot;org/acme/user/alice&quot;,\n    labels=[&quot;source=onboarding&quot;],\n)\nhits = memory.recall(&quot;What is Alice&#39;s role?&quot;, k=10, mode=&quot;hybrid&quot;, lens=&quot;org/acme/user/alice&quot;)\nmemory.forget(&quot;anything about my previous role&quot;)          # soft\nmemory.forget(&quot;erase permanently&quot;, purge=True)            # permanent</code></pre>\n<p>Offline, with the real client and a stub transport, those calls became:</p>\n<ul><li><code>POST /api/v1/{context}/facts</code> with <code>text</code>, <code>infer</code>, <code>scopes: [[&quot;org/acme/user/alice&quot;]]</code>, <code>labels</code>, and an <code>Idempotency-Key</code></li><li><code>POST /api/v1/{context}/query</code> with <code>query</code>, <code>k</code>, <code>mode</code>, <code>lens: [[&quot;...&quot;]]</code></li><li><code>POST /api/v1/{context}/forget</code> with <code>query</code> (and <code>purge: true</code> only when requested)</li></ul>\n<p>So a plain scope string is normalised to the DNF form the wire docs describe. The transport sends <code>Authorization: Bearer …</code> from the client’s API key.</p>\n<p>TypeScript (<code>@surrealdb/memory</code> 1.0.0-alpha.11) mirrors the same verbs (<code>remember</code>, <code>recall</code>, <code>forget</code>, <code>reflect</code>, <code>chat</code>, …) and ships OpenAPI-generated path types under <code>/api/v1/{context_id}/...</code>.</p>\n<p>Hosted quickstart env vars still use the Spectron names:</p>\n<pre><code class=\"language-bash\">export SPECTRON_URL=&quot;https://&lt;your-context-host&gt;&quot;\nexport SPECTRON_CONTEXT_ID=&quot;&lt;your-context-id&gt;&quot;\nexport SPECTRON_API_KEY=&quot;sp-...&quot;</code></pre>\n<p>Register scope paths before scoped writes (<code>agent-memory scopes create …</code> or the Cloud admin API).</p>\n<h2>Provenance, supersession and forget</h2>\n<ul><li><strong>Provenance.</strong> Fact-bearing records carry structured provenance so the system can answer where a fact was learned, not only what is known (<a href=\"https://surrealdb.com/docs/agent-memory/mental-model/provenance-and-traceability\">docs</a>).</li><li><strong>Supersession.</strong> A correction replaces the current belief and keeps history. Current recall shows the new value; a known-time (<code>asOf</code>) recall can walk the chain. Cross-provenance clashes surface as <strong><code>uncertainty</code></strong> instead of a silent pick.</li><li><strong>Decay.</strong> Category-aware importance decay runs daily (<code>identity</code> does not decay; <code>context</code> facts also expire after 7 days). Decay changes importance only; it does not end a fact.</li><li><strong>Forget.</strong> Default soft-forget removes matches from current and temporal retrieval but keeps audit history; <code>purge: true</code> permanently erases. Forget needs the <strong><code>memory:forget</code></strong> grant, not only <code>memory:write</code>. Soft-forget does not block future extraction of the same topic.</li></ul>\n<h2>What was and wasn’t tested</h2>\n<p><strong>Tested offline on 2026-11-06:</strong></p>\n<ul><li>surrealdb-memory <strong>1.0.0b1</strong> request shapes for remember / recall / forget / reflect / query_context against documented REST paths (stub transport, no network)</li><li>@surrealdb/memory <strong>1.0.0-alpha.11</strong> package contents and OpenAPI path typings</li><li>MCP and REST documentation for the seven tools, auth, scopes/lens and lifecycle</li></ul>\n<p><strong>Not tested:</strong></p>\n<ul><li>a live Sandbox or paid Context (Studio signup is human)</li><li>OAuth (this product path is Bearer-only)</li><li><code>upload</code> / document pipeline end-to-end</li><li>BEAM 1M reproduction</li></ul>\n<h2>Related reading</h2>\n<p>For how this sits next to Mem0, LangMem, Zep and others, see <a href=\"/compare/agent-memory-layers/\">Memory layers for AI agents</a>. For wiring any remote MCP server into a harness, see <a href=\"/guides/connect-an-agent-to-a-remote-mcp-server/\">Connect an agent to a remote MCP server</a>.</p>"
}
