# 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 (`spectron scopes create org/acme/user/alice`). See [Contexts and scope](/docs/agent-memory/mental-model/contexts-and-scope.md).

## Ranked hits - `/query`

```bash
spectron recall "What role does Alice have?" --json \
  --url "$SPECTRON_URL" \
  --api-key "$SPECTRON_API_KEY" \
  --context-id "$SPECTRON_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` | `direct`, `cache`, `hybrid`, or `full_context` - relational questions may resolve at tier 1 when the classifier routes to a structured relation read |
| `hits` | Ranked results; each hit includes **`source`** (`entity`, `attribute`, `memory_chunk`, `chunk`, or `section`) and optional **`occurredAt`** (known time of the row - use to resolve relative dates in source text) |
| `contextHits` | Same-section sibling passages pulled by **section expansion** - separate from `hits`, not counted against `k`. Empty when expansion is off or found nothing to add. 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)), **`scope_view`** (`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` rows 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 (`SPECTRON_MAX_QUERY_K`). The internal retrieval pool is independent of `k` - see [Hybrid search](/docs/agent-memory/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** (`SPECTRON_RETRIEVAL_SECTION_EXPANSION`); set it to `0` to opt out. 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
spectron context "What role does Alice have?"
```

## Session-scoped context

```http
GET /api/v1/{context_id}/sessions/{session_id}/context
```

Returns recall formatted for the session’s scope and recent turns.

## Document-only query

For retrieval limited to uploaded files:

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

```bash
spectron recall "return policy" --include passages
```

## Chat (composed recall + synthesis)

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

```bash
spectron 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
POST /api/v1/{context_id}/state
```

`profile` returns category-grouped attributes (identity, knowledge, context, instructions) for prompt assembly.

## Four-tier router

See [Coherence, retrieval, and cost tiers](/docs/agent-memory/architecture/coherence-retrieval-and-tiers.md). Tiers progress from cheap structured lookup through response cache, hybrid vector + BM25 + graph, to full-context synthesis. Mode details: [Hybrid search](/docs/agent-memory/retrieve/hybrid-search.md), [Keywords and BM25](/docs/agent-memory/retrieve/keywords-and-bm25.md), [Graph traversal](/docs/agent-memory/retrieve/graph-traversal.md).