---
title: "Learn"
description: "How SurrealDB Agent Memory works: contexts, scopes, sessions and memory categories, then ingest, retrieve, reasoning, operations and tuning, and the architecture underneath."
canonical_url: "https://surrealdb.com/docs/agent-memory/learn"
section: "Agent Memory"
surrealdb_version: "4.x"
last_modified: "2026-11-18T02:40:10Z"
---

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

# Learn

How SurrealDB Agent Memory works: contexts, scopes, sessions and memory categories, then ingest, retrieve, reasoning, operations and tuning, and the architecture underneath.

This section explains how SurrealDB Agent Memory works. The mental model comes first, then each step a fact goes through, from ingest to retrieval, and last the architecture underneath. If context windows and embeddings are new to you, start with [How an AI model remembers](/docs/agent-memory/welcome/how-a-model-remembers.md).

## Concepts

- [Contexts and scope](/docs/agent-memory/learn/mental-model/contexts-and-scope.md) - where memory is stored, and who can read which part of it
- [Sessions and turns](/docs/agent-memory/learn/mental-model/sessions-and-turns.md) - the unit of a conversation
- [Memory categories](/docs/agent-memory/learn/mental-model/memory-categories.md) - the six kinds of experiential memory
- [Supersession, decay, and forget](/docs/agent-memory/learn/mental-model/memory-lifecycle.md) - how a fact changes and ends
- [Provenance and traceability](/docs/agent-memory/learn/mental-model/provenance-and-traceability.md) - where each fact came from
- [Unified substrate and authority](/docs/agent-memory/learn/mental-model/two-layer-architecture.md) - how documents and conversations meet in one graph

Agent Memory stores two kinds of material in one SurrealDB graph, the Authoritative and Experiential pillars from [Eight pillars and six categories](/docs/agent-memory/learn/architecture/eight-pillars-and-categories.md):

- **Authoritative** - manuals, policies, product data, structured uploads (`source.kind = "document"`, higher default trust).
- **Experiential** - conversation, sessions, and derived facts (`source.kind = "turn"`, reflections, elaborations, consolidations).

The sections below are organised by what you do with them: ingest, retrieve, reason and tune.

## Ingest

**Authoritative**

- [Uploading documents](/docs/agent-memory/learn/ingest/authoritative/uploading-documents.md), [Bulk import](/docs/agent-memory/learn/ingest/authoritative/bulk-import.md)
- [Multi-modal content](/docs/agent-memory/learn/ingest/authoritative/multimodal-content.md), [Knowledge nodes](/docs/agent-memory/learn/ingest/authoritative/knowledge-nodes.md)

**Experiential**

- [Remember](/docs/agent-memory/learn/ingest/experiential/remember.md) - `POST /facts` and `/facts/batch`
- [Sessions](/docs/agent-memory/learn/sessions/chat-sessions.md) - containers for turns ([creating](/docs/agent-memory/learn/sessions/creating-sessions.md), [adding turns](/docs/agent-memory/learn/sessions/adding-turns.md))

## Retrieve

Unified read path over facts **and** document passages:

- [Recalling memories](/docs/agent-memory/learn/retrieve/recall.md) - `/query`, `/context`, `/chat`
- [Hybrid search](/docs/agent-memory/learn/retrieve/hybrid-search.md), [Keywords and BM25](/docs/agent-memory/learn/retrieve/keywords-and-bm25.md), [Graph traversal](/docs/agent-memory/learn/retrieve/graph-traversal.md)

HTTP tables: [REST API](/docs/agent-memory/reference/rest-api.md) and [Surface, models, and security](/docs/agent-memory/learn/architecture/surface-security-and-models.md).

## Reasoning

How writes are extracted, reconciled, and time-stamped - for **both** documents and turns:

- [Extraction pipeline](/docs/agent-memory/learn/reasoning/extraction-pipeline.md)
- [Reconciliation and supersession](/docs/agent-memory/learn/reasoning/reconciliation-and-supersession.md)
- [Authority when pillars meet](/docs/agent-memory/learn/reasoning/authority-hierarchy.md), [Cross-layer linking](/docs/agent-memory/learn/reasoning/cross-layer-linking.md)
- [Temporal validity](/docs/agent-memory/learn/reasoning/temporal-validity.md), [Instructions and uncertainties](/docs/agent-memory/learn/reasoning/instructions-and-uncertainties.md)

## Operations & tuning

- [Reflect](/docs/agent-memory/learn/operations/reflect.md), [Forget](/docs/agent-memory/learn/operations/forget.md), [Profiles](/docs/agent-memory/learn/operations/profiles.md)
- [Models per stage](/docs/agent-memory/learn/tuning/models-per-stage.md), [Caching and invalidation](/docs/agent-memory/learn/tuning/caching-and-invalidation.md), [Extraction vocabulary](/docs/agent-memory/learn/tuning/ontology-grounding.md)

## Examples

- [Showcase](/docs/agent-memory/cookbooks/showcase.md) - Finished demos built on Agent Memory, each with how it was made.

- [Cookbooks](/docs/agent-memory/cookbooks.md#build) - Step-by-step builds of support agents, research agents, assistants and more.

- [Patterns](/docs/agent-memory/cookbooks.md#patterns) - Reusable patterns such as user memory in chat, reflection loops and spoiler-safe memory.

## Architecture

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