Retrieve memories
retrieve_memoriesRead-onlyIdempotent
Retrieve memories by semantic relevance, by date window, or both. Returns
episodes, facts, working memory, concepts, procedures and perceptions,
each in its own list. For a single call that also aggregates entities and
hypotheses on a topic, use cognitive_query.
With `query`, results are ranked by relevance, blended with usage (for
episodes) and confidence (for facts). Without `query`, episodes come newest
first and facts highest confidence first. Retrieval records usage: each
returned episode's importance score rises slightly (so frequently used
memories rank higher later), and returned facts get their access count
updated. Superseded memories are still returned, with the correction
attached in `superseded_por`.
The response always includes:
- `totals`: matches per type within the relevance threshold, before
limit/offset; use `offset` to page through the rest.
- `tipos_consultados`: the memory types actually queried.
- `ventana`: the date window applied ({inicio, fin, origen, etiqueta}).
`origen: "inferida"` means a Spanish recency phrase in the query (such
as "acabo de" or "hace un rato") narrowed the search to the last 24 hours;
pass time_range="all_time" to disable that.
Args:
query: Natural-language description of what to retrieve. Optional:
without it and with a date window, the result is that window
unranked.
entity_id: Restrict to memories linked to this entity UUID.
memory_types: Types to query; omit for all. Values: 'episodic',
'semantic', 'working', 'conceptual', 'procedural', 'perception'
(the response field names such as 'episodes' and 'facts' are
also accepted). An unknown value returns 422 with the accepted values.
limit: Total budget, split evenly across the queried types
(limit // number of types). Default 50, i.e. about 8 items per
type when all six are queried.
offset: Skip the first N episodes/facts to get the next page.
session_id: Include this session's working memory. Without it,
`working_memory` is empty.
time_range: Window label. Calendar days in the user's time zone:
'today', 'yesterday', 'this_week', 'last_week', 'this_month',
'last_month', 'this_year' (Spanish equivalents such as 'hoy',
'ayer', 'anteayer' are also accepted). Rolling: 'last_1h',
'last_6h', 'last_12h', 'last_24h', 'last_48h', 'last_72h',
'last_7d', 'last_14d', 'last_30d', 'last_90d', 'last_180d',
'last_365d'. Unbounded: 'all_time'. An unknown label returns 422.
since: Inclusive ISO-8601 lower bound, e.g. '2026-08-01' or
'2026-08-01T14:30:00'. A date without time starts at 00:00.
until: Inclusive ISO-8601 upper bound. A date without time ends at
the end of that day. `since` later than `until` returns 422.
`time_range` and `since`/`until` are mutually exclusive; combining them
returns 422. The window applies to every memory type: episodes by when
they happened, facts by when they were stored, perceptions by when they
were measured.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| query | No | ||
| since | No | ||
| until | No | ||
| offset | No | ||
| entity_id | No | ||
| session_id | No | ||
| time_range | No | ||
| memory_types | No |