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. |
| 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_keywordedges 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.
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. | 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.