# Overview

Principles, architecture, quickstarts, and mental model for SurrealDB Agent Memory - memory and knowledge for AI agents on SurrealDB.

SurrealDB Agent Memory is a **memory and knowledge layer for AI agents** - a **horizontally scalable application tier** in front of **SurrealDB**, which holds every durable record (graph, vector, document, relational, geospatial) with **ACID writes**, **first-class provenance and trust**, **graph-resident traces**, and **tri-temporal** belief history. It aims for memory that **associates** related ideas and keeps straight **what was said, what is true now, and what used to be true** - much like people do, but queryable and auditable in software.

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

> [!NOTE]
> SurrealDB Agent Memory was developed under the project name **Spectron**, and that name is retained throughout the shipped interface: the `spectron` and `spectrond` binaries, the `SPECTRON_*` environment variables, the `spectron_*` MCP tool names, and SDK packages such as `@surrealdb/spectron`. The rule of thumb is that prose uses the product name and anything you type or configure uses `spectron`. These names will be renamed in a future release.

## 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.