---
title: "Search memories"
method: POST
path: "/api/v1/memory/search"
tags: ["memory"]
---

# Search memories

`POST /api/v1/memory/search`

## Request

- Base URL: `https://api.wontopos.com`
- URL: `https://api.wontopos.com/api/v1/memory/search`
- Auth: API key in header `X-API-Key`

Returns `memories`, ordered most useful first. `images` can appear beside it on a model that stores images (one by default; `max_images` sets 0 to 5), `self_memories` on a model that keeps the agent's own words apart, and `verify_used` when you pass `verify` above 0: the number of extra passes that added memories; each is billed for what it added.

In the SDKs, `search()` returns one list: the memories, then the agent's own words, then any image rows, with no id repeated. It does not carry `verify_used`. Use `search_full()` (`searchFull()` in TypeScript) to keep those fields apart.

## Headers

- `X-WOS-Model` string

## Request body

- object
  - `user_id` string, required: The store to operate on. Stores are explicit: create one first or use the built-in "default". Use the id the store was created with: 1-64 ASCII letters, digits, ., _ or -, starting with a letter or digit. Ids that differ only by case name one store.
  - `query` string, required
  - `max_results` integer: How many memories to return. Omitted, Tablet 2 returns 20 and Scroll 1.2 returns 15; the SDKs send 10 unless you pass a count. Out of range is refused, not clamped: asking for 20 and silently getting 10 reads as "that is all there is".
  - `speaker` string: Recall only this person’s words ("me" or a registered name). Unregistered → 404.
  - `cache_control` object: Opt-in recall caching: first call writes the cache (billed 2x query tokens for 5m TTL, 3x for 1h), the same query again within the TTL bills 0.1x; one that extends the cached query bills 0.1x for its cached part, the write rate for the new part and the normal rate for its results. One cached query per store, model and set of options: a different query replaces it. Any write to the store invalidates instantly.
    - `ttl` '5m' | '1h'
  - `filters` object: Narrow the search to part of the store. A narrow filter can return fewer than `max_results` even when the store holds more inside it. Filtering behaves identically in every language. Unlisted keys are dropped rather than rejected — a typo silently widens the search. Filters apply to `memories`; `self_memories` is not filtered.
    - `categories` string[]: Only these categories (the `category` you see on /list results).
    - `event_from` string: WHEN THE CONTENT HAPPENED (metadata.event_date), not when it was written — usually the one you want; a memory without one is matched by when it was written. RFC3339, or a plain YYYY-MM-DD.
    - `event_to` string: Upper bound of the same event-date window.
    - `time_from` string: Ingestion-time window, matched as given.
    - `time_to` string: Upper bound of the ingestion-time window.
    - `min_importance` number: Drop matches the engine scored below this importance (0–1).
  - `form` 'memoir' | 'archive': Render each returned memory’s time in this form (Scroll 1.2 and newer; HTTP header equivalent: X-WOS-Form). An unknown form is a 400.
  - `tz` integer: UTC offset in hours, used only while a `form` renders the times.
  - `max_images` integer: How many image memories the answer may carry. 0 asks for none. Out of range is refused, not clamped — silently cutting 5 to 1 would leave you believing you got five. Requires an image-capable model; an older one is refused rather than answering with no images.
  - `verify` integer: Memory verification passes. After the first retrieval, ask the engine again up to this many times, each time telling it what was already returned so it skips those and reaches further back. Raising it adds no language model call. Each pass is one more engine call and can add up to `max_results` more memories, so it costs more — you are billed for what is delivered. Stops early when a pass finds nothing new. Default 0, so existing calls are unchanged. Higher values help most on questions that need several distinct memories from far apart in the history; they do little on a single-fact lookup.

## Response `200`

Success.

- object
  - `memories` Memory[]
    - `id` string, uuid
    - `content` string
    - `category` string: Category of the memory, e.g. "general".
    - `similarity` number: How close this memory is to the query (0–1), higher is closer. It is NOT the ranking key — results already arrive best-first, and ordering by this field instead produces a WORSE order, not the same one. Take `memories` in the order given. There is no `score` field.
    - `importance` number: How much weight this memory carries, as the engine assigned it.
    - `time_bucket` string: Month bucket, e.g. "2026-07". Omitted when temporal fields are stripped.
    - `is_superseded` boolean: True if a later memory has superseded this one.
    - `superseded_by` string, nullable: Id of the memory that superseded this one, or null.
    - `created_at` string, date-time: When the memory was stored (RFC3339). Omitted when temporal fields are stripped.
    - `event_date` string, date-time: When the content actually happened (RFC3339), if known.
    - `speaker` string: WHO said it: "me" (the agent itself) or a registered person. Absent = untagged.
  - `verify_used` integer: Verification passes that added memories. Present only when `verify` above 0 was sent. Lower than requested means a pass found nothing new, or could not run.

## Other responses

- `400`: `verify` outside 0–3, or `max_images` outside 0–5. Refused rather than clamped: a silently reduced value looks like a smaller answer, not a rejected request.
- `401`: Missing or invalid API key.
- `403`: `verify` or `max_images` on a model whose engine cannot serve it (Tablet 2 and newer can). Refused instead of accepted-and-ignored, so you are never billed for passes that did not run or told an image was stored when it was dropped. The message names the model.
- `404`: Store does not exist — or the speaker filter names an unregistered person.
- `429`: Rate limited (per-account, per-tier RPM). Retry after the indicated delay.

---

[API](https://skmtc.dev/wontopos/apis/wontopos-memory-api.md) · [All operations](https://skmtc.dev/wontopos/apis/wontopos-memory-api/llms.txt) · [OpenAPI document](https://skmtc.dev/wontopos/apis/wontopos-memory-api/revisions/48dda7326a33?raw)