离线整理
Markdown 版记忆的离线整理。这些操作只在开启了离线整理的部署上存在。
读取整理报告需要部署开启
GET/v2/memory/dreams/{dream_id}
memory-dreaming)。未开启的部署上它不存在,返回 404。一次离线整理的报告。需要 knowledge:read;请求你不可见的离线整理时,接口返回 404。只在开启了离线整理的部署上存在,其他部署返回 404。
需要的能力 knowledge:read
指南:记忆
参数
响应
200application/jsonDevDream
错误状态
400 401 403 404 422 429 500 503 错误结构见 错误,各错误码的含义见 错误码。
请求示例
curl "https://api.mirabase.dev/v2/memory/dreams/$DREAM_ID" \
-H "Authorization: Bearer $MIRABASE_API_KEY"响应结构示例
{
"id": "<id>",
"space_id": "<space_id>",
"scope": "project",
"status": "queued",
"trigger": "manual",
"created_at": "2026-11-06T00:00:00Z",
"undoable": false,
"counts": {
"dormant_marked": 1
},
"model_tokens": 1
}列出整理动作需要部署开启
GET/v2/memory/dreams/{dream_id}/actions
memory-dreaming)。未开启的部署上它不存在,返回 404。一次离线整理按顺序执行的改动,只包含来源对你可见的记忆。需要 knowledge:read。只在开启了离线整理的部署上存在,其他部署返回 404。
需要的能力 knowledge:read
指南:记忆
参数
| 名称 | 位置 | 类型 | 说明 |
|---|---|---|---|
dream_id必填 | 路径 | DevId | 服务端签发的不透明标识符,客户端按字节比较。长度 1 到 256 |
cursor | 查询 | DevCursor | 上一页的 next_cursor。不传则从第一页开始。长度 1 到 1024 |
limit | 查询 | integer | 每页最多返回的条目数:1 到 100,默认 20。1 到 100,默认 20 |
响应
200application/json
| 字段 | 类型 | 说明 |
|---|---|---|
data必填 | DevDreamAction[] | 这一页的条目。 |
next_cursor | DevCursor | 作为 cursor 传入以获取下一页。最后一页不返回该字段。 |
错误状态
400 401 403 404 422 429 500 503 错误结构见 错误,各错误码的含义见 错误码。
请求示例
curl "https://api.mirabase.dev/v2/memory/dreams/$DREAM_ID/actions" \
-H "Authorization: Bearer $MIRABASE_API_KEY"响应结构示例
{
"data": [
{
"seq": 1,
"memory_id": "<memory_id>",
"entry_id": "<entry_id>",
"action": "dormant",
"reason": "quote_missing",
"state": "applied",
"created_at": "2026-11-06T00:00:00Z"
}
]
}列出整理判定需要部署开启
GET/v2/memory/dreams/{dream_id}/judgments
memory-dreaming)。未开启的部署上它不存在,返回 404。这次离线整理交由模型比较的每一对记忆,最早的在前:生成提案的、仅记录判定的(shadow 设置),以及被丢弃的(discarded,不保留任何文字,只说明原因)。需要 knowledge:read;只有每个成员的来源都对你可见时,你才能看到这条判定。只在开启了离线整理的部署上存在,其他部署返回 404。
需要的能力 knowledge:read
指南:记忆
参数
| 名称 | 位置 | 类型 | 说明 |
|---|---|---|---|
dream_id必填 | 路径 | DevId | 服务端签发的不透明标识符,客户端按字节比较。长度 1 到 256 |
cursor | 查询 | DevCursor | 上一页的 next_cursor。不传则从第一页开始。长度 1 到 1024 |
limit | 查询 | integer | 每页最多返回的条目数:1 到 100,默认 20。1 到 100,默认 20 |
响应
200application/json
| 字段 | 类型 | 说明 |
|---|---|---|
data必填 | DevDreamJudgment[] | 这一页的条目。 |
next_cursor | DevCursor | 作为 cursor 传入以获取下一页。最后一页不返回该字段。 |
错误状态
400 401 403 404 422 429 500 503 错误结构见 错误,各错误码的含义见 错误码。
请求示例
curl "https://api.mirabase.dev/v2/memory/dreams/$DREAM_ID/judgments" \
-H "Authorization: Bearer $MIRABASE_API_KEY"响应结构示例
{
"data": [
{
"id": "<id>",
"dream_id": "<dream_id>",
"outcome": "open",
"member_ids": [
"<member_ids>"
],
"layer": "rule",
"signals": [
"<signals>"
],
"prompt_version": 1,
"cached": false,
"created_at": "2026-11-06T00:00:00Z"
}
]
}撤销整理需要部署开启
POST/v2/memory/dreams/{dream_id}/undo
memory-dreaming)。未开启的部署上它不存在,返回 404。逐条撤销一次已结束的离线整理所做的改动,并返回它的报告;它未处理的提案变成 withdrawn,已批准的 merge 和 supersede 提案会被还原。权限与发起离线整理相同。之后发生变更的记忆(被遗忘、确认、更正、重新提炼,或被后来的离线整理接管)保持不变,计入 conflict_skipped;对已批准的提案,保留的那条记忆发生过变更时也是如此。已遗忘的记忆不会恢复。确认不妨碍撤销 unused 标记。reported 动作未做任何修改,无需撤销。之后的离线整理不会对同一版本的记忆重复执行已撤销的改动(每种原因分别计算),也不会再次对已撤销的那一对记忆提出提案。从离线整理结束起 30 天内可以撤销,如果它的提案最后一次被批准的时间更晚,就从那时算起;从这个时刻起,这个范围又成功完成三次离线整理后也不能再撤销,以先到者为准(之后接口返回 409 conflict);离线整理仍在运行时,接口返回 409 dream_run_in_flight;重复撤销返回同一份报告。只在开启了离线整理的部署上存在,其他部署返回 404。需要 knowledge:write;project 范围还需要 memory:confirm。
需要的能力 knowledge:write
指南:记忆
参数
| 名称 | 位置 | 类型 | 说明 |
|---|---|---|---|
dream_id必填 | 路径 | DevId | 服务端签发的不透明标识符,客户端按字节比较。长度 1 到 256 |
Idempotency-Key | 请求头 | DevIdempotencyKey | Idempotency-Key、主体、API Key、操作和输入都相同时,24 小时内重放原结果。同一个 Idempotency-Key 搭配不同输入时返回 409 conflict。长度 1 到 512 |
请求体
application/json DevEmptyRequest
响应
200application/jsonDevDream
错误状态
400 401 403 404 408 409 410 412 413 415 422 429 500 503 错误结构见 错误,各错误码的含义见 错误码。
请求示例
curl -X POST "https://api.mirabase.dev/v2/memory/dreams/$DREAM_ID/undo" \
-H "Authorization: Bearer $MIRABASE_API_KEY" \
-H "Content-Type: application/json" \
-d '{}'响应结构示例
{
"id": "<id>",
"space_id": "<space_id>",
"scope": "project",
"status": "queued",
"trigger": "manual",
"created_at": "2026-11-06T00:00:00Z",
"undoable": false,
"counts": {
"dormant_marked": 1
},
"model_tokens": 1
}读取整理提案需要部署开启
GET/v2/memory/proposals/{proposal_id}
memory-dreaming)。未开启的部署上它不存在,返回 404。读取一条离线整理提案。需要 knowledge:read;提案对你不可见,或者并非所有成员的来源都对你可见时,接口返回 404。只在开启了离线整理的部署上存在,其他部署返回 404。
需要的能力 knowledge:read
参数
| 名称 | 位置 | 类型 | 说明 |
|---|---|---|---|
proposal_id必填 | 路径 | DevId | 服务端签发的不透明标识符,客户端按字节比较。长度 1 到 256 |
响应
200application/jsonDevMemoryProposal
错误状态
400 401 403 404 422 429 500 503 错误结构见 错误,各错误码的含义见 错误码。
请求示例
curl "https://api.mirabase.dev/v2/memory/proposals/$PROPOSAL_ID" \
-H "Authorization: Bearer $MIRABASE_API_KEY"响应结构示例
{
"id": "<id>",
"space_id": "<space_id>",
"scope": "project",
"dream_id": "<dream_id>",
"kind": "merge",
"member_ids": [
"<member_ids>"
],
"status": "open",
"created_at": "2026-11-06T00:00:00Z"
}批准整理提案需要部署开启
POST/v2/memory/proposals/{proposal_id}/approve
memory-dreaming)。未开启的部署上它不存在,返回 404。执行一条 merge 或 supersede 提案:plan.close 里的记忆被关闭(状态为 superseded),这个范围里表述同一句话的记忆也一起关闭;plan.keep 保留,正文不变。合并会把被关闭记忆的引文加到保留记忆的 provenance,之后遗忘保留的记忆时,并入它的内容也一起遗忘。被关闭的那句话不会再被提炼。执行前先重新核对成员:提案生成之后有成员变更时,提案变成 stale,接口返回 409 proposal_closed;对于任何已经不是 open 的提案,接口也返回这个错误。对于 conflict 和 promote 提案,接口返回 422:矛盾要通过更正或遗忘其中一条记忆来解决,或者驳回提案。权限与 reject 相同。来源正在写入时,接口返回 409 space_busy。如需撤销批准,请撤销该次离线整理(适用条件见 POST /v2/memory/dreams/{dream_id}/undo)。只在开启了离线整理的部署上存在,其他部署返回 404。需要 knowledge:write;project 范围还需要 memory:confirm。
需要的能力 knowledge:write
指南:记忆
参数
| 名称 | 位置 | 类型 | 说明 |
|---|---|---|---|
proposal_id必填 | 路径 | DevId | 服务端签发的不透明标识符,客户端按字节比较。长度 1 到 256 |
Idempotency-Key | 请求头 | DevIdempotencyKey | Idempotency-Key、主体、API Key、操作和输入都相同时,24 小时内重放原结果。同一个 Idempotency-Key 搭配不同输入时返回 409 conflict。长度 1 到 512 |
请求体
application/json DevEmptyRequest
响应
200application/jsonDevMemoryProposal
错误状态
400 401 403 404 408 409 410 412 413 415 422 429 500 503 错误结构见 错误,各错误码的含义见 错误码。
请求示例
curl -X POST "https://api.mirabase.dev/v2/memory/proposals/$PROPOSAL_ID/approve" \
-H "Authorization: Bearer $MIRABASE_API_KEY" \
-H "Content-Type: application/json" \
-d '{}'响应结构示例
{
"id": "<id>",
"space_id": "<space_id>",
"scope": "project",
"dream_id": "<dream_id>",
"kind": "merge",
"member_ids": [
"<member_ids>"
],
"status": "open",
"created_at": "2026-11-06T00:00:00Z"
}驳回整理提案需要部署开启
POST/v2/memory/proposals/{proposal_id}/reject
memory-dreaming)。未开启的部署上它不存在,返回 404。关闭提案,不修改任何记忆;相同的成员不会再为同一种改动被提出。权限与撤销这个范围的离线整理相同:project 范围需要 knowledge:write、memory:confirm 和 editor 角色,调用方不能是 proposal 模式的 Agent(403 proposal_required),也不能在这个 Space 里设有 write_root 或 read_root(403 outside_write_root);agent 范围仅限那个 Agent 自己。用委托授权调用时,接口返回 403。提案已经不是 open 时,接口返回 409 proposal_closed。只在开启了离线整理的部署上存在,其他部署返回 404。
需要的能力 knowledge:write
指南:记忆
参数
| 名称 | 位置 | 类型 | 说明 |
|---|---|---|---|
proposal_id必填 | 路径 | DevId | 服务端签发的不透明标识符,客户端按字节比较。长度 1 到 256 |
Idempotency-Key | 请求头 | DevIdempotencyKey | Idempotency-Key、主体、API Key、操作和输入都相同时,24 小时内重放原结果。同一个 Idempotency-Key 搭配不同输入时返回 409 conflict。长度 1 到 512 |
请求体
application/json DevEmptyRequest
响应
200application/jsonDevMemoryProposal
错误状态
400 401 403 404 408 409 410 412 413 415 422 429 500 503 错误结构见 错误,各错误码的含义见 错误码。
请求示例
curl -X POST "https://api.mirabase.dev/v2/memory/proposals/$PROPOSAL_ID/reject" \
-H "Authorization: Bearer $MIRABASE_API_KEY" \
-H "Content-Type: application/json" \
-d '{}'响应结构示例
{
"id": "<id>",
"space_id": "<space_id>",
"scope": "project",
"dream_id": "<dream_id>",
"kind": "merge",
"member_ids": [
"<member_ids>"
],
"status": "open",
"created_at": "2026-11-06T00:00:00Z"
}列出整理需要部署开启
GET/v2/spaces/{space_id}/memory/dreams
memory-dreaming)。未开启的部署上它不存在,返回 404。这个 Space 的离线整理记录,最新的在前。需要 knowledge:read,且这个 Space 必须对你可见;agent 范围的离线整理只对那个 Agent 和 Space 所有者列出。只在开启了离线整理的部署上存在,其他部署返回 404。
需要的能力 knowledge:read
参数
| 名称 | 位置 | 类型 | 说明 |
|---|---|---|---|
space_id必填 | 路径 | DevSpaceRef | Space id;default 表示你的默认 Space(你自己的默认 Space,否则为唯一可见的 Space);或 ext:<external_id>,表示带有你为它设定的 id 的 Space,例如 ext:user-42。三种写法均可用于路径、?space_id= 和 space_ids。没有可见的 Space 带有该 external_id 时返回 404。长度 1 到 256 |
cursor | 查询 | DevCursor | 上一页的 next_cursor。不传则从第一页开始。长度 1 到 1024 |
limit | 查询 | integer | 每页最多返回的条目数:1 到 100,默认 20。1 到 100,默认 20 |
scope | 查询 | DevDreamScope | 只保留一个范围的离线整理:project 或 agent。 |
status | 查询 | DevDreamStatus | 只保留这个状态的离线整理。 |
响应
200application/json
| 字段 | 类型 | 说明 |
|---|---|---|
data必填 | DevDream[] | 这一页的条目。 |
next_cursor | DevCursor | 作为 cursor 传入以获取下一页。最后一页不返回该字段。 |
错误状态
400 401 403 404 422 429 500 503 错误结构见 错误,各错误码的含义见 错误码。
请求示例
curl "https://api.mirabase.dev/v2/spaces/$SPACE_ID/memory/dreams" \
-H "Authorization: Bearer $MIRABASE_API_KEY"响应结构示例
{
"data": [
{
"id": "<id>",
"space_id": "<space_id>",
"scope": "project",
"status": "queued",
"trigger": "manual",
"created_at": "2026-11-06T00:00:00Z",
"undoable": false,
"counts": {
"dormant_marked": 1
},
"model_tokens": 1
}
]
}发起整理需要部署开启
POST/v2/spaces/{space_id}/memory/dreams
memory-dreaming)。未开启的部署上它不存在,返回 404。立即发起一次整理,总是作为任务:返回 202,带 job_id(即整理 id)和 Location,用 GET /v2/jobs/{job_id} 跟进。某个范围有新记忆时,整理也会自己运行。离线整理会将每条提炼记忆的引文与来源的当前版本核对,引文全部缺失的标为 dormant(quote_missing);人工确认过的记忆(审核通过的候选,或带 memory:confirm 导入的对话中提炼出的记忆)不会因此被标记,已遗忘的记忆不会恢复,且不会跨范围。status: "confirmed" 也包括未经审核即生效的提炼记忆,只有这类记忆会被标为 quote_missing。随后它会查找闲置的提炼记忆(计入 counts.dormancy_candidates):Space 设置为 dormancy: "report"(默认)时仅作报告;设置为 apply 时将它们标为 dormant(unused),再次被取用时被唤醒。规则和偏好不会被标为 unused(quote_missing 仍然适用);人工确认过的记忆不会被标记。project 范围需要 knowledge:write、memory:confirm 和 editor 角色,调用方不能是 proposal 模式的 Agent(返回 403 proposal_required),也不能在该 Space 中设有 write_root 或 read_root(返回 403 outside_write_root);Agent Key 自己的 agent 范围需要 knowledge:write 和 editor。委托授权返回 403。同一范围同时只能有一次整理(409 dream_run_in_flight);Space 设置为 off 时返回 409 dreaming_disabled。只在开启了离线整理的部署上存在,其他部署返回 404。请求体可以不传,与 {} 相同。
需要的能力 knowledge:write
指南:记忆
参数
| 名称 | 位置 | 类型 | 说明 |
|---|---|---|---|
space_id必填 | 路径 | DevSpaceRef | Space id;default 表示你的默认 Space(你自己的默认 Space,否则为唯一可见的 Space);或 ext:<external_id>,表示带有你为它设定的 id 的 Space,例如 ext:user-42。三种写法均可用于路径、?space_id= 和 space_ids。没有可见的 Space 带有该 external_id 时返回 404。长度 1 到 256 |
Idempotency-Key | 请求头 | DevIdempotencyKey | Idempotency-Key、主体、API Key、操作和输入都相同时,24 小时内重放原结果。同一个 Idempotency-Key 搭配不同输入时返回 409 conflict。长度 1 到 512 |
请求体
application/json DevStartDreamRequest
| 字段 | 类型 | 说明 |
|---|---|---|
scope | DevDreamScope | 默认值:Agent Key 为 agent(它自己的私有记忆),其他情况为 project。只有 Agent Key 有 agent 范围;其他调用方指定该值时,接口返回 422。 |
响应
202application/jsonDevJobReceipt
响应头
Location/v2/jobs/{job_id}:轮询它,直到status变成succeeded或failed。
错误状态
400 401 403 404 408 409 410 412 413 415 422 429 500 503 错误结构见 错误,各错误码的含义见 错误码。
请求示例
curl -X POST "https://api.mirabase.dev/v2/spaces/$SPACE_ID/memory/dreams" \
-H "Authorization: Bearer $MIRABASE_API_KEY" \
-H "Content-Type: application/json" \
-d '{}'响应结构示例
{
"job_id": "<job_id>"
}列出整理提案需要部署开启
GET/v2/spaces/{space_id}/memory/proposals
memory-dreaming)。未开启的部署上它不存在,返回 404。这个 Space 的离线整理提案,最早的在前;status 默认为 open,dream_id 将结果限定为某一次离线整理。需要 knowledge:read,且这个 Space 必须对你可见;只有每个成员的来源都对你可见时才列出提案,agent 提案只对那个 Agent 和 Space 所有者列出。只在开启了离线整理的部署上存在,其他部署返回 404。
需要的能力 knowledge:read
参数
| 名称 | 位置 | 类型 | 说明 |
|---|---|---|---|
space_id必填 | 路径 | DevSpaceRef | Space id;default 表示你的默认 Space(你自己的默认 Space,否则为唯一可见的 Space);或 ext:<external_id>,表示带有你为它设定的 id 的 Space,例如 ext:user-42。三种写法均可用于路径、?space_id= 和 space_ids。没有可见的 Space 带有该 external_id 时返回 404。长度 1 到 256 |
cursor | 查询 | DevCursor | 上一页的 next_cursor。不传则从第一页开始。长度 1 到 1024 |
limit | 查询 | integer | 每页最多返回的条目数:1 到 100,默认 20。1 到 100,默认 20 |
status | 查询 | DevMemoryProposalStatus | 只保留这个状态的提案。默认 open。 |
dream_id | 查询 | DevId | 只保留这次离线整理生成的提案。长度 1 到 256 |
响应
200application/json
| 字段 | 类型 | 说明 |
|---|---|---|
data必填 | DevMemoryProposal[] | 这一页的条目。 |
next_cursor | DevCursor | 作为 cursor 传入以获取下一页。最后一页不返回该字段。 |
错误状态
400 401 403 404 422 429 500 503 错误结构见 错误,各错误码的含义见 错误码。
请求示例
curl "https://api.mirabase.dev/v2/spaces/$SPACE_ID/memory/proposals" \
-H "Authorization: Bearer $MIRABASE_API_KEY"响应结构示例
{
"data": [
{
"id": "<id>",
"space_id": "<space_id>",
"scope": "project",
"dream_id": "<dream_id>",
"kind": "merge",
"member_ids": [
"<member_ids>"
],
"status": "open",
"created_at": "2026-11-06T00:00:00Z"
}
]
}读取整理设置需要部署开启
GET/v2/spaces/{space_id}/memory/settings
memory-dreaming)。未开启的部署上它不存在,返回 404。这个 Space 的离线整理设置。需要 knowledge:read,且这个 Space 必须对你可见。只在开启了离线整理的部署上存在,其他部署返回 404。
需要的能力 knowledge:read
参数
| 名称 | 位置 | 类型 | 说明 |
|---|---|---|---|
space_id必填 | 路径 | DevSpaceRef | Space id;default 表示你的默认 Space(你自己的默认 Space,否则为唯一可见的 Space);或 ext:<external_id>,表示带有你为它设定的 id 的 Space,例如 ext:user-42。三种写法均可用于路径、?space_id= 和 space_ids。没有可见的 Space 带有该 external_id 时返回 404。长度 1 到 256 |
响应
200application/jsonDevMemorySettings
错误状态
400 401 403 404 422 429 500 503 错误结构见 错误,各错误码的含义见 错误码。
请求示例
curl "https://api.mirabase.dev/v2/spaces/$SPACE_ID/memory/settings" \
-H "Authorization: Bearer $MIRABASE_API_KEY"响应结构示例
{
"space_id": "<space_id>",
"memory_dreaming": "off",
"dormancy": "report",
"d4": "off"
}修改整理设置需要部署开启
PATCH/v2/spaces/{space_id}/memory/settings
memory-dreaming)。未开启的部署上它不存在,返回 404。需为 Space 所有者并持有 knowledge:manage;委托授权返回 403。off 会停止该 Space 的整理,已执行的变更不会撤销。dormancy 决定未使用的记忆是仅作报告还是标为休眠;改回 report 不会清除已有标记(如需清除,请撤销该次整理)。d4 决定整理是否使用模型比较记忆(可选 off(默认)、shadow、propose);shadow 仅记录判定而不生成提案,切换为 propose 后会直接根据已记录的判定生成提案,不再调用模型。空请求体返回 422。只在开启了离线整理的部署上存在,其他部署返回 404。
需要的能力 knowledge:manage
参数
| 名称 | 位置 | 类型 | 说明 |
|---|---|---|---|
space_id必填 | 路径 | DevSpaceRef | Space id;default 表示你的默认 Space(你自己的默认 Space,否则为唯一可见的 Space);或 ext:<external_id>,表示带有你为它设定的 id 的 Space,例如 ext:user-42。三种写法均可用于路径、?space_id= 和 space_ids。没有可见的 Space 带有该 external_id 时返回 404。长度 1 到 256 |
Idempotency-Key | 请求头 | DevIdempotencyKey | Idempotency-Key、主体、API Key、操作和输入都相同时,24 小时内重放原结果。同一个 Idempotency-Key 搭配不同输入时返回 409 conflict。长度 1 到 512 |
请求体
application/json DevUpdateMemorySettingsRequest 至少传一个字段;未传的字段保持原值。
| 字段 | 类型 | 说明 |
|---|---|---|
memory_dreaming | DevMemoryDreamingMode | auto 在上线前返回 422。 |
dormancy | DevMemoryDormancyMode | 离线整理如何处理闲置的记忆:report(默认)或 apply。 |
d4 | DevMemoryD4Mode | 离线整理是否请模型比较记忆:off(默认)、shadow 或 propose。 |
响应
200application/jsonDevMemorySettings
错误状态
400 401 403 404 408 409 410 412 413 415 422 429 500 503 错误结构见 错误,各错误码的含义见 错误码。
请求示例
curl -X PATCH "https://api.mirabase.dev/v2/spaces/$SPACE_ID/memory/settings" \
-H "Authorization: Bearer $MIRABASE_API_KEY" \
-H "Content-Type: application/json" \
-d '{}'响应结构示例
{
"space_id": "<space_id>",
"memory_dreaming": "off",
"dormancy": "report",
"d4": "off"
}