Reading memories

One-call LLM context

POST/api/v1/memory/recall

In the SDKs: recall

Short-term turns + long-term matches + surrounding context in one bounded call.

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 the account default is used.

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

query string required
limit integer 5–20 · default 10

Long-term memories to recall. Out of range is refused, not clamped — asking for 20 and silently getting 10 reads as "that is all there is".

context_limit integer 0–20 · default 10

How much surrounding context is attached around the best match. 0 attaches none.

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.

Returns

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

short_term object
long_term object
long_term.memories Memory[]
long_term.count integer
context object

Example

cURL
curl -X POST https://api.wontopos.com/api/v1/memory/recall \
  -H "X-API-Key: $WOS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"user_id":"alice","query":"what should I know before I reply?"}'

Status codes

StatusMeaning
200Success.
401Missing or invalid API key.
404Store (user_id) does not exist. Create it first: POST /api/v1/memory/collection.
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.