> 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/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/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/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 or below the **confidence floor** (0.40 fused score), 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.

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