Engrams

Run an engram

POST/api/v1/engram/run

In the SDKs: engram

Built-in multi-hop retrieval in one call. Call GET /api/v1/engram for the catalog the selected model can run, with a description of each. Available: deep_recall, timeline, equilibrium, tone_stabilizer, gather. Input is billed per engine hop the engram performs, output by what it returns.

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

name "deep_recall" | "timeline" | "equilibrium" | "tone_stabilizer" | "gather" required
query string required
form string

Delivery form (model-dependent; see GET /api/v1/engram).

tz integer

UTC offset hours for time-aware forms.

Returns

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

engram string
form string
user_id string
hops integer
count integer
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.

usage Usage

Example

cURL
curl -X POST https://api.wontopos.com/api/v1/engram/run \
  -H "X-API-Key: $WOS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

Status codes

StatusMeaning
200Success.
400Unknown engram name, or the selected model cannot run it.
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.