Where did you hear about us?
1 of 6
Reading memories

Search memories

POST/api/v1/memory/search

In the SDKs: search · search_full · search_self

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.

Authentication

Every call carries your API key in an X-API-Key header. Keys are created in the console.

X-WOS-Modeloptional

Picks the memory model that answers. Omit it and Tablet 2 answers.

Request body

JSON, required. Out-of-range values are refused with a 400 rather than quietly clamped.

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 5–20

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.

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.

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 0–5 · default 1

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 0–3 · default 0

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.

Returns

The 200 body. Fields nested one level are shown as parent.child.

memories Memory[]
memories.id string
memories.content string
memories.category string

Category of the memory, e.g. "general".

memories.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.

memories.importance number

How much weight this memory carries, as the engine assigned it.

memories.time_bucket string

Month bucket, e.g. "2026-07". Omitted when temporal fields are stripped.

memories.is_superseded boolean

True if a later memory has superseded this one.

memories.superseded_by string,null

Id of the memory that superseded this one, or null.

memories.created_at string

When the memory was stored (RFC3339). Omitted when temporal fields are stripped.

memories.event_date string

When the content actually happened (RFC3339), if known.

memories.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.

Example

cURL
curl -X POST https://api.wontopos.com/api/v1/memory/search \
  -H "X-API-Key: $WOS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"user_id":"alice","query":"what does alice drink?","max_results":10}'

Status codes

StatusMeaning
200Success.
400verify 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.
401Missing or invalid API key.
403verify 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.
404Store does not exist — or the speaker filter names an unregistered person.
429Rate limited (per-account, per-tier RPM). Retry after the indicated delay.

Rate limits per tier and the full status list are in Errors & limits.

In the SDKs

The Python, TypeScript, and Rust SDKs wrap this endpoint so you do not build the request by hand — pip install wontopos, npm i wontopos, or cargo add wontopos, then the method list is on the SDK reference. A coding agent can take the whole API in one file at llms.txt, or over MCP with npx -y wontopos-mcp.