跳到主要内容
开发者文档
文档目录

离线整理

Markdown 版

记忆的离线整理。这些操作只在开启了离线整理的部署上存在。

读取整理报告需要部署开启

GET/v2/memory/dreams/{dream_id}

这个接口需要部署开启离线整理(memory-dreaming)。未开启的部署上它不存在,返回 404。

一次离线整理的报告。需要 knowledge:read;请求你不可见的离线整理时,接口返回 404。只在开启了离线整理的部署上存在,其他部署返回 404。

需要的能力 knowledge:read

指南:记忆

参数

名称位置类型说明
dream_id必填路径DevId服务端签发的不透明标识符,客户端按字节比较。长度 1 到 256

响应

错误状态

400 401 403 404 422 429 500 503 错误结构见 错误,各错误码的含义见 错误码。

请求示例

curl
curl "https://api.mirabase.dev/v2/memory/dreams/$DREAM_ID" \
  -H "Authorization: Bearer $MIRABASE_API_KEY"

响应结构示例

json
{
  "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

响应

  • 200 application/json
字段类型说明
data必填DevDreamAction[]这一页的条目。
next_cursorDevCursor作为 cursor 传入以获取下一页。最后一页不返回该字段。

错误状态

400 401 403 404 422 429 500 503 错误结构见 错误,各错误码的含义见 错误码。

请求示例

curl
curl "https://api.mirabase.dev/v2/memory/dreams/$DREAM_ID/actions" \
  -H "Authorization: Bearer $MIRABASE_API_KEY"

响应结构示例

json
{
  "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

响应

  • 200 application/json
字段类型说明
data必填DevDreamJudgment[]这一页的条目。
next_cursorDevCursor作为 cursor 传入以获取下一页。最后一页不返回该字段。

错误状态

400 401 403 404 422 429 500 503 错误结构见 错误,各错误码的含义见 错误码。

请求示例

curl
curl "https://api.mirabase.dev/v2/memory/dreams/$DREAM_ID/judgments" \
  -H "Authorization: Bearer $MIRABASE_API_KEY"

响应结构示例

json
{
  "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请求头DevIdempotencyKeyIdempotency-Key、主体、API Key、操作和输入都相同时,24 小时内重放原结果。同一个 Idempotency-Key 搭配不同输入时返回 409 conflict。长度 1 到 512

请求体

application/json DevEmptyRequest

响应

错误状态

400 401 403 404 408 409 410 412 413 415 422 429 500 503 错误结构见 错误,各错误码的含义见 错误码。

请求示例

curl
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 '{}'

响应结构示例

json
{
  "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

响应

错误状态

400 401 403 404 422 429 500 503 错误结构见 错误,各错误码的含义见 错误码。

请求示例

curl
curl "https://api.mirabase.dev/v2/memory/proposals/$PROPOSAL_ID" \
  -H "Authorization: Bearer $MIRABASE_API_KEY"

响应结构示例

json
{
  "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请求头DevIdempotencyKeyIdempotency-Key、主体、API Key、操作和输入都相同时,24 小时内重放原结果。同一个 Idempotency-Key 搭配不同输入时返回 409 conflict。长度 1 到 512

请求体

application/json DevEmptyRequest

响应

错误状态

400 401 403 404 408 409 410 412 413 415 422 429 500 503 错误结构见 错误,各错误码的含义见 错误码。

请求示例

curl
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 '{}'

响应结构示例

json
{
  "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请求头DevIdempotencyKeyIdempotency-Key、主体、API Key、操作和输入都相同时,24 小时内重放原结果。同一个 Idempotency-Key 搭配不同输入时返回 409 conflict。长度 1 到 512

请求体

application/json DevEmptyRequest

响应

错误状态

400 401 403 404 408 409 410 412 413 415 422 429 500 503 错误结构见 错误,各错误码的含义见 错误码。

请求示例

curl
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 '{}'

响应结构示例

json
{
  "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必填路径DevSpaceRefSpace 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只保留这个状态的离线整理。

响应

  • 200 application/json
字段类型说明
data必填DevDream[]这一页的条目。
next_cursorDevCursor作为 cursor 传入以获取下一页。最后一页不返回该字段。

错误状态

400 401 403 404 422 429 500 503 错误结构见 错误,各错误码的含义见 错误码。

请求示例

curl
curl "https://api.mirabase.dev/v2/spaces/$SPACE_ID/memory/dreams" \
  -H "Authorization: Bearer $MIRABASE_API_KEY"

响应结构示例

json
{
  "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必填路径DevSpaceRefSpace 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请求头DevIdempotencyKeyIdempotency-Key、主体、API Key、操作和输入都相同时,24 小时内重放原结果。同一个 Idempotency-Key 搭配不同输入时返回 409 conflict。长度 1 到 512

请求体

application/json DevStartDreamRequest

字段类型说明
scopeDevDreamScope默认值:Agent Key 为 agent(它自己的私有记忆),其他情况为 project。只有 Agent Key 有 agent 范围;其他调用方指定该值时,接口返回 422。

响应

响应头

  • Location /v2/jobs/{job_id}:轮询它,直到 status 变成 succeeded 或 failed。

错误状态

400 401 403 404 408 409 410 412 413 415 422 429 500 503 错误结构见 错误,各错误码的含义见 错误码。

请求示例

curl
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 '{}'

响应结构示例

json
{
  "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必填路径DevSpaceRefSpace 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

响应

  • 200 application/json
字段类型说明
data必填DevMemoryProposal[]这一页的条目。
next_cursorDevCursor作为 cursor 传入以获取下一页。最后一页不返回该字段。

错误状态

400 401 403 404 422 429 500 503 错误结构见 错误,各错误码的含义见 错误码。

请求示例

curl
curl "https://api.mirabase.dev/v2/spaces/$SPACE_ID/memory/proposals" \
  -H "Authorization: Bearer $MIRABASE_API_KEY"

响应结构示例

json
{
  "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必填路径DevSpaceRefSpace id;default 表示你的默认 Space(你自己的默认 Space,否则为唯一可见的 Space);或 ext:<external_id>,表示带有你为它设定的 id 的 Space,例如 ext:user-42。三种写法均可用于路径、?space_id= 和 space_ids。没有可见的 Space 带有该 external_id 时返回 404。长度 1 到 256

响应

错误状态

400 401 403 404 422 429 500 503 错误结构见 错误,各错误码的含义见 错误码。

请求示例

curl
curl "https://api.mirabase.dev/v2/spaces/$SPACE_ID/memory/settings" \
  -H "Authorization: Bearer $MIRABASE_API_KEY"

响应结构示例

json
{
  "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必填路径DevSpaceRefSpace 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请求头DevIdempotencyKeyIdempotency-Key、主体、API Key、操作和输入都相同时,24 小时内重放原结果。同一个 Idempotency-Key 搭配不同输入时返回 409 conflict。长度 1 到 512

请求体

application/json DevUpdateMemorySettingsRequest 至少传一个字段;未传的字段保持原值。

字段类型说明
memory_dreamingDevMemoryDreamingModeauto 在上线前返回 422。
dormancyDevMemoryDormancyMode离线整理如何处理闲置的记忆:report(默认)或 apply。
d4DevMemoryD4Mode离线整理是否请模型比较记忆:off(默认)、shadow 或 propose。

响应

错误状态

400 401 403 404 408 409 410 412 413 415 422 429 500 503 错误结构见 错误,各错误码的含义见 错误码。

请求示例

curl
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 '{}'

响应结构示例

json
{
  "space_id": "<space_id>",
  "memory_dreaming": "off",
  "dormancy": "report",
  "d4": "off"
}