# 记忆

受治理的记忆列表：写入、审核、更正、遗忘，以及追溯到来源。

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

## 列出记忆

`GET /v2/memories`

列出记忆，最新的在前。不带 `status` 时返回 `candidate` 和 `confirmed`；`rejected` 和 `superseded` 需要显式指定。账户记忆只对所有者列出，带 `space_id` 时不列出。以 Agent 身份或使用收窄的 Key 请求 `scope=account` 返回 403。开启了离线整理的部署上，内容相同的提炼记忆按组只列一次（`group_id`、`sources`），分页按组计数。需要 `knowledge:read`。

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

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

### 参数

| 名称 | 位置 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- | --- |
| `cursor` | 查询 | `DevCursor` | 可选 | 上一页的 `next_cursor`。不传则从第一页开始。 长度 1 到 1024 |
| `limit` | 查询 | `integer` | 可选 | 每页最多返回的条目数：1 到 100，默认 20。 1 到 100，默认 20 |
| `scope` | 查询 | `DevMemoryScope` | 可选 | 只保留一个范围的记忆：`project`、`agent` 或 `account`。 |
| `space_id` | 查询 | `DevSpaceRef` | 可选 | 只保留这个 Space 的记忆。`default` 指你的默认 Space，和路径里的含义相同。传了它就不列出账户记忆。 长度 1 到 256 |
| `status` | 查询 | `DevMemoryStatus` | 可选 | 只保留这个状态的记忆。不传时列表包含 `candidate` 和 `confirmed`。 |
| `kind` | 查询 | `string` | 可选 | 只保留一类，例如 `preference`、`decision` 或 `event`，即记忆上的 `kind`。不存在的类别返回空列表。 长度 1 到 64 |
| `entry_id` | 查询 | `DevId` | 可选 | 只保留源自该 Entry 的记忆：作为记忆写入的 Entry 本身，以及从中提炼出的事实。导入对话后，可用此参数读取该对话生成的记忆。不可见的 Entry 返回空列表。 长度 1 到 256 |
| `q` | 查询 | `string` | 可选 | 只保留正文包含这段文字的记忆，不区分大小写。此参数为字面匹配，用于浏览和清理，不是检索；按语义查找记忆请调用 `search` 并传入 `include: ["memory"]`。 长度 1 到 200 |

### 响应

- `200` `application/json`

200 响应：

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `data` | `DevMemory[]` | 必填 | 这一页的条目。 |
| `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/memories" \
  -H "Authorization: Bearer $MIRABASE_API_KEY"
```

### 响应结构示例

```json
{
  "data": [
    {
      "id": "<id>",
      "scope": "project",
      "kind": "<kind>",
      "status": "candidate",
      "text": "The launch moved to March 14.",
      "pinned": false,
      "created_at": "2026-11-06T00:00:00Z",
      "updated_at": "2026-11-06T00:00:00Z"
    }
  ]
}
```

## 写入记忆

`POST /v2/memories`

写入一条已确认的记忆。`account` 需要 `memory:confirm`；`project` 需要 `memory:confirm` 和 `knowledge:write`，且 Space 所有者必须是个人（`proposal` 模式的 Agent 不能写入 `project`）；`agent` 需要 `knowledge:write` 和 Agent 的 Key，写入该 Agent 自己的记忆。若要生成候选记忆而非直接写入已确认记忆，请导入对话。若 `project` 或 `agent` 记忆的 `text` 与同一 Space、同一范围、同一 `kind` 下的现行记忆相同，则不会重复写入，而是返回 200 及现有记忆（若请求传入 `pinned: true`，则会将其固定）。措辞不同的陈述算作新的记忆。

**需要的能力** 视请求而定，见上面的说明。

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

### 参数

| 名称 | 位置 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- | --- |
| `Idempotency-Key` | 请求头 | `DevIdempotencyKey` | 可选 | `Idempotency-Key`、主体、API Key、操作和输入都相同时，24 小时内重放原结果。同一个 `Idempotency-Key` 搭配不同输入时返回 409 `conflict`。 长度 1 到 512 |

### 请求体

`application/json` `DevCreateMemoryRequest`

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `scope` | `DevMemoryScope` | 必填 | 记忆的范围：`project`、`agent` 或 `account`。 |
| `space_id` | `DevSpaceRef` | 可选 | `project` 和 `agent` 必填；`default` 指你的默认 Space，和路径里一样。账户记忆不属于任何 Space，不带这个字段。 |
| `kind` | `string` | 必填 | `preference`、`decision` 或 `progress`。账户记忆另有一组：`role`、`project`、`commitment`、`preference`、`person`、`fact`、`episode_summary`、`interview_answer`、`first_screen_pin`、`ask_less`。 长度 1 到 64 |
| `text` | `string` | 必填 | 记忆的内容，1 到 2000 个字符。 长度 1 到 2000 |
| `pinned` | `boolean` | 可选 | 账户记忆没有这个字段。 默认 false |

### 响应

- `200` `application/json` `DevMemory`
- `201` `application/json` `DevMemory`

### 错误状态

`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/memories" \
  -H "Authorization: Bearer $MIRABASE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"scope":"project","space_id":"default","kind":"preference","text":"Ada prefers release notes in British English."}'
```

### 响应结构示例

```json
{
  "id": "ent_01JD2M8A7C",
  "space_id": "col_01JD2M7QK3",
  "scope": "project",
  "kind": "preference",
  "status": "confirmed",
  "text": "Ada prefers release notes in British English.",
  "pinned": false,
  "created_at": "2026-11-17T08:05:00Z",
  "updated_at": "2026-11-17T08:05:00Z"
}
```

## 读取记忆

`GET /v2/memories/{memory_id}`

读取一条记忆。提炼事实的 id 含 `:`，放入路径时需进行百分号编码。你不可见的记忆返回 404 `not_found`，与不存在的记忆相同。需要 `knowledge:read`。

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

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

### 参数

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

### 响应

- `200` `application/json` `DevMemory`

### 错误状态

`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/memories/$MEMORY_ID" \
  -H "Authorization: Bearer $MIRABASE_API_KEY"
```

### 响应结构示例

```json
{
  "id": "ent_01JD2M8A7C",
  "space_id": "col_01JD2M7QK3",
  "scope": "project",
  "kind": "preference",
  "status": "confirmed",
  "text": "Ada prefers release notes in British English.",
  "pinned": false,
  "created_at": "2026-11-17T08:05:00Z",
  "updated_at": "2026-11-17T08:05:00Z"
}
```

## 修改记忆

`PATCH /v2/memories/{memory_id}`

固定或取消固定一条以 Entry 写入的记忆，或用 `valid_to` 关闭提炼事实或账户记忆。传入不适用于这类记忆的字段返回 422。候选记忆返回 409（提炼事实是 `memory_pending_review`，账户记忆是 `conflict`），请先审核。Space 记忆需要 `knowledge:write`，账户记忆需要 `memory:confirm`。

**需要的能力** 视请求而定，见上面的说明。

### 参数

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

### 请求体

`application/json` `DevUpdateMemoryRequest` 至少传一个。

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `pinned` | `boolean` | 可选 | 只对以 Entry 写入的记忆有效。固定记忆会改变 Space 的起始内容，所以 Space 所有者必须是人。 |
| `valid_to` | `string (date-time)` | 可选 | 关闭提炼事实或账户记忆。以 Entry 写入的记忆没有有效期，请遗忘或更正它。 |

### 响应

- `200` `application/json` `DevMemory`

### 错误状态

`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/memories/$MEMORY_ID" \
  -H "Authorization: Bearer $MIRABASE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
```

### 响应结构示例

```json
{
  "id": "ent_01JD2M8A7C",
  "space_id": "col_01JD2M7QK3",
  "scope": "project",
  "kind": "preference",
  "status": "confirmed",
  "text": "Ada prefers release notes in British English.",
  "pinned": false,
  "created_at": "2026-11-17T08:05:00Z",
  "updated_at": "2026-11-17T08:05:00Z"
}
```

## 遗忘记忆

`DELETE /v2/memories/{memory_id}`

永久遗忘一条记忆。提炼事实需要 `knowledge:write` 及 Space 的 editor 角色；以 Entry 写入的记忆需要 `knowledge:write`；账户记忆需要 `memory:confirm`。来源重新发布、恢复、编辑或移动后，该提炼事实不会恢复，相同内容也不会再次提炼到该 Space；来源 Entry 保持不变。以 Entry 写入的记忆及其曾取代的记忆会被彻底删除。再次删除返回 404。若要禁止从某条 Entry 提炼记忆，请在该 Entry 上设置 `memory_exclude`。

**需要的能力** 视请求而定，见上面的说明。

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

### 参数

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

### 响应

- `200` `application/json` `DevMemoryForgetReceipt`

### 错误状态

`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 DELETE "https://api.mirabase.dev/v2/memories/$MEMORY_ID" \
  -H "Authorization: Bearer $MIRABASE_API_KEY"
```

### 响应结构示例

```json
{
  "memory_id": "<memory_id>",
  "status": "forgotten"
}
```

## 更正记忆

`POST /v2/memories/{memory_id}/correct`

用你提供的内容替换一条记忆。需要 `memory:confirm`。旧记忆被关闭，不会恢复。提炼事实或以 Entry 写入的记忆由同一 Space 里的一条新记忆 Entry 替换，只有 Space 所有者或 Agent 能写入，因此响应包含新的 `id`，`supersedes` 指向旧记忆。账户记忆由另一条账户记忆替换。以 Entry 写入的记忆已经被替换时返回 409 `memory_superseded`。

**需要的能力** `memory:confirm`

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

### 参数

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

### 请求体

`application/json` `DevCorrectMemoryRequest` 写入替换内容，并关闭旧记忆的有效期。

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `text` | `string` | 必填 | 更正后的内容，1 到 2000 个字符。 长度 1 到 2000 |

### 响应

- `200` `application/json` `DevMemory`

### 错误状态

`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/memories/$MEMORY_ID/correct" \
  -H "Authorization: Bearer $MIRABASE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text":"The launch moved to March 14."}'
```

### 响应结构示例

```json
{
  "id": "ent_01JD2M8A7C",
  "space_id": "col_01JD2M7QK3",
  "scope": "project",
  "kind": "preference",
  "status": "confirmed",
  "text": "Ada prefers release notes in British English.",
  "pinned": false,
  "created_at": "2026-11-17T08:05:00Z",
  "updated_at": "2026-11-17T08:05:00Z"
}
```

## 查看记忆来源

`GET /v2/memories/{memory_id}/provenance`

一条记忆所依据的 Entry 版本，有引文时附带引文。需要 `knowledge:read`。

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

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

### 参数

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

### 响应

- `200` `application/json` `DevMemoryProvenance`

### 错误状态

`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/memories/$MEMORY_ID/provenance" \
  -H "Authorization: Bearer $MIRABASE_API_KEY"
```

### 响应结构示例

```json
{
  "memory_id": "<memory_id>",
  "sources": [
    {
      "entry_id": "<entry_id>",
      "version_id": "<version_id>"
    }
  ]
}
```

## 审核记忆

`POST /v2/memories/{memory_id}/review`

处理一条候选记忆。需要 `memory:confirm`。`confirm` 将它变为 `confirmed`，检索会使用它；`reject` 将它变为 `rejected`，同一句话不会在这个 Space 里再次被提炼。重复相同决定时，接口原样返回记忆；提交相反决定时，接口返回 409 `memory_already_reviewed`（账户记忆是 `conflict`）。要移除已确认的记忆，请遗忘它。

**需要的能力** `memory:confirm`

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

### 参数

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

### 请求体

`application/json` `DevReviewMemoryRequest`

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `decision` | `confirm \| reject` | 必填 | `confirm` 确认候选记忆；`reject` 驳回候选记忆。 |

### 响应

- `200` `application/json` `DevMemory`

### 错误状态

`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/memories/$MEMORY_ID/review" \
  -H "Authorization: Bearer $MIRABASE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"decision":"confirm"}'
```

### 响应结构示例

```json
{
  "id": "ent_01JD2M8A7C",
  "space_id": "col_01JD2M7QK3",
  "scope": "project",
  "kind": "preference",
  "status": "confirmed",
  "text": "Ada prefers release notes in British English.",
  "pinned": false,
  "created_at": "2026-11-17T08:05:00Z",
  "updated_at": "2026-11-17T08:05:00Z"
}
```

## 撤销记忆写入

`POST /v2/memories/{memory_id}/undo`

在 30 分钟内撤销你写入的记忆或所做的更正。需要 `memory:confirm`。对新记忆调用：这条记忆被彻底删除，它所替换的内容在 `restored` 中恢复。超过 30 分钟时限或这条记忆已被其他记忆取代时，接口返回 409：以 Entry 写入的记忆对应的错误码是 `undo_window_expired` 或 `memory_superseded`，账户记忆是 `conflict`。对提炼事实调用时，接口返回 409 `undo_not_applicable`：没有人写入过它，且遗忘不可撤销。对以 Entry 写入的记忆第二次撤销返回 404，因为第一次撤销已经把它彻底删除。

**需要的能力** `memory:confirm`

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

### 参数

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

### 响应

- `200` `application/json` `DevMemoryUndoReceipt`

### 错误状态

`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/memories/$MEMORY_ID/undo" \
  -H "Authorization: Bearer $MIRABASE_API_KEY"
```

### 响应结构示例

```json
{
  "memory_id": "<memory_id>",
  "status": "undone",
  "restored": [
    {
      "id": "<id>",
      "scope": "project",
      "kind": "<kind>",
      "status": "candidate",
      "text": "The launch moved to March 14.",
      "pinned": false,
      "created_at": "2026-11-06T00:00:00Z",
      "updated_at": "2026-11-06T00:00:00Z"
    }
  ]
}
```
