memory

Search memories

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.

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

Headers

X-WOS-Modelstring

Which engine reads the memory (see GET /api/v1/models). All live models share one memory per workspace, so you can store with one and recall with another. A retired model answers 410 with error.type gone_error and error.code 0, except on DELETE /api/v1/memory/collection, which deletes the store under any model. Until then, a model scheduled to retire names the day in a Sunset header (RFC 8594) on every answer it serves, the same date GET /api/v1/models lists as retires_at.

Request body

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

querystring required
max_resultsinteger

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

speakerstring

Recall only this person’s words ("me" or a registered name). Unregistered → 404.

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.

tzinteger

UTC offset in hours, used only while a form renders the times.

max_imagesinteger

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.

verifyinteger

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

Success.

verify_usedinteger

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.

Changes

No recorded changes to this operation across all 1 revision of this API.