v1

latestOpenAPI 3.1.0Apache-2.02026-07-17586455.2 KB
Memories

Full semantic search with optional temporal / retrieval-mode / token-budget controls.

post/v1/memories/search

Request body

agent_idstring

Optional agent identifier. Silently dropped if empty / non-string.

as_ofstring date-time

ISO-8601 timestamp accepted by temporal search (as_of). Empty string or null means absent; any other non-ISO value is rejected with 400.

config_overrideobject

Optional per-request overlay on RuntimeConfig. Keys correspond to RuntimeConfig field names; values must be primitives (boolean / number / string / null). Unknown keys are accepted but surfaced via the X-Atomicmem-Unknown-Override-Keys response header and a server-side warning log — they do not cause a 400. Scope: just this request — no server mutation.

limitinteger
namespace_scopestring
querystring required

Required. query.

retrieval_mode'flat' | 'tiered' | 'abstract-aware'
session_idstring

Optional thread/session identifier used to scope ingest, search, and list symmetrically.

skip_repairboolean
source_sitestring
thresholdnumber

Optional normalized relevance threshold. Results below this semantic relevance floor are excluded before injection packaging.

token_budgetinteger
user_idstring required

Required. user_id.

visibility'agent_only' | 'restricted' | 'workspace'

Visibility (one of agent_only / restricted / workspace). Invalid values silently drop to undefined.

workspace_idstring

Optional workspace identifier. Silently dropped if empty / non-string.

Example request

{
  "as_of": "2026-01-15T12:00:00Z"
}

Response

Search results with injection_text and citations.

budget_constrainedboolean required
citationsstring[]
countnumber required
deterministicboolean

True only on the LLM-free /search/fast path: no LLM call is made, so the result is replayable given the pinned embedding model in the retrieval receipt. /search reports false because it may run the LLM repair/rerank loop.

estimated_context_tokensnumber
expand_idsstring[]
injection_textstring
retrieval_mode'flat' | 'tiered' | 'abstract-aware' required
specialist_answerstring