Search

Search runs inside one collection and returns results ranked by relevance, each carrying a citation back to the memory it came from.

curl -X POST "https://api.zeroset.com/v2/collections/$COLLECTION/memories/search" \
  -H "Authorization: Bearer $NEBULA_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "why are exports slow",
    "retrieval_id": "018f3c2a-8d55-7a21-88bf-6e0d43c9a115",
    "effort": "low"
  }'

The request

Field	Required	Meaning
`query`	yes	Natural-language query, using semantic and lexical retrieval with local graph traversal.
`retrieval_id`	generated	A UUID identifying the retrieval. The clients generate one per call; pass your own and a retry is the same retrieval rather than a second one.
`effort`	no	`auto`, `low`, `medium`, or `high` work allowance; `auto` resolves to `low`. This is not a result-count limit.
`entity_id`	no	A grounded entity identity returned by search. Start local follow-up there, without a global fallback if it is unavailable.
`valid_at`	no	Evaluate fact validity at an RFC 3339 instant with an explicit timezone and millisecond precision or coarser. Defaults to now; does not select an old storage snapshot.
`minimum_confidence`	no	Minimum confidence from `0` to `1`; defaults to `0.1`.
`include_sources`	no	Include full evidence detail for selected results. Defaults to compact provenance (`false`).

The former limit and valid_at_ms fields are rejected. Effort bounds work; it does not guarantee a particular number of results or better answer accuracy.

The response

MemorySearchPage echoes retrieval_id. Its recall contains typed semantic, episodic, procedural, entity, source, workflow and table results, plus execution metadata: behavior version, effective effort, visited count and source-detail mode. Search returns ranked evidence within the requested work allowance, not a claim that every relevant memory has been found. Budget and stop diagnostics remain internal. Use a returned entity id as the next request's entity_id for grounded follow-up.

The compatibility data array groups supporting results by memory. Each hit carries:

memory_id — the memory it came from
summary — what that memory says, in context of the query
excerpt — a bounded source preview or selected evidence quote; may be empty in compact mode
citation — a label, and a uri when one exists
relevance — a score from 0 to 1

Neither array has a separate result-count cutoff. Summaries are retrieved evidence, not a generated final answer. Table results retain typed references and available schema; table observations retain exact row and column coordinates.

Freshness

A memory is searchable only once its store operation reports search_ready. If you store and immediately search, follow the operation first.

Optional warming

Prepare search when a user selects a collection, without submitting a dummy query:

curl -X POST "https://api.zeroset.com/v2/collections/$COLLECTION/warm" \
  -H "Authorization: Bearer $NEBULA_ACCESS_TOKEN"

The read-authorized POST returns HTTP 202. Without a configured serving pool it waits for preparation on the receiving replica, returning scope: "replica", state: "prepared" and ready: true. This provides no replica affinity or retention lease. It omits generation, expires_at_ms and status_url; GET and DELETE return 404 because there is no lease.

With a configured serving pool, POST establishes or renews a time-limited lease and returns scope: "pool" with its current state and status_url. Follow that URL with GET; only state: "prepared" sets ready: true. An optional wait_ms (at most 10,000) waits for pool preparation, but a timeout does not imply readiness or cancel accepted work. DELETE revokes the lease and requires collection-management permission. Automatic POST retries are disabled.

Pool preparation covers the serving readers and is inherited by replacements. Failed leases and obsolete placements report ready: false without preventing replacement readers from serving; current active leases still gate admission. Preparation does not call the query-embedding provider or run retrieval, and readiness does not guarantee a search deadline or complete results. Every search still checks freshness and authority and can prepare on demand. Expiry releases warm retention; publication changes remain authoritative. Follow the store operation separately for ingestion completion.