Recalling memories

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.

Ranked hits - `/query`

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):

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), scopeView (strict, crossTeam, merged - the latter two resolve like strict; see Contexts and scope), 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.

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:

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

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

surreal memory context "What role does Alice have?"

Session-scoped context

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:

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

surreal memory recall "return policy" --include passages

Chat (composed recall + synthesis)

POST /api/v1/{context_id}/chat

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

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. 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, Keywords and BM25, Graph traversal.

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

Ranked hits - /query