---
title: "Full semantic search with optional temporal / retrieval-mode / token-budget controls."
method: POST
path: "/v1/memories/search"
tags: ["Memories"]
---

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

`POST /v1/memories/search`

## Request body

- object — Search memories. User-scoped unless workspace_id + agent_id are both provided.
  - `agent_id` string — Optional agent identifier. Silently dropped if empty / non-string.
  - `agent_scope` union — Agent-scope filter for workspace searches. String literal 'all' | 'self' | 'others' or a concrete agent_id. Array of agent_ids is also accepted. Any other value is silently ignored.
    - string
    - string[]
  - `as_of` string, 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_override` object — 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.
  - `limit` integer
  - `namespace_scope` string
  - `query` string, required — Required. query.
  - `retrieval_mode` 'flat' | 'tiered' | 'abstract-aware'
  - `session_id` string — Optional thread/session identifier used to scope ingest, search, and list symmetrically.
  - `skip_repair` boolean
  - `source_site` string
  - `threshold` number — Optional normalized relevance threshold. Results below this semantic relevance floor are excluded before injection packaging.
  - `token_budget` integer
  - `user_id` string, required — Required. user_id.
  - `visibility` 'agent_only' | 'restricted' | 'workspace' — Visibility (one of agent_only / restricted / workspace). Invalid values silently drop to undefined.
  - `workspace_id` string — Optional workspace identifier. Silently dropped if empty / non-string.

## Response `200`

Search results with injection_text and citations.

- object — Search results with injection_text, citations, budget_constrained, and optional traces.
  - `budget_constrained` boolean, required
  - `citations` string[]
  - `consensus` object
    - `filtered_count` number, required
    - `original_count` number, required
    - `removed_count` number, required
    - `removed_memory_ids` string[], required
  - `count` number, required
  - `deterministic` boolean — 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_tokens` number
  - `expand_ids` string[]
  - `injection_text` string
  - `lesson_check` object
    - `highest_severity` string, required
    - `matched_count` number, required
    - `safe` boolean, required
    - `warnings` unknown[], required
      - unknown
  - `memories` object[], required
    - `content` string, required
    - `created_at` string
    - `id` string, required
    - `importance` number, nullable
    - `metadata` object — Memory metadata persisted on the row, including caller-supplied verbatim metadata (set via /v1/memories/ingest/quick with skip_extraction=true) and core-generated metadata (e.g. cmo_id, memberMemoryIds, headline). Mirrors the shape /v1/memories/list and /v1/memories/:id return.
    - `observed_at` string — When the memory was observed/recorded. Part of the retrieval receipt.
    - `ranking_score` number, nullable — Composite ranking/debug score. It is not normalized and may be outside the [0,1] relevance range.
    - `relevance` number, nullable — Normalized relevance value used for threshold filtering; clamped to the [0,1] range.
    - `score` number, nullable
    - `semantic_similarity` number, nullable
    - `session_id` string, nullable
    - `similarity` number, nullable
    - `source_site` string
    - `version_id` string, nullable — Owning claim's current_version_id (a claim-version id) for the memory, enabling a client to pin the exact retrieved version as a replay fixture. null when the memory has no claim version (e.g. workspace-pool rows).
  - `observability` object — Retrieval pipeline trace summaries.
    - `assembly` object
      - `blocks` string[], required
      - `final_ids` string[], required
      - `final_token_cost` number, required
      - `primary_evidence_position` number, nullable, required
      - `token_budget` number, nullable, required
    - `packaging` object
      - `date_count` number, required
      - `dropped_ids` string[], required
      - `episode_count` number, required
      - `evidence_roles` object, required
      - `has_conflict_block` boolean, required
      - `has_current_marker` boolean, required
      - `included_ids` string[], required
      - `package_type` 'subject-pack' | 'timeline-pack' | 'tiered', required
      - `token_cost` number, required
    - `retrieval` object
      - `candidate_count` number, required
      - `candidate_ids` string[], required
      - `filter_decisions` object[] — Per-candidate threshold decisions emitted only when retrieval tracing is enabled. Entries include per-result source_site, source_kind, and namespace for debugging disclosure scope.
        - `decision` 'kept' | 'filtered', required
        - `id` string, required
        - `namespace` string, nullable, required
        - `ranking_score` number, required — Composite ranking/debug score. It is not normalized and may be outside the [0,1] relevance range.
        - `reason` string, required
        - `relevance` number, required — Normalized relevance value used for threshold filtering; clamped to the [0,1] range.
        - `semantic_similarity` number, required
        - `source_kind` 'integration' | 'local', required
        - `source_site` string, required
        - `threshold` number, nullable, required
      - `filtered_candidate_ids` string[]
      - `query_text` string, required
      - `relevance_filter_reason` string
      - `relevance_filter_source` string
      - `relevance_threshold` number, nullable
      - `skip_repair` boolean, required
      - `stage_count` number
      - `stage_names` string[]
      - `trace_id` string
  - `retrieval` object, required — Audit-grade retrieval receipt.
    - `candidate_ids` string[], required — Returned memory ids in ranked order.
    - `embedding_dimensions` number, required
    - `embedding_model` string, required
    - `embedding_model_version` string, required — Embedding model version. No supported provider exposes a separate immutable version string, so this is the resolved model id — the most precise model identity the provider reports, never a fabricated value.
    - `embedding_provider` string, required
    - `query_text` string, required
    - `trace_id` string, required
  - `retrieval_mode` 'flat' | 'tiered' | 'abstract-aware', required
  - `scope` union, required — Echoed scope: user-scoped or workspace-scoped.
    - object
      - `kind` 'user', required
      - `user_id` string, required
    - object
      - `agent_id` string, required
      - `agent_scope` unknown
      - `kind` 'workspace', required
      - `user_id` string, required
      - `workspace_id` string, required
  - `specialist_answer` string
  - `tier_assignments` object[]
    - `estimated_tokens` number, required
    - `memory_id` string, required
    - `tier` string, required

## Other responses

- `400` — Input validation error
- `500` — Internal server error
- `502` — Upstream AI provider returned an unrecoverable failure (auth, non-retryable 4xx).
- `503` — Upstream AI provider is rate-limited, quota-exhausted, or returned 5xx; consult `retryable`.

## Changes

- **2026-07-17** `d501daa39bb2` — 5 info
  - added the optional property `deterministic` to the response with the `200` status
  - added the optional property `memories/items/observed_at` to the response with the `200` status
  - added the optional property `memories/items/session_id` to the response with the `200` status
  - added the optional property `memories/items/version_id` to the response with the `200` status
  - …1 more
- **2026-05-18** `457c8928e1ab` — 1 breaking, 4 warning
  - removed the required property `retrieval` from the response with the `200` status
  - removed the optional property `deterministic` from the response with the `200` status
  - removed the optional property `memories/items/observed_at` from the response with the `200` status
  - removed the optional property `memories/items/session_id` from the response with the `200` status
  - …1 more

[Change history](https://skmtc.dev/atomicstrata/apis/atomicmemory-http-api/changes/v1/memories/search/post.md)

---

[API](https://skmtc.dev/atomicstrata/apis/atomicmemory-http-api.md) · [All operations](https://skmtc.dev/atomicstrata/apis/atomicmemory-http-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/atomicstrata/atomicmemory-http-api/revisions/d501daa39bb2/schema)