Agent API

状态与记忆

store、previous_response_id、session_id 与数据留存在 Agent API 上如何组合。

两个相互独立的开关决定什么被持久化：

store 与 retention 正交，一个管对话，一个管数据面：

开关	作用于	取值	管什么
`store`	`POST /v1/responses`	`true`（默认）/ `false`	响应对象 + 对话线程是否持久化：`store=true` 保留 30 天（绑定 `session_id` 则永久），从而支持 `previous_response_id` 链式续聊与 `GET /v1/responses/{id}`。`store=false` 则回复结束后什么都不留。
`retention`	`POST /v1/data`、`POST /v1/files`、`POST /v1/standardize`（`store=true` 时）	`permanent`（别名 `persistent`）/ `1d` / `6h` / `2h` / `1h` / `session`	你写入的健康记录 / 文件在 Subject 存储中的存活时长。时间粒度自动删除（硬上限 ≤ 24h）；`session` 把记录绑定到 `session_id`，`DELETE /v1/sessions/{id}` 可立即清除。

retention 管理显式的数据面写入，不管理存储对话。store=true 的对话还可能从内容中抽取出健康记录与持久记忆，这些记录用 DELETE /v1/data 删除，或直接删除该 Subject。store=false 的对话则不会产生任何此类数据。

对话状态（`store`）

store 默认 true（对齐 OpenAI）。一个被存储的响应持久化三项内容：响应对象（供 GET /v1/responses/{id}）、对话线程（供 previous_response_id 续接），以及该轮次给平台对话记忆贡献的内容。

模式	方式	生命周期
一次性	`store: false`	回复结束后什么都不留。仍可通过无状态回放实现多轮。
链式	`store: true`（默认），用 `previous_response_id` 续接	每个响应 30 天 TTL；过期后 GET 返回 `404` 且无法续接。
永续对话	传 `session_id`	绑定的响应永不自动过期。同一 `session_id` 总能恢复同一段对话：这是「用户的常驻线程」的稳定句柄。

# 第 1 轮 —— 默认即存储
r1 = client.responses.create(model="mirobody-flash",
                             input="How is my fasting glucose trending?", user="alice")

# 第 2 轮 —— 服务端状态：无需重发历史
r2 = client.responses.create(model="mirobody-flash",
                             input="And compared with last quarter?",
                             previous_response_id=r1.id, user="alice")

清理

DELETE /v1/responses/{id} 总会移除指定的存储响应。只有当它是所在对话的最后一个存活响应时，平台才会拆除对话历史并回撤对话衍生的记忆。见 Agent API → 删除。

跨会话记忆

存储的对话让 agent 记住关于某个 Subject 的持久事实，并在此后的对话中沿用。store: false 的轮次完全置身事外。删除一段对话的最后一个存活响应，才会回撤该对话衍生的记忆；线程中仍有其他响应时，删除较早响应不会回撤共享记忆。

写日记（Journaling）

一条主观日记（比如*「头疼一下午，喝了两杯咖啡后缓解」*）就是一次单轮 POST /v1/responses，带 store: true。不需要专用端点：本页讲的这些开关组合起来就是配方。为每条记录分配独立的 session_id（如 journal-{entry_id}），使其不受 30 天 TTL 约束，并可独立删除。builtin_tools: "none" 加上要求单句确认的 instructions，把你并不消费的回复成本压到最低：

curl -s https://api.mirobody.ai/v1/responses \
  -H "Authorization: Bearer $MIROBODY_API_KEY" -d '{
  "input": "头疼一下午，喝了两杯咖啡后缓解",
  "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."
}'

接下来的一切都是平台的标准流程：

指标与记忆会自动为你抽出。 Mirobody 会在写入后不久从这条存储条目中抽出可量化指标与持久记忆，与回复本身无关。
单条回看用 GET /v1/responses/{id}。不提供列表端点（对齐 OpenAI），请在你自己一侧维护 (记录 → response_id) 索引。平台是数据/智能层，不是笔记应用。
删除单条记录：调用 DELETE /v1/responses/{id}。采用推荐的「每个 session_id 仅一个响应」设计时，该响应就是对话的最后一个存活响应，其对话衍生记忆也会被回撤。若多个响应共用同一 session_id，需将其全部删除后，共享记忆才会被回撤。
删除会话范围的工作数据：调用 DELETE /v1/sessions/{id}。此调用不会删除存储响应对象。
擦除 Subject：调用 DELETE /v1/subjects/{user}。
一个细节：已经抽取进数据面的读数是普通记录，删除日记条目只会回撤记忆，这些读数仍会保留；用 DELETE /v1/data（按 id 或 indicator）或 Subject 级擦除来移除。

数据面留存（`retention`）

健康记录与文件带有自己的生命周期，设置位置就在数据写入处：POST /v1/data（必填）、POST /v1/files（可选）、POST /v1/standardize（store=true 时必填）。

`retention`	生命周期
`permanent`（别名 `persistent`）	直到显式删除（`DELETE /v1/data`、`DELETE /v1/files/{key}`、`DELETE /v1/subjects/{user}`）
`1d` / `6h` / `2h` / `1h`	按粒度自动过期：过期记录立即从读取中消失，随后被永久删除
`session`	绑定 `session_id`；由 `DELETE /v1/sessions/{id}` 清除

没有 retention: "none"：写入存储却要求不存储是自相矛盾的。用完即弃的分析请用 POST /v1/standardize 的 store=false（dry-run，零副作用），以 retention: "1h" 写入（自动过期），或使用 retention: "session" 并在用完后删除该会话。

常见用法

目标	设置
完全短暂的一次调用	`store: false`；不写数据（或以 `retention: "1h"` 写入，或用 `retention: "session"`，事后删除会话）
用户的常驻助手线程	每轮都传 `session_id: <稳定 id>`；数据用 `retention: "permanent"`
用户的日记	每条单轮 `store: true` + 独立的 `session_id: journal-{entry_id}`，见写日记（Journaling）
短生命周期的分诊对话	默认 `store: true` + `previous_response_id` 链式；工作数据 `retention: "session"` + 同一 `session_id`；结束时删除存储响应 id，再调用 `DELETE /v1/sessions/{id}`
被遗忘权	`DELETE /v1/subjects/{user}`：一切，包括存储的对话；或按件：`DELETE /v1/data` / `DELETE /v1/files/{key}` / `DELETE /v1/responses/{id}`

另见

Agent API（Responses）：store 所属的端点。
数据生命周期：删除已存响应与 Subject。
结构化记录：数据写入处设置的 retention。