> Full SurrealDB documentation index: https://surrealdb.com/docs/llms.txt

# Agent Memory

Memory and knowledge for AI agents on SurrealDB. Principles, architecture, quickstarts, and the mental model.

SurrealDB Agent Memory is a memory and knowledge layer for AI agents. It is an application tier in front of SurrealDB, and every durable record lives in that database: graph, vector, document, relational, and geospatial, written under ACID transactions. Provenance and trust sit on the records themselves. Traces of retrieval and decisions are persisted as graph nodes. Belief history is tri-temporal, so the system can keep apart what was said, what is true now, and what used to be true.

Use this hub to go from principles to running code, then go to the product sections (memory & knowledge, integrations, cookbooks, reference).

> [!NOTE]
> SurrealDB Agent Memory was developed under the project name **Spectron**, and the rename is arriving in stages. Already renamed: the client SDKs (`@surrealdb/memory`, `surrealdb-memory`, and so on), the framework integrations, and, since the CLI rebrand, the **`agent-memory`** binary and the MCP server, which now registers as `agent-memory`.
>
> Still carrying the old name: the **`SPECTRON_*`** environment variables, and the **`X-Spectron-*`** request headers. Those are configuration and wire contract rather than things the product is called, so they are unchanged for now.

## Architecture

What SurrealDB Agent Memory is built to do, what it is not, and how retrieval, traces, and time work:

- [Principles and goals](/docs/agent-memory/architecture/principles-and-goals.md)
- [Eight pillars and six categories](/docs/agent-memory/architecture/eight-pillars-and-categories.md)
- [Coherence, retrieval, and cost tiers](/docs/agent-memory/architecture/coherence-retrieval-and-tiers.md)
- [Traces and memory evolution](/docs/agent-memory/architecture/traces-and-evolution.md)
- [Tri-temporal model](/docs/agent-memory/architecture/tri-temporal-model.md)
- [Surface, models, and security](/docs/agent-memory/architecture/surface-security-and-models.md)
- [Glossary](/docs/agent-memory/architecture/glossary.md)

## Welcome and quickstarts

- **[What is SurrealDB Agent Memory?](/docs/agent-memory/welcome/what-is-surrealdb-agent-memory.md)** - product positioning in one pass.
- **[Why agentic memory?](/docs/agent-memory/welcome/why-agentic-memory.md)** - where naive context and pure-vector shortcuts fail.
- **[The accuracy promise](/docs/agent-memory/welcome/accuracy-promise.md)** - provenance, reconciliation, and auditability.
- **[How it works](/docs/agent-memory/welcome/how-it-works.md)** - end-to-end path from a turn to stored, retrievable state.

**Quickstarts**

- **[Agent Memory on SurrealDB Cloud](/docs/agent-memory/quickstarts/surrealdb-cloud.md)** - Cloud API vs data plane, organisation roles, and your first context in SurrealDB Studio.
- **[Hosted quickstart](/docs/agent-memory/quickstarts/hosted.md)** - SurrealDB Agent Memory Cloud, API key, first remember and recall.
- **[Embedded library](/docs/agent-memory/quickstarts/embedded.md)** - HTTP, MCP, and SDK integration surfaces.

**Building with AI coding tools?** Start with **[Agent guide (AGENTS.md)](/docs/agent-memory/reference/agents.md)** - copy it into Cursor rules or a project skill so your agent can learn SurrealDB Agent Memory without reading the full docs.

## Mental model

How isolation, sessions, categories, and provenance fit together:

- [Unified substrate and authority](/docs/agent-memory/mental-model/two-layer-architecture.md) - authoritative versus experiential **streams** in **one** graph.
- [Contexts and scope](/docs/agent-memory/mental-model/contexts-and-scope.md)
- [Sessions and turns](/docs/agent-memory/mental-model/sessions-and-turns.md)
- [Memory categories](/docs/agent-memory/mental-model/memory-categories.md)
- [Provenance and traceability](/docs/agent-memory/mental-model/provenance-and-traceability.md)
- [Supersession, decay, and forget](/docs/agent-memory/mental-model/memory-lifecycle.md) - how beliefs change, fade, and are removed

## Product sections

- **[Memory & knowledge](/docs/agent-memory/memory-and-knowledge.md)** - authoritative and experiential ingest, unified retrieval, reasoning, operations, tuning.
- **[Integrations](/docs/agent-memory/integrations.md)** - SDKs, MCP, framework adapters.
- **[Cookbooks](/docs/agent-memory/cookbooks.md)** - end-to-end patterns.
- **[Reference](/docs/agent-memory/reference.md)** - REST, management API, CLI, configuration, errors.

## Sessions

- [State and diffs](/docs/agent-memory/sessions/state-and-diffs.md) - what a session holds, and how it changes between turns