---
title: "Coherence, retrieval, and cost tiers"
description: "Five coherence dimensions and hybrid structural retrieval. Also covers the four-tier query ladder."
canonical_url: "https://surrealdb.com/docs/agent-memory/learn/architecture/coherence-retrieval-and-tiers"
section: "Agent Memory"
surrealdb_version: "4.x"
last_modified: "2026-11-18T02:09:16Z"
---

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

# Coherence, retrieval, and cost tiers

Five coherence dimensions and hybrid structural retrieval. Also covers the four-tier query ladder.

When you hear **cat**, you do not run one search string - you blend what it reminds you of (pets, lions, a team logo), exact words you once read, how things connect, and whether a fact is still true. Retrieval in SurrealDB Agent Memory works the same way: several signals fused together, not a single embedding score.

## Five coherence dimensions

Memory is coherent along five axes at once - SurrealDB Agent Memory stores enough metadata to answer questions on each, so retrieval stays auditable and trustworthy:

| Dimension | What it gives you |
| --- | --- |
| **Semantic** | Similarity before structure is explicit: embedding-based recall over entities and passages. |
| **Lexical** | What was actually said or shown, down to character positions in the source: extracted attributes carry `source.span` into the originating turn or document passage. Citations are a **stored field**, not best-effort prose. |
| **Relational** | Understanding as connections: one entity/relation graph so “cat” can reach a manual, a prior turn, and a related entity (lion, pet, breed) without treating them as unrelated chunks. |
| **Time** | What held when, and how beliefs evolved: `valid_from` / `valid_until`, `as_of`, and time-travel queries. See [Tri-temporal model](/docs/agent-memory/learn/architecture/tri-temporal-model.md). |
| **Space** | Where a fact was captured or applies - optional geometry; geo filters compose with semantic and graph signals in the same ranker. |

A vector-only index misses several of these at once, while an unstructured store misses them unless you add structure later. SurrealDB Agent Memory stores the metadata up front.

## Structural retrieval (beyond embeddings)

Retrieval is hybrid by design. Embeddings are one signal, fused with other precomputed structure so that top-k is not a black box.

Typical signals in the fused ranker include:

- **Vector recall** - dense embeddings on entities, attributes, chunks, and (when enabled) images and audio.
- **Lexical recall** - BM25 over chunk text and entity names for exact phrases and rare terms.
- **Graph traversal** - limited hops from seed entities when surface forms differ.
- **Keyword bridges** - RAKE keyphrases linked via `knowledge_has_keyword` edges from query-matched terms to document passages.
- **Section embeddings and document links** - related sections, not only the single nearest chunk.
- **Personalised PageRank** - graph-walk scoring biased toward query seeds. Relation edges used in graph hops are **scope-gated** on the edge itself, not only on destination entities.
- **Geographic recall** - radius, polygon, nearest‑k on stored geometry.
- **Trace-derived features** - prior retrieval outcomes boost what worked; demote what led to corrections.

Each `/query` emits a **`retrieval_trace`** recording candidates, per-signal contributions, and the returned set.

Hands-on retrieval modes are in [Hybrid search](/docs/agent-memory/learn/retrieve/hybrid-search.md).

## Tiered query resolution

SurrealDB Agent Memory does not run the same expensive path on every request. Reads route through a four-tier ladder so simple questions use as few LLM tokens as possible. A cache hit skips a large prompt and a synthesis-model call, and structured lookups add exact fact rows to the context cheaply.

| Tier | What happens | Token / cost profile |
| --- | --- | --- |
| **2 - Response reuse** | Checked first. Match against prior answers in the same Context, for callers who can see the same records, with **entity-aware invalidation** (cited facts must still be current). Returns a prior answer when still valid. Used by `/chat` only: `/query`, `/context`, `/reflect`, and the MCP read tools skip it. **Bypassed** for `/chat` when the session already has prior turns (the reply depends on the transcript window; windowed turns neither reuse nor seed the cache), or when the call sets `bypassCache: true`. See [Caching and invalidation](/docs/agent-memory/learn/tuning/caching-and-invalidation.md). | **No new generation** on a hit - reuses prior synthesis. |
| **1 - Structured seed reads** | Typed questions looked up in the entity/attribute graph by key - no embeddings, no LLM. Never returns on its own: the rows it finds join tier 3 as seeds. | **Minimal tokens** - adds a few fact rows to the context. |
| **3 - Hybrid retrieval and synthesis** | Fused retrieval over a **bounded internal pool** (default 256 candidates; independent of answer `k`), plus the tier-1 seeds, then LLM synthesis over a **bounded** context block on `/chat`. Default answer size **`k`** is **10** (max **50**). | Moderate tokens - default for open questions. |
| **4 - Escalated** | Runs when tier 3 is thin (fewer than `k / 2` hits), when its top fused score is below the **confidence floor** (0.40) and no vector hit reaches a cosine of 0.80, or when the query classifier asks for full context: a HyDE query rewrite, a doubled candidate pool, and a re-rank. Hits are merged with the tier-3 hits by id, keeping the highest score, and the answer stays `k`-sized. Reported as `escalated` on the trace. | **Highest token use** - explicit escalation, still traceable. |

Tiers cascade: a cache miss falls to tier 1 and tier 3, and a thin or low-confidence tier 3 escalates to tier 4. Each tier writes **`retrieval_trace`** metadata describing which tier ran and why - so you can see where token spend goes and tune per Context.

The figure below shows the tiers in execution order, with the `tier` value each exit reports.

<img src="~/assets/img/diagrams/light/am-recall-tiers-light.webp" darkSrc="~/assets/img/diagrams/am-recall-tiers.webp" alt="The read path in execution order. Query understanding classifies and embeds the question. Tier 2 response reuse returns a prior answer when a previous query has cosine similarity of at least 0.92 and its cited facts are still current, exiting with tier cache. On a miss, tier 1 structured reads look up attributes and relations in the graph without an LLM; they never end the request and their rows join tier 3 as seeds. Tier 3 fuses vector, BM25 and graph signals over 256 candidates and exits with tier hybrid unless it escalates. It escalates when the classifier asks for full context, when fewer than k / 2 hits came back, or when the top fused score is below 0.40 and the best vector cosine is below 0.80. Tier 4 rewrites the query with HyDE, doubles the pool to 512, re-ranks and exits with tier escalated. Tier 2 runs on /chat only, and is skipped on /query, /context, /reflect and the MCP read tools, when the session already has prior turns, when bypassCache is true, and when the read has a time or location filter." />

In short: most “what is Alice’s role?”-style questions should resolve without stuffing the entire memory graph into the model context.
