# Principles and goals

What SurrealDB Agent Memory is built to do - and what it deliberately is not.

SurrealDB Agent Memory is a **memory and knowledge layer for AI agents** built so **you can trust** what it remembers and retrieves. It sits as a **horizontally scalable application tier** in front of SurrealDB; durable state - graph, vectors, documents, structured records - lives in the database, typically **one ACID transaction per write**.

## Principles

- **One substrate, many models.** Documents, conversations, entities, attributes, relations, traces, and embeddings live in one ACID-transactional database. Cross-store stitching is rejected as an architectural choice, not a feature gap.
- **Provenance and trust are first-class data.** Every fact-bearing record carries where it came from, who said it, when it was authored, which source produced it, and how trusted that source is. Trust and confidence are stored, queryable, and auditable.
- **Memory is tri-temporal and non-deleting.** Supersession and aging replace blind overwrite. **System time** (MVCC record history), **known time** (when SurrealDB Agent Memory first learnt a fact), and **valid time** (when the fact held in the world) are queryable independently. See [Tri-temporal model](/docs/agent-memory/architecture/tri-temporal-model.md).
- **One reconciler, all provenance.** Document-extracted facts, turn-extracted facts, reflections, elaborations, and consolidations all flow through the same supersession-and-uncertainty machinery - identical guarantees regardless of how a fact arrived.
- **Traces are memory, not logs.** Retrieval, decision, and response traces are first-class graph nodes that feed back into ranking, calibration, consolidation, and reinforcement - not an afterthought shipped only to a vendor dashboard.
- **Cost is tiered and visible.** Cheap questions are answered cheaply; expensive paths are explicit, not buried in averages. See [Coherence, retrieval, and cost tiers](/docs/agent-memory/architecture/coherence-retrieval-and-tiers.md).
- **Models are pluggable.** Extraction, embedding, reconciliation, synthesis, and chat models are configurable per Context and per call.
- **Deterministic by design.** Change the data, and the agent’s answer changes. Calibration, tri-temporality, supersession, and response reuse (with invalidation) anchor answers in **queryable substrate state** rather than in model variance alone.
- **The HTTP contract is explicit.** SurrealDB Agent Memory publishes an OpenAPI specification for its REST surface. Official SDKs are generated from that spec so request and response types stay aligned with the server across releases.

## What SurrealDB Agent Memory is not

- **Not a vector database.** Vectors are one signal among many. Embeddings-only retrieval has known failure modes; SurrealDB Agent Memory treats them as an input to a **fused ranker**, not as the whole substrate.
- **Not a chat-history blob.** Turns are reconciled into typed entities, attributes, and relations - not stored as opaque text that is re-stuffed into prompts at query time.
- **Not a hand-rolled knowledge graph.** Structure emerges from extraction, elaboration, and consolidation. Users do not hand-author a schema to “get a graph”; the graph is a **product** of the pipeline.
- **Not a context-window manager.** SurrealDB Agent Memory is the durable memory and knowledge layer **behind** an agent - not the in-prompt scratchpad. The agent decides what goes in the window; SurrealDB Agent Memory decides what is **remembered**.
- **Not an agent runtime.** `/chat` is a convenience composition over ingest and read paths for callers who want SurrealDB Agent Memory to *behave* like an agent. SurrealDB Agent Memory does not own model orchestration, tool calling, or planning loops.
- **Not an observability vendor.** Traces are stored substrate state used by the system itself. They yield derivable operational signals, but SurrealDB Agent Memory is not “metrics SaaS by default”.

## Where to read next

- [Eight pillars and six categories](/docs/agent-memory/architecture/eight-pillars-and-categories.md) - the operational model in primitives.
- [Architecture glossary](/docs/agent-memory/architecture/glossary.md) - short definitions of key terms.
- [Unified substrate and authority](/docs/agent-memory/mental-model/two-layer-architecture.md) - how authoritative and experiential material meet in one graph.