Read Memory

Natural language or semantic query.

Maximum number of items to return. Cap raised from 100 to 500 for benchmark k-sweep (k=200 cells). Per-call rate-limit policy still applies; downstream cost scales linearly.

Optional domain filter (null = all domains).

Minimum relevance score threshold.

Optional fingerprint for O(1) episodic exact match.

Whether to expand results via Hebbian concept associations.

Per-request override for two-pass retrieval. null = use engine config default (Settings.two_pass_enabled). Forwarded to ReadRequest.two_pass; consumed by memory_engine._gate at line 1775.

Per-request override for retrieval strategy. null = engine default (no override). 'auto' triggers the LLM classifier → heuristic fallback (memory_engine.py:1739). Named values ('precise', 'multi_hop', 'temporal', 'exhaustive') resolve via STRATEGY_CATALOG. Anything else returns 422 from FastAPI before reaching the engine.

Opt-in per-phase timing dict on the response (TRACING_SPEC §2): phase wall-times in ms (embed_query_ms, vector_search_ms, db_touch_ms, ...) plus n_embed_calls / n_vector_searches / n_db_roundtrips counters. Off by default so the response payload is unchanged for existing clients; the server-side read_completed log line carries the same dict regardless.

Result ordering. 'relevance' (default) = engine ranking, unchanged. 'recency' = stable re-sort of the final assembled result by created_at DESC (items without a stored timestamp sort last); list length and channel composition are unchanged. This still passes the semantic gate — a pure newest-first feed is #404 R5, a separate endpoint.

Only return items created at or after this ISO-8601 instant (inclusive). Naive datetimes are interpreted as UTC. Applied as an engine post-filter on the assembled result (same placement as the authorship filters): items without a stored timestamp are excluded, and the page may return fewer than top_k when the bound excludes candidates — the queryless feed (#404 R5) is the complete view.

Only return items created at or before this ISO-8601 instant (inclusive). Same UTC/naive, missing-timestamp, and post-filter semantics as since. Must be >= since when both are set (422 otherwise).

Drop items whose provenance.principal equals this value — the 'everyone but me' read in shared rooms (#404 R4). Complement of author_principal; the two may combine. Same post-filter semantics as since.

Return superseded revisions alongside live ones; each carries superseded_by, and every item carries supersedes when it replaced something. History is returned in the domain where each revision is stored: a read scoped to the successor's domain does not include a cross-domain predecessor — use an unscoped read or GET /memory/atoms/{id}. History items compete under normal ranking, min_relevance and top_k/limit — include_history grants eligibility, not chain completeness; for the chain itself use GET /memory/atoms/{id}/chain, which spends a 64-LOOKUP budget per call (resolved revisions AND dangling-pointer misses both count) and sets truncated when the budget ran out — so truncated means the walk stopped early, not that the chain necessarily holds more than 64 revisions. One exception to the domain rule above: when a fingerprint matches a revision that has been replaced, the live tip is returned alongside it even if that tip lives in another domain — the episodic index is domain-blind, and this makes it two atoms rather than one. No effect until the read-side supersession filter is enabled (nothing is hidden before then, so nothing needs unhiding), and inert for xroom:<room_id> domains, whose atoms cannot be superseded at all.

0 (default) leaves the ranking as it is: the ranked candidates are cut to top_k. A value above 0 turns the cut into a maximal marginal relevance selection: items are picked one at a time, each the one that best trades its relevance against its cosine similarity to the items already picked (weight diversity on the similarity, 1 - diversity on relevance), so a near-copy of something already in the answer loses its slot to the next distinct item. 1 means similarity alone decides after the first pick. Applied after outcome feedback and recency have re-ranked, on the ranked pool of up to 200 candidates that cleared min_relevance, and only when top_k is below 200 (at 200 or more the plain cut applies); pinned fingerprint revisions and the association-reserved slots are unchanged. It changes which items are returned, not their scores.

Only return atoms written by this principal.

Only return atoms written by this agent id.

Only return atoms written from this client env (cursor·claude·chatgpt·chat·api·unknown).

Filter by authorship class: true = external only, false = internal only, null = no filter.

True if an exact episodic (fingerprint) match was found.

Search duration in milliseconds.