State & Memory - Mirobody

Before copying a curl example, choose your Cloud region. For authenticated calls, it must be the same region as your key. The examples below use MIROBODY_API_BASE:

export MIROBODY_API_BASE="https://api.mirobody.ai/v1"   # Global account
# export MIROBODY_API_BASE="https://api.mirobody.cn/v1" # China account: use this instead

For SDK examples with a literal Global URL, use the matching China URL when your account is in China. See Regions. Two independent knobs govern what persists: store and retention are orthogonal — one governs the conversation, the other governs the data plane:

Knob	Applies to	Values	Governs
`store`	`POST /v1/responses`	`true` (default) / `false`	Whether the response object + conversation thread persist: `store=true` keeps them 30 days (or permanently when bound to a `session_id`), enabling `previous_response_id` chaining and `GET /v1/responses/{id}`. `store=false` keeps nothing after the reply.
`retention`	`POST /v1/data`, `POST /v1/files`, `POST /v1/standardize` (`store=true`)	`permanent` (alias `persistent`) / `1d` / `6h` / `2h` / `1h` / `session`	How long the health records / files you write live in the Subject’s store. Time grains auto-delete (hard-capped ≤ 24h); `session` binds records to a `session_id` and `DELETE /v1/sessions/{id}` purges them.

retention governs explicit data-plane writes; it does not govern a stored conversation. A stored conversation can also produce health records and memories from its content — delete those with DELETE /v1/data, or erase the Subject. store=false conversations produce none.

Conversation state (`store`)

store defaults to true (OpenAI parity). A stored response persists three things: the response object (for GET /v1/responses/{id}), the conversation thread (so previous_response_id can continue it), and what the turn contributes to the platform’s conversation memory.

Mode	How	Lifetime
One-shot	`store: false`	Nothing persists after the reply. Multi-turn still possible via stateless replay.
Chained	`store: true` (default), continue with `previous_response_id`	30-day TTL per response; expired responses `404` on GET and can’t be chained.
Durable conversation	pass `session_id`	Bound responses never auto-expire. The same `session_id` always resumes the same conversation — a stable handle for “the user’s ongoing thread”.

# Turn 1 — stored by default
r1 = client.responses.create(model="mirobody-flash",
                             input="How is my fasting glucose trending?", user="alice")

# Turn 2 — server-side state: no history resend
r2 = client.responses.create(model="mirobody-flash",
                             input="And compared with last quarter?",
                             previous_response_id=r1.id, user="alice")

previous_response_id on an unknown, expired, or deleted response returns 404 — treat a chained conversation older than 30 days as gone unless it was session_id-bound. A response that ended in a client-tool handoff must be continued with function_call_output items first — see Function calling.

Cleanup

DELETE /v1/responses/{id} always removes that stored response. Only when it is the last live response in its conversation does the platform tear down the conversation history and retract conversation-derived memory. See Agent API → Delete.

Cross-session memory

Stored conversations let the agent remember durable facts about a Subject across later conversations. store: false turns stay out of it entirely. Deleting the last live response in a conversation retracts that conversation’s derived memory; deleting an earlier one retracts nothing while other responses in the thread remain.

Journaling

A subjective journal entry — “headache all afternoon, eased after two coffees” — is a single-turn POST /v1/responses with store: true. No dedicated endpoint: the knobs on this page already compose into the recipe. Give each entry its own session_id (for example, journal-{entry_id}) so it never hits the 30-day TTL and can be deleted independently. builtin_tools: "none" plus a short-acknowledgement instructions keeps the reply — which you don’t consume — as cheap as possible:

curl -s "$MIROBODY_API_BASE/responses" \
  -H "Authorization: Bearer $MIROBODY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "input": "Headache all afternoon; eased after two cups of coffee",
  "user": "patient-42",
  "session_id": "journal-entry-018",
  "store": true,
  "builtin_tools": "none",
  "instructions": "The user is journaling, not asking a question. Reply with a single short acknowledgement."
}'

Everything after that is standard:

Indicators and memories are extracted for you. Mirobody pulls any quantifiable indicators and durable memories out of the stored entry shortly after the write, independent of the reply.
Read back a single entry with GET /v1/responses/{id}. There is no list endpoint (OpenAI parity) — keep your own (entry → response_id) index. The platform is the data/intelligence layer, not a note-taking app.
Delete one entry with DELETE /v1/responses/{id}. With the recommended one-response-per-session_id design, that response is the conversation’s last live response, so its conversation-derived memory is also retracted. If several responses share a session_id, the shared memory is retracted only once you delete all of them.
Delete session-scoped working data with DELETE /v1/sessions/{id}. It does not delete stored response objects.
Erase the Subject with DELETE /v1/subjects/{user}.
One nuance: readings already extracted into the data plane are ordinary records — deleting the journal entry retracts memories but leaves those readings; remove them with DELETE /v1/data (by id or indicator) or the Subject-level wipe.

Data-plane retention (`retention`)

Health records and files carry their own lifetime, set where the data is written — POST /v1/data (required), POST /v1/files (optional), POST /v1/standardize (required when store=true):

`retention`	Lifetime
`permanent` (alias `persistent`)	Until explicitly deleted (`DELETE /v1/data`, `DELETE /v1/files/{key}`, `DELETE /v1/subjects/{user}`)
`1d` / `6h` / `2h` / `1h`	Auto-expires after the grain — expired records disappear from reads immediately and are then permanently deleted
`session`	Bound to a `session_id`; purged by `DELETE /v1/sessions/{id}`

There is no retention: "none" — writing to the store while asking not to store is contradictory. For use-and-forget analysis, run POST /v1/standardize with store=false (dry-run, zero side effects), write with retention: "1h" (auto-expires), or use retention: "session" and delete the session when done.

Common patterns

Goal	Settings
Fully ephemeral one-off	`store: false`; don’t write data (or write with `retention: "1h"`, or `retention: "session"` and delete the session after)
A user’s ongoing assistant thread	`session_id: <stable-id>` on every turn; data `retention: "permanent"`
A user’s journal	Single-turn `store: true` + a unique `session_id: journal-{entry_id}` for each entry — see Journaling
Short-lived triage conversation	default `store: true`, chain with `previous_response_id`; working data `retention: "session"` + the same `session_id`; delete the stored response IDs and then `DELETE /v1/sessions/{id}` when done
Right to be forgotten	`DELETE /v1/subjects/{user}` — everything, including stored conversations; or per-piece: `DELETE /v1/data` / `DELETE /v1/files/{key}` / `DELETE /v1/responses/{id}`

​Conversation state (store)

​Cleanup

​Cross-session memory

​Journaling

​Data-plane retention (retention)

​Common patterns

​See also

Conversation state (`store`)

Cleanup

Cross-session memory

Journaling

Data-plane retention (`retention`)

Common patterns

See also