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

# Recalling memories

Unified retrieval over facts and document passages.

SurrealDB Agent Memory exposes one fused read path over the **unified substrate**: structured facts from turns and passages from documents. Use **`POST /api/v1/{context_id}/query`** for ranked hits and **`POST /api/v1/{context_id}/context`** for a pre-formatted LLM block.

Register scope paths before use (`surreal memory scopes create org/acme/user/alice`). See [Contexts and scope](/docs/agent-memory/mental-model/contexts-and-scope.md).

## Ranked hits - `/query`

```bash
surreal memory recall "What role does Alice have?" --json \
  --url "$SURREAL_MEMORY_URL" \
  --api-key "$SURREAL_MEMORY_API_KEY" \
  --context-id "$SURREAL_MEMORY_CONTEXT_ID" \
  --limit 10
```

Pass **`lens`** on the REST body (the CLI does not expose a `--scope` flag on `recall` today):

```http
POST /api/v1/{context_id}/query
Authorization: Bearer <key>
Content-Type: application/json

{
  "query": "What role does Alice have?",
  "k": 10,
  "lens": [["org/acme/user/alice"]]
}
```

**Response fields:**

| Field | Meaning |
| --- | --- |
| `tier` | `cache`, `hybrid`, or `escalated`. The response cache (tier 2) is checked first. Tier 1 structured reads (attribute and relation lookups) only seed tier 3 and never answer on their own, so `direct` remains a valid wire value but is not returned by `/query` |
| `hits` | Ranked results; each hit includes **`source`** (`entity`, `attribute`, `action`, `memory_chunk`, `chunk`, or `section`) and optional **`occurredAt`** (known time of the row - use to resolve relative dates in source text) |
| `contextHits` | Extra rows for synthesis, separate from `hits` and not counted against `k`: same-section sibling passages from **section expansion**, neighbouring conversation chunks of ranked memory hits, attribute and relation rows from the tier 1 seed reads, and optional entity fact cards. A row's `source` names its family, and can also be `turn` (an earlier assistant reply). Omitted when nothing was added. Useful for UIs that show “expanded context” beside the ranked answer set |
| `queryMs` | Server-side latency in milliseconds |
| `trace.traceId` | Correlates with `GET .../traces/{traceId}` |

Optional read modifiers: **`labels`** (descriptor filter only), **`lens`** (DNF scope filter by involvement), **`asOf`** (known-time playback - hide facts and relations from later chapters or episodes; see [spoiler-safe narrative memory](/docs/agent-memory/cookbooks/patterns/spoiler-safe-narrative-memory.md)), **`scopeView`** (`strict`, `crossTeam`, `merged` - the latter two resolve like **`strict`**; see [Contexts and scope](/docs/agent-memory/mental-model/contexts-and-scope.md#labels-lens-and-scope-views-reads)), **`include`** (`facts`, `passages`, or both - narrows the response only; retrieval considers all families), **`includeDuplicates`** (default `false` - excludes **near-duplicate** document passages and conversation `memory_chunk` records flagged via SimHash / `duplicate_of`; set `true` to include them, matching `/documents/query`). Exact byte-identical document uploads are still collapsed at ingest (`content_hash`); `includeDuplicates` does not resurrect those.

**`k`** defaults to **10** and is capped at **50** per deployment. The internal retrieval pool is independent of `k` - see [Hybrid search](/docs/agent-memory/memory-and-knowledge/retrieve/hybrid-search.md#answer-size-vs-search-breadth).

### Section expansion

When a ranked hit lands on a section heading or other “pointer” chunk, SurrealDB Agent Memory can pull the same-section siblings into **`contextHits`** so synthesis (and `/chat` citations) see the section body, not only the heading. Expansion is **on by default** for the deployment. It is read-path only, capped, scope-gated, and does not change the ranked `hits` list - so eval and ranker baselines that read only `hits` stay stable. MCP **`recall`** returns the ranked `hits` path; `/chat` and `/context` fold expanded passages into synthesis.

CLI flags: `--limit` (maps to `k`), `--mode hybrid|vector|bm25|graph`, `--include facts,passages`, tri-temporal `--as-of`, `--at-instant`, `--valid-from`, `--valid-until`.

> [!NOTE]
> **`--min-trust`** is not supported yet - the `/query` response does not expose per-hit trust scores, so the CLI rejects the flag rather than silently returning unfiltered results.

## Formatted context - `/context`

Use when you want a single string for system-prompt injection:

```http
POST /api/v1/{context_id}/context
Content-Type: application/json

{
  "query": "What role does Alice have?",
  "k": 10,
  "lens": [["org/acme/user/alice"]]
}
```

```bash
surreal memory context "What role does Alice have?"
```

## Session-scoped context

```http
POST /api/v1/{context_id}/sessions/{session_id}/context
Content-Type: application/json

{
  "query": "What role does Alice have?"
}
```

Returns `{"context": "…"}`: recall for `query`, formatted for the session’s scope and recent turns. `query` is required and must not be empty.

## Document-only query

For retrieval limited to uploaded files:

```http
POST /api/v1/{context_id}/documents/query
```

```bash
surreal memory recall "return policy" --include passages
```

## Chat (composed recall + synthesis)

```http
POST /api/v1/{context_id}/chat
```

```bash
surreal memory chat "Summarise what you know about Alice"
```

SurrealDB Agent Memory runs recall internally, then calls the configured response model. Use `--stream` for SSE.

## Profile and state

```http
GET /api/v1/{context_id}/profile
GET /api/v1/{context_id}/state
```

`profile` returns grouped entries for prompt assembly: `selfFacts` (facts about the caller), `static`, `dynamic`, `preferences`, and `instructions`.

## Four-tier router

See [Coherence, retrieval, and cost tiers](/docs/agent-memory/architecture/coherence-retrieval-and-tiers.md). The router checks the response cache (tier 2) first. On a miss, tier 1 structured reads seed tier 3, the hybrid vector + BM25 + graph retrieval. When tier 3 is thin or unconfident, tier 4 (`escalated`) rewrites the query with HyDE, widens the candidate pool and re-ranks. Mode details: [Hybrid search](/docs/agent-memory/memory-and-knowledge/retrieve/hybrid-search.md), [Keywords and BM25](/docs/agent-memory/memory-and-knowledge/retrieve/keywords-and-bm25.md), [Graph traversal](/docs/agent-memory/memory-and-knowledge/retrieve/graph-traversal.md).

The figure below shows the router 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." />
