Retrieve

Retrieve understands meaning rather than keywords. “Where does Alice work?”, “Alice’s employer”, and “What company is Alice at?” all surface the same memory. Your query is embedded and compared against stored memory embeddings, then results are ranked by relevance_score.

POST /v1/retrieve
Authorization: Bearer anona_live_YOUR_KEY
Content-Type: application/json

{
  "space_id": "customer-support-bot",
  "query": "Where does Alice work?",
  "top_k": 10,
  "memory_type": ["fact"],
  "tags": ["work"],
  "tags_match": "any",
  "min_score": 0.3,
  "mode": "accurate"
}

Parameters

Parameter	Type	Required	Description
`space_id`	string	Yes	Which space to search.
`query`	string	Yes	Natural-language query.
`limit`	integer	No	Maximum results, 1 to 100. Defaults to 10.
`top_k`	integer	No	Alias for `limit`, 1 to 100. Takes precedence when both are sent.
`memory_type`	string[]	No	Filter by type: `fact`, `note`, `experience`, or `summary`.
`user_id`	string	No	Only memories written under this end user. See Scoping.
`agent_id`	string	No	Only memories written under this agent.
`session_id`	string	No	Only memories written under this conversation or run.
`tags`	string[]	No	Return only memories carrying these tags.
`tags_match`	string	No	How `tags` combine: `any` (default), `all`, `any_strict`, `all_strict`, or `exact`.
`min_score`	number	No	Drop results whose `relevance_score` falls below this floor. Trades breadth for precision without shrinking `limit`.
`prefer_observations`	boolean	No	When `true` (default), returns a distilled `note` in place of the raw facts behind it. Set `false` to get both. See Memory types.
`as_of`	string	No	ISO 8601 instant. Point-in-time recall: drops every memory recorded after it, so you get what the space knew then. See Searching over time.
`query_timestamp`	string	No	ISO 8601 instant that recency scoring and relative dates in the query (“last June”) are measured against, instead of now. Re-ranks only, and never removes a result.
`mode`	string	No	`accurate` (default) or `fast`. See Latency modes.
`format`	string	No	`results` (default) returns only the array. `block` also returns one prompt-ready string. See Prompt-ready context.
`context_max_tokens`	integer	No	Approximate token ceiling for that block.

Response

{
  "results": [
    {
      "memory_id": "mem_abc123def456",
      "content": "Alice works at Google and specializes in distributed systems",
      "relevance_score": 0.95,
      "memory_type": "fact",
      "entities": ["Alice", "Google"],
      "occurred_start": "2024-01-15T10:30:00Z",
      "occurred_end": "2024-01-15T10:30:00Z",
      "metadata": {"user_id": "alice_123"},
      "created_at": "2026-07-14T12:34:56Z"
    }
  ],
  "usage": {
    "input_tokens": 8
  }
}

Field	Type	Description
`memory_id`	string	Stable id for the memory.
`content`	string	The memory text.
`relevance_score`	number or null	Higher means more relevant. `null` for results returned outside a ranked recall.
`memory_type`	string	`fact`, `note`, `experience`, or `summary`.
`entities`	string[]	The people, places, and things this memory is about.
`occurred_start`	string or null	ISO timestamp for when the event began, distinct from `created_at`.
`occurred_end`	string or null	ISO timestamp for when the event ended.
`metadata`	object	Whatever you attached at write time.
`created_at`	string	When the memory was recorded.

results = client.retrieve(
    space_id="customer-support-bot",
    query="Where does Alice work?",
    limit=10,
)

for r in results:
    print(r["content"], r["relevance_score"])

client.retrieve() returns the results list directly, and an empty list when nothing matches.

Memory types

Every result carries a memory_type. The same content can exist at more than one level, as raw evidence and as a distilled version of it, so filtering by type asks for exactly the layer you want.

Type	What it is
`fact`	Raw evidence: a single piece of information as it was recorded. Append-only.
`note`	A consolidated synthesis distilled from related facts, deduped and stated at a higher level. One note can stand in for several raw facts.
`experience`	An episodic memory: something that happened, from the recorder’s point of view.
`summary`	A broad pattern learned across many memories, rather than a single event.

By default (prefer_observations: true) a note is returned in place of the facts it was built from, so you see one distilled result instead of the same content several times. Set prefer_observations: false to receive the raw facts alongside their note.

Entities and time

Each result carries structured signal beyond the raw text.

Signal	Detail
Entities	Retrieval extracts the people, places, and things a memory is about and returns them in `entities`. Because memories are linked through shared entities, a query about one entity can surface related memories about the others it connects to.
Event time	`occurred_start` and `occurred_end` capture when the event happened, separately from `created_at`, which is when you recorded it. Ranking is recency-aware, so more recent and more time-relevant memories score higher.

The same entities are exposed as a browsable graph. See Graph.

Searching over time

Every memory carries two independent times, and knowing which is which is most of the work:

	Set by	Returned as	Meaning
Event time	`timestamp` on record	`occurred_start` / `occurred_end`	When the thing happened.
Record time	the system, at write	`created_at`	When you told us about it.

They differ whenever you import history: a memory about last June that you upload today has an event time of last June and a record time of today. as_of and query_timestamp are not variants of each other: one filters, the other ranks, and both work on record time.

# What did the space know on June 1st? Anything recorded
# after that instant is dropped, however relevant.
results = client.retrieve(
    space_id="support",
    query="what plan is this customer on?",
    as_of="2026-06-01T00:00:00Z",
)

# Rank as though it were June 1st, and read "last quarter"
# in the query relative to that date. Nothing is removed.
results = client.retrieve(
    space_id="support",
    query="what changed last quarter?",
    query_timestamp="2026-06-01T00:00:00Z",
)

Use as_of to reproduce a past answer or audit a decision: “why did the agent say that on June 1st”. Use query_timestamp when the query itself contains a relative date, or when you want older-but-more-time-relevant memories to rank higher without excluding anything. Both take an ISO 8601 instant. A malformed one is rejected as 422 before the search runs, so a typo costs you nothing.

as_of filters on when a memory was recorded, not on when the event happened. A bulk import is recorded today no matter what timestamp each item carries, so as_of a year ago returns nothing from it. There is currently no filter on event time. timestamp and occurred_start affect ranking and are returned on results, but cannot be used as a range filter.

Under as_of, retrieval skips its graph-expansion pass and answers from semantic, keyword and temporal retrieval only. Expansion follows entity links without a time bound, so it could pull in a memory recorded after the cutoff: a wrong answer for point-in-time recall rather than a ranking artifact. The practical effect is that an as_of search is slightly narrower than the same search without it.

Prompt-ready context

Most callers take the results array and join it into a system prompt. Ask for format: "block" and that is done for you, including the token budget, which a hand-written loop usually skips.

context = client.get_context(space_id="support", query=user_message)

messages = [
    {"role": "system", "content": context},
    {"role": "user", "content": user_message},
]

Over the raw API:

{
  "space_id": "support",
  "query": "what plan are they on?",
  "format": "block",
  "context_max_tokens": 500
}

{
  "context": "1. Customer is on the Scale plan\n2. Their team has four seats",
  "token_estimate": 18,
  "results": [ "…unchanged…" ],
  "usage": { "input_tokens": 0, "output_tokens": 0 }
}

results stays populated, so wanting both costs one round trip, not two.
The block is numbered plain text with no header, so you compose your own prompt around it.
context_max_tokens drops whole memories, lowest-ranked first. Text is never cut mid-sentence: half a fact still reads as a fact.
token_estimate is an estimate, derived from a characters-per-token approximation rather than a tokenizer. Treat it as a guide when budgeting a context window, not an exact count.

Omitting format behaves exactly as before.

Scoping within a space

A space is the coarse boundary. user_id, agent_id and session_id partition it, so one space can serve many end users without their memories mixing, and you do not need a space per user.

# Write under a user
client.record(
    space_id="support",
    content="Prefers email over phone.",
    user_id="alice",
)

# Only Alice's memories come back
results = client.retrieve(
    space_id="support",
    query="how should we contact them?",
    user_id="alice",
)

Scoping is strict, and that is the point:

A scoped search returns only memories written under the same scope. Bob’s memories can never appear in Alice’s results.
Memories stored without a scope are not returned to a scoped search either. If you turn scoping on for a space that already has history, that history stays visible to unscoped searches but not to scoped ones, so backfill the scope on those memories if you need them.
Passing several keys ANDs them: user_id + session_id returns only that user’s memories from that session.
Consolidated memories are built per user, so a synthesis never mixes two users’ facts. Sessions roll up into the user, which is what lets the memory improve across conversations.

Tags beginning with anona: are reserved for this and rejected with 422 reserved_tag, since otherwise a hand-written tag could impersonate another user’s scope. Use the scope fields instead.

Scoping costs nothing when unused. A request without these fields behaves exactly as it did before they existed.

Latency modes

mode trades relevance quality against speed.

Mode	Behavior	When to use
`accurate`	Neurally reranks candidates for best relevance. The default.	Most calls, where result quality matters most.
`fast`	Skips the neural rerank pass and ranks by retrieval fusion instead.	Latency-sensitive paths such as agent loops and autocomplete-style lookups, where slightly lower precision is an acceptable tradeoff.

results = client.retrieve(
    space_id="customer-support-bot",
    query="Where does Alice work?",
    mode="fast",
)

Error responses

Status	Code	Cause
400	`bad_request`	Missing `query` or `space_id`.
401	`unauthorized`	Missing or invalid API key.
403	`forbidden`	The space is not owned by your organization.
404	`not_found`	The space does not exist.
429	`rate_limited`	Credit quota or rate limit exceeded.

See the full error reference.

Next steps

Reason API

Get a synthesized answer instead of a ranked list.

Graph API

Inspect the entities behind your results.

API Essentials

Memory (data plane)

LLM Proxy (drop-in)

Account (control plane)

Parameters

Response

Memory types

Entities and time

Searching over time

Prompt-ready context

Scoping within a space

Latency modes

Error responses

Next steps

Reason API

Graph API

​Parameters

​Response

​Memory types

​Entities and time

​Searching over time

​Prompt-ready context

​Scoping within a space

​Latency modes

​Error responses

​Next steps

Reason API

Graph API

Parameters

Response

Memory types

Entities and time

Searching over time

Prompt-ready context

Scoping within a space

Latency modes

Error responses

Next steps