# 离线整理

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

API 参考。Base URL：`https://api.mirabase.dev`

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

`GET /v2/memory/dreams/{dream_id}`

> 这个接口需要部署开启离线整理（`memory-dreaming`）。未开启的部署上它不存在，返回 404。

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

**需要的能力** `knowledge:read`

指南：[记忆](https://mirabase.io/zh/developers/memory.md#dreams)

### 参数

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

### 响应

- `200` `application/json` `DevDream`

### 错误状态

`400` `401` `403` `404` `422` `429` `500` `503` 错误结构见 [错误](https://mirabase.io/zh/developers/conventions.md#errors)，各错误码的含义见 [错误码](https://mirabase.io/zh/developers/errors.md)。

### 请求示例

```bash
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`

指南：[记忆](https://mirabase.io/zh/developers/memory.md#dreams)

### 参数

| 名称 | 位置 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- | --- |
| `dream_id` | 路径 | `DevId` | 必填 | 服务端签发的不透明标识符，客户端按字节比较。 长度 1 到 256 |
| `cursor` | 查询 | `DevCursor` | 可选 | 上一页的 `next_cursor`。不传则从第一页开始。 长度 1 到 1024 |
| `limit` | 查询 | `integer` | 可选 | 每页最多返回的条目数：1 到 100，默认 20。 1 到 100，默认 20 |

### 响应

- `200` `application/json`

200 响应：

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `data` | `DevDreamAction[]` | 必填 | 这一页的条目。 |
| `next_cursor` | `DevCursor` | 可选 | 作为 `cursor` 传入以获取下一页。最后一页不返回该字段。 |

### 错误状态

`400` `401` `403` `404` `422` `429` `500` `503` 错误结构见 [错误](https://mirabase.io/zh/developers/conventions.md#errors)，各错误码的含义见 [错误码](https://mirabase.io/zh/developers/errors.md)。

### 请求示例

```bash
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`

指南：[记忆](https://mirabase.io/zh/developers/memory.md#dreams)

### 参数

| 名称 | 位置 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- | --- |
| `dream_id` | 路径 | `DevId` | 必填 | 服务端签发的不透明标识符，客户端按字节比较。 长度 1 到 256 |
| `cursor` | 查询 | `DevCursor` | 可选 | 上一页的 `next_cursor`。不传则从第一页开始。 长度 1 到 1024 |
| `limit` | 查询 | `integer` | 可选 | 每页最多返回的条目数：1 到 100，默认 20。 1 到 100，默认 20 |

### 响应

- `200` `application/json`

200 响应：

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `data` | `DevDreamJudgment[]` | 必填 | 这一页的条目。 |
| `next_cursor` | `DevCursor` | 可选 | 作为 `cursor` 传入以获取下一页。最后一页不返回该字段。 |

### 错误状态

`400` `401` `403` `404` `422` `429` `500` `503` 错误结构见 [错误](https://mirabase.io/zh/developers/conventions.md#errors)，各错误码的含义见 [错误码](https://mirabase.io/zh/developers/errors.md)。

### 请求示例

```bash
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`

指南：[记忆](https://mirabase.io/zh/developers/memory.md#dreams)

### 参数

| 名称 | 位置 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- | --- |
| `dream_id` | 路径 | `DevId` | 必填 | 服务端签发的不透明标识符，客户端按字节比较。 长度 1 到 256 |
| `Idempotency-Key` | 请求头 | `DevIdempotencyKey` | 可选 | `Idempotency-Key`、主体、API Key、操作和输入都相同时，24 小时内重放原结果。同一个 `Idempotency-Key` 搭配不同输入时返回 409 `conflict`。 长度 1 到 512 |

### 请求体

`application/json` `DevEmptyRequest`

### 响应

- `200` `application/json` `DevDream`

### 错误状态

`400` `401` `403` `404` `408` `409` `410` `412` `413` `415` `422` `429` `500` `503` 错误结构见 [错误](https://mirabase.io/zh/developers/conventions.md#errors)，各错误码的含义见 [错误码](https://mirabase.io/zh/developers/errors.md)。

### 请求示例

```bash
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 |

### 响应

- `200` `application/json` `DevMemoryProposal`

### 错误状态

`400` `401` `403` `404` `422` `429` `500` `503` 错误结构见 [错误](https://mirabase.io/zh/developers/conventions.md#errors)，各错误码的含义见 [错误码](https://mirabase.io/zh/developers/errors.md)。

### 请求示例

```bash
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`](https://mirabase.io/zh/developers/api/memory-dreaming.md#memorydreams-undo)）。只在开启了离线整理的部署上存在，其他部署返回 404。需要 `knowledge:write`；`project` 范围还需要 `memory:confirm`。

**需要的能力** `knowledge:write`

指南：[记忆](https://mirabase.io/zh/developers/memory.md#memory-proposals)

### 参数

| 名称 | 位置 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- | --- |
| `proposal_id` | 路径 | `DevId` | 必填 | 服务端签发的不透明标识符，客户端按字节比较。 长度 1 到 256 |
| `Idempotency-Key` | 请求头 | `DevIdempotencyKey` | 可选 | `Idempotency-Key`、主体、API Key、操作和输入都相同时，24 小时内重放原结果。同一个 `Idempotency-Key` 搭配不同输入时返回 409 `conflict`。 长度 1 到 512 |

### 请求体

`application/json` `DevEmptyRequest`

### 响应

- `200` `application/json` `DevMemoryProposal`

### 错误状态

`400` `401` `403` `404` `408` `409` `410` `412` `413` `415` `422` `429` `500` `503` 错误结构见 [错误](https://mirabase.io/zh/developers/conventions.md#errors)，各错误码的含义见 [错误码](https://mirabase.io/zh/developers/errors.md)。

### 请求示例

```bash
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`

指南：[记忆](https://mirabase.io/zh/developers/memory.md#memory-proposals)

### 参数

| 名称 | 位置 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- | --- |
| `proposal_id` | 路径 | `DevId` | 必填 | 服务端签发的不透明标识符，客户端按字节比较。 长度 1 到 256 |
| `Idempotency-Key` | 请求头 | `DevIdempotencyKey` | 可选 | `Idempotency-Key`、主体、API Key、操作和输入都相同时，24 小时内重放原结果。同一个 `Idempotency-Key` 搭配不同输入时返回 409 `conflict`。 长度 1 到 512 |

### 请求体

`application/json` `DevEmptyRequest`

### 响应

- `200` `application/json` `DevMemoryProposal`

### 错误状态

`400` `401` `403` `404` `408` `409` `410` `412` `413` `415` `422` `429` `500` `503` 错误结构见 [错误](https://mirabase.io/zh/developers/conventions.md#errors)，各错误码的含义见 [错误码](https://mirabase.io/zh/developers/errors.md)。

### 请求示例

```bash
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` | 路径 | `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` | 可选 | 只保留这个状态的离线整理。 |

### 响应

- `200` `application/json`

200 响应：

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `data` | `DevDream[]` | 必填 | 这一页的条目。 |
| `next_cursor` | `DevCursor` | 可选 | 作为 `cursor` 传入以获取下一页。最后一页不返回该字段。 |

### 错误状态

`400` `401` `403` `404` `422` `429` `500` `503` 错误结构见 [错误](https://mirabase.io/zh/developers/conventions.md#errors)，各错误码的含义见 [错误码](https://mirabase.io/zh/developers/errors.md)。

### 请求示例

```bash
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}`](https://mirabase.io/zh/developers/api/jobs.md#jobs-read) 跟进。某个范围有新记忆时，整理也会自己运行。离线整理会将每条提炼记忆的引文与来源的当前版本核对，引文全部缺失的标为 `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`

指南：[记忆](https://mirabase.io/zh/developers/memory.md#dreams)

### 参数

| 名称 | 位置 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- | --- |
| `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。 |

### 响应

- `202` `application/json` `DevJobReceipt`

### 响应头

- `Location` `/v2/jobs/{job_id}`：轮询它，直到 `status` 变成 `succeeded` 或 `failed`。

### 错误状态

`400` `401` `403` `404` `408` `409` `410` `412` `413` `415` `422` `429` `500` `503` 错误结构见 [错误](https://mirabase.io/zh/developers/conventions.md#errors)，各错误码的含义见 [错误码](https://mirabase.io/zh/developers/errors.md)。

### 请求示例

```bash
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` | 路径 | `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 |

### 响应

- `200` `application/json`

200 响应：

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `data` | `DevMemoryProposal[]` | 必填 | 这一页的条目。 |
| `next_cursor` | `DevCursor` | 可选 | 作为 `cursor` 传入以获取下一页。最后一页不返回该字段。 |

### 错误状态

`400` `401` `403` `404` `422` `429` `500` `503` 错误结构见 [错误](https://mirabase.io/zh/developers/conventions.md#errors)，各错误码的含义见 [错误码](https://mirabase.io/zh/developers/errors.md)。

### 请求示例

```bash
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` | 路径 | `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 |

### 响应

- `200` `application/json` `DevMemorySettings`

### 错误状态

`400` `401` `403` `404` `422` `429` `500` `503` 错误结构见 [错误](https://mirabase.io/zh/developers/conventions.md#errors)，各错误码的含义见 [错误码](https://mirabase.io/zh/developers/errors.md)。

### 请求示例

```bash
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` | 路径 | `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`。 |

### 响应

- `200` `application/json` `DevMemorySettings`

### 错误状态

`400` `401` `403` `404` `408` `409` `410` `412` `413` `415` `422` `429` `500` `503` 错误结构见 [错误](https://mirabase.io/zh/developers/conventions.md#errors)，各错误码的含义见 [错误码](https://mirabase.io/zh/developers/errors.md)。

### 请求示例

```bash
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"
}
```
