# Glossary

Terminology used across SurrealDB Agent Memory docs.

SurrealDB Agent Memory’s architecture is described by **eight pillars** of agent memory and by **six experiential memory categories** (episodic turns plus identity, knowledge, context, instructions, uncertainty). Curated documents and conversational memory are **Authoritative** versus **Experiential** *pillars* - both are records in the **same** SurrealDB graph. See [Eight pillars and six categories](/docs/agent-memory/architecture/eight-pillars-and-categories.md) and [Unified substrate and authority](/docs/agent-memory/mental-model/two-layer-architecture.md).

## Attribute

A key-value property on an entity, representing a learned or asserted fact. Attributes are versioned: when a value changes, the old attribute is superseded (not deleted) and a new one is created, forming a supersession chain. Attributes carry `valid_from` and `valid_until` timestamps for temporal queries.

## Authoritative precedence

The precedence rule: **Authoritative** (curated) content takes precedence over **Experiential** assertions when they conflict. Disagreements are surfaced via **`uncertainty`** records and conflict indicators in state/profile responses - curated records are not silently overwritten. See [Authority when pillars meet](/docs/agent-memory/reasoning/authority-hierarchy.md).

## BM25

A keyword-based full-text ranking algorithm used in SurrealDB Agent Memory's hybrid retrieval. BM25 complements vector search by finding exact-keyword matches that semantic search might miss.

## Context

The unit of memory storage and configuration isolation in SurrealDB Agent Memory. Each Context is bound to a SurrealDB `(namespace, database)` pair and has its own API keys, model configuration, and data. Contexts cannot see each other's data. See [Contexts and scope](/docs/agent-memory/mental-model/contexts-and-scope.md).

## Decision trace

A **`decision_trace`** node records reconciliation outcomes: candidates considered, records created or superseded, confidence and trust, and links to parent traces. Ranked reads emit **`retrieval_trace`**; `/chat` and `/reflect` emit **`response_trace`**. Together they form the graph-resident audit model described in [Traces and memory evolution](/docs/agent-memory/architecture/traces-and-evolution.md).

## Dimensional scope

Hierarchical scope paths (for example `org/acme/user/alice/`) that partition data within a Context. Records store visibility as **OR-of-AND clauses** (each clause lists scope nodes that must all apply together). Queries and grants resolve which clauses a caller can see. See [Contexts and scope](/docs/agent-memory/mental-model/contexts-and-scope.md).

## Entity

A thing being tracked in **experiential** memory - a person, company, product, location, or other named object. Entities are identified by a `(type, normalised_name)` pair and carry attributes and relations. Entities can resolve to **knowledge** nodes via `resolves_to`.

## Extraction pipeline

The multi-stage process that converts conversational turns into structured experiential records. It operates in three stages: pattern matching (Stage 0), fast LLM (Stage 1), and strong LLM (Stage 2). The pipeline produces entities, attributes, relations, instructions, uncertainties, and invalidations.

## Extraction vocabulary

The entity names, attribute keys, relation labels, and action verbs a Context has already used, fed back into the extraction prompt so later runs reuse them instead of inventing near-synonyms. It is emergent rather than configured: there is no per-Context ontology to declare. Entity types are a separate, fixed vocabulary. See [Extraction vocabulary](/docs/agent-memory/tuning/ontology-grounding.md).

## Hybrid retrieval

A query mode that combines vector similarity (semantic) and BM25 (keyword) results using Reciprocal Rank Fusion (RRF). The `hybrid_graph` mode adds keyword graph density and typed knowledge graph scores to the fusion for improved precision.

## Instruction

A behavioural directive for the agent, stored separately from factual memory. Instructions are first-class records with `active` status and can be created, updated, and deactivated. They are included in profile responses and injected into the agent's system context.

## Authoritative pillar (curated knowledge)

The **Authoritative** pillar covers curated artefacts (`source.kind = "document"`, operator `upsert`): documents, policies, product data, FAQs, structured exports. Higher default **trust**. Same SurrealDB substrate as experiential records.

## Experiential pillar (conversational memory)

The **Experiential** pillar covers conversational input and derived facts (`turn`, `reflect`, `elaboration`, `consolidation`, …). It includes the **six [memory categories](/docs/agent-memory/mental-model/memory-categories.md)**: episodic session/turn data plus identity, knowledge, context, instructions, and uncertainty.

## MCP (Model Context Protocol)

An open protocol for connecting AI agents to tools and data sources. SurrealDB Agent Memory exposes an MCP server at `/mcp` with seven high-level tools for memory and knowledge operations.

## Memory category

A classification for **experiential** data (plus the raw **episodic** record): `identity`, `knowledge`, `context`, `instructions`, and **`uncertainty`** records, alongside the session/turn stream itself. Instructions and uncertainty use dedicated tables/paths. See [Memory categories](/docs/agent-memory/mental-model/memory-categories.md).

## Principal

The identity an API key acts as. A principal has a `kind` (`human`, `agent`, `service`, or `unknown`) that describes what it is, and a per-verb `grants` map that decides what it may do and where. Kind never affects access. See [Permissions and delegation](/docs/agent-memory/mental-model/contexts-and-scope.md#permissions-and-delegation).

## Profile

A structured snapshot of the current memory state for a given scope. A profile aggregates identity facts, dynamic context, preferences, and active instructions into a format suitable for injection into an agent's system prompt.

## Provenance

The ability to trace every record back to its **source** (turn, document, or trace). Records carry a structured **`source`** object (`kind`, `ref`, `span`, `trust`, `derived_from`, …). Some examples use `source_turn` as shorthand for conversational `source.ref`. See [Provenance and traceability](/docs/agent-memory/mental-model/provenance-and-traceability.md).

## Reconciliation

The **Reconciliation** pillar: integrating newly extracted information with existing beliefs - deduplication, supersession, scope coexistence, and **Authoritative** precedence. See [Eight pillars and six categories](/docs/agent-memory/architecture/eight-pillars-and-categories.md).

## Reflection

The **Reflection** pillar: on-demand synthesis (`POST /reflect`). Insights can be transient or persisted with `source.kind = "reflect"`.

## Relation

A typed edge between two entities, representing a fact about their connection. Relations carry a label (e.g. `works_at`, `relocated_to`) and temporal validity timestamps.

## `resolves_to`

A link from an experiential-memory entity to a **knowledge** node under the **Authoritative** pillar. When set, the agent can combine conversational context with curated facts for the same real-world thing.

## ResultKind

The **`source`** field on each `/query` hit: `entity`, `attribute`, `memory_chunk`, `chunk`, or `section`. Literal `infer: none` writes surface as **`memory_chunk`**; structured extraction surfaces as **`entity`** / **`attribute`**.

## Scope floor

The minimum scope paths that an API key must include in its requests. A key scoped to `org/acme` cannot make requests at `org/beta`. The server enforces this at the query level. Register paths with `spectron scopes create` before use.

## Semantic response cache

A per-Context cache keyed on the embedding of the query string. Before falling through to full retrieval, SurrealDB Agent Memory checks whether a semantically similar query has been answered recently and returns the cached result if the similarity exceeds the threshold.

## Session

A first-class conversation record in SurrealDB Agent Memory. Sessions group turns together and provide the scope context for all memory extracted from those turns. Sessions are durable records - they persist after the conversation ends and can be recalled, diffed, and reflected upon.

## Supersession

The versioned replacement of an attribute value. When new information contradicts a stored attribute, the old record is marked with `superseded_by` and `valid_until`, and a new record is created with `supersedes` and `valid_from`. Both remain in the database, forming a correction history.

## Turn

A single message in a session, with a role (`user`, `assistant`, `system`, or `tool`) and content. Turns are the input to the extraction pipeline and the provenance anchor for all memory produced from them.

## Uncertainty

Explicit records for gaps and clashes - part of the **Experiential** pillar’s six categories and central to the **Reconciliation** pillar when confidence is insufficient or provenances disagree.

## `valid_from` / `valid_until`

Temporal validity fields on attributes and relations. `valid_from` records when a fact became true; `valid_until` records when it ceased to be true. These fields enable point-in-time queries and historical analysis without deleting old data.