# MCP

同一套接口，以 Model Context Protocol 工具的形式提供给 Agent。

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

## MCP 握手

`GET /mcp`

基于 Streamable HTTP 的 MCP 握手。仅携带 `Accept: text/event-stream` 时返回 405：该服务不推送。本身不需要任何能力：`tools` 只列出这个 Key 的能力允许的工具。

**需要的能力** 不检查能力。

指南：[连接 Agent（MCP）](https://mirabase.io/zh/developers/agents.md#protocol-versions)

### 响应

- `200` `application/json` `DevMcpHandshake`

### 响应头

- `Mcp-Protocol-Version`

### 错误状态

`400` `401` `403` `404` `405` `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/mcp" \
  -H "Authorization: Bearer $MIRABASE_API_KEY"
```

### 响应结构示例

```json
{
  "name": "research",
  "version": "<version>",
  "protocol": "<protocol>",
  "transport": "streamable-http",
  "tools": [
    {
      "name": "mira.whoami",
      "description": "<description>",
      "inputSchema": {}
    }
  ]
}
```

## 调用 MCP

`POST /mcp`

MCP JSON-RPC 端点。请求本身按读取限流，每次工具调用再按它发出的 `/v2` 请求限流，所以一次工具调用消耗两个令牌。本身不需要任何能力：每个工具检查自己需要的能力，`tools/list` 只列出 Key 的能力允许调用的工具。此操作上的 `x-mirabase-mcp-tools` 按 `tools/list` 的返回列出每个工具：`name`、`title`、`description`、`annotations`、`inputSchema`，结果结构稳定的只读工具还有 `outputSchema`。带 `feature` 的工具只在开启该功能的部署上存在。支持的协议版本为 `2025-11-25`、`2025-06-18`、`2025-03-26` 和 `2024-11-05`。`initialize` 时，客户端请求的版本受支持则使用该版本，否则使用 `2025-11-25`。后续请求按 `MCP-Protocol-Version` 请求头处理：未带该请求头时按 `2025-03-26` 处理，不支持的版本返回 400 和 JSON-RPC 错误 `-32000`。从 `2025-06-18` 起，`tools/list` 包含 `outputSchema`，调用这类工具成功时还返回 `structuredContent`。参数不符合 `inputSchema` 时，`2025-11-25` 之前返回 JSON-RPC 错误 `-32602`；从 `2025-11-25` 起返回带 `isError: true`、错误码为 `validation_error` 的工具结果。

**需要的能力** 不检查能力。

### 请求体

`text/plain` `DevMcpRequest` 一个 JSON-RPC 2.0 请求，或最多 32 个请求组成的批次。方法由 MCP 定义；`tools/call` 的工具取自 `x-mirabase-mcp-tools`，`arguments` 须符合该工具的 `inputSchema`。

### 响应

- `200` `text/plain` `DevMcpResponse`, `text/event-stream; charset=utf-8` `string`
- `202` 无响应体

### 响应头

- `Mcp-Protocol-Version`

### 错误状态

`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 -X POST "https://api.mirabase.dev/mcp" \
  -H "Authorization: Bearer $MIRABASE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'
```

## 工具

`tools/list` 返回的全部工具。工具的参数是 `tools/call` 中 `arguments` 的字段；`tools/list` 只列出 Key 的能力允许调用的工具。

- `mira.whoami` 显示 Key 的身份
- `mira.files.list` 列出文件
- `mira.files.read` 读取文件
- `mira.files.write` 写入文件
- `mira.files.edit` 编辑文件
- `mira.files.delete` 把文件移入废纸篓
- `mira.search` 搜索
- `mira.context` 构建任务上下文
- `mira.context.feedback` 报告用到的上下文
- `mira.activity` 显示近期动态
- `mira.memory.list` 列出记忆
- `mira.memory.remember` 记住一条陈述
- `mira.memory.forget` 遗忘记忆
- `mira.conversation.ingest` 保存对话
- `mira.text.ingest` 保存文本
- `mira.url.ingest` 保存网页
- `mira.entries.read` 读取 Entry
- `mira.answer` 带引用回答
- `mira.memory.correct` 更正记忆
- `mira.memory.review` 审核候选记忆
- `mira.trash.list` 列出废纸篓
- `mira.trash.restore` 从废纸篓恢复
- `mira.memory.get` 读取记忆（需要部署开启）

## 显示 Key 的身份

`mira.whoami`

返回这个 Key 代表谁：主体及其类型（人或 Agent）、`effective_capabilities`，以及 Key 限定的 Space 或元数据。遇到意料之外的 403 或 404 后调用它；为 `mira.memory.remember` 选择 `scope` 之前也先调用它。

**注解** `readOnlyHint` `idempotentHint`

`tools/list` 为它提供 `outputSchema`；从协议版本 `2025-06-18` 起，调用成功时还返回 `structuredContent`。

### 参数

不带参数。

## 列出文件

`mira.files.list`

列出一个目录：每个文件带路径、`size_bytes`、`etag` 和 `modified_at`。为新文件选择路径之前，用它查看 Space 里已有的内容；知道所在目录但不知道文件名时也用它。要按内容查找文件，用 `mira.search`。

**注解** `readOnlyHint` `idempotentHint`

`tools/list` 为它提供 `outputSchema`；从协议版本 `2025-06-18` 起，调用成功时还返回 `structuredContent`。

### 参数

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `space_id` | `string` | 可选 | Space id，或 `ext:<external_id>`（带有你自己的 id 的 Space）。不传时用你的默认 Space。 长度 1 到 256 |
| `path` | `string` | 可选 | 要列出的目录。不传时列出根目录。 长度 1 到 4096 |
| `recursive` | `boolean` | 可选 | 为 `true` 时列出整棵子树。 |
| `cursor` | `string` | 可选 | 上一页返回的 `next_cursor`。 长度 1 到 1024 |
| `limit` | `integer` | 可选 | 每页最多返回的节点数。 1 到 100 |

## 读取文件

`mira.files.read`

按路径读取一个文件。`view` 为 `text`（默认）时分窗口返回文本：只要 `content_window.truncated` 为真，就把 `offset` 设为 `content_window.next_offset` 再次调用。`view` 为 `table` 时返回 CSV 文件或表格的列和行。`view` 为 `meta` 时返回 Entry，其中 `file.etag` 可作为 `if_match` 传入，`knowledge.state` 表示索引进度。文本文件写入后即可用 `text` 读取。`table`，以及其他格式的 `text`，在处理完成前返回 404 `content_not_ready`：稍后再读。422 `view_not_available` 表示这个文件没有这种视图。

**注解** `readOnlyHint` `idempotentHint`

### 参数

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `space_id` | `string` | 可选 | Space id，或 `ext:<external_id>`（带有你自己的 id 的 Space）。不传时用你的默认 Space。 长度 1 到 256 |
| `path` | `string` | 必填 | 绝对路径，如 `/notes/plan.md`。 长度 1 到 4096 |
| `view` | `text \| meta \| table` | 可选 | `text`（默认）、`table` 或 `meta`。 |
| `version` | `string` | 可选 | 读取这个旧版本。不传时读取最新版本。 长度 1 到 256 |
| `offset` | `integer` | 可选 | 窗口的起点，以字符计：上一次调用返回的 `content_window.next_offset`。仅用于 `text`。 不小于 0 |
| `max_chars` | `integer` | 可选 | 窗口大小，以字符计。默认 16000，最多 100000。仅用于 `text`。 1 到 100000 |

## 写入文件

`mira.files.write`

在一个路径上创建或替换文本文件。任务产出以后要用的文档（笔记、报告、计划、规格说明，或 `media_type` 为 `text/csv` 的 CSV 表格）时调用它，用户要求保存一段文本时也调用它。使用稳定的路径，后续版本写到同一路径：每次写入都会新增一个版本，旧版本保留（内容相同时不新增），所以不要另建 `plan-v2.md` 这样的副本。调用返回时写入已提交，可以读取；64 KiB 以内的文本在下一次调用时即可按词检索，索引完成后可按语义检索。`content` 是文本，这个工具不能传二进制文件。单条事实或偏好不要用它（用 `mira.memory.remember`），临时输出以及密码、密钥和令牌也不要用它保存。

**注解** `idempotentHint`

### 参数

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `space_id` | `string` | 可选 | Space id，或 `ext:<external_id>`（带有你自己的 id 的 Space）。不传时用你的默认 Space。 长度 1 到 256 |
| `path` | `string` | 必填 | 绝对路径，如 `/notes/plan.md`。缺少的目录会自动创建。 长度 1 到 4096 |
| `content` | `string` | 必填 | 完整的文件内容，以文本表示。 |
| `media_type` | `string` | 可选 | 默认 `text/markdown`。表格用 `text/csv`。 长度 1 到 256 |
| `if_match` | `string` | 可选 | 你上次读到的 `etag`（`meta` 视图中的 `file.etag`，或 `mira.files.list` 返回的 `etag`）。如果文件在那之后有变更，调用以 412 `precondition_failed` 失败。 长度 1 到 256 |
| `create_only` | `boolean` | 可选 | 为 `true` 时，文件已存在就以 412 `precondition_failed` 失败。 |
| `session_id` | `string` | 可选 | 本次修改所属对话的 id，由你指定，与传给 `mira.conversation.ingest` 的相同。它记录在版本上。 长度 1 到 256 |
| `wait_seconds` | `integer` | 可选 | 等待索引完成后再返回的最长秒数。无论是否等到，写入都已提交。 1 到 10 |
| `idempotency_key` | `string` | 可选 | 只在 24 小时内重试完全相同的调用时发送同一个键：服务会再次返回第一次的结果。 长度 1 到 256 |

## 编辑文件

`mira.files.edit`

替换已有 UTF-8 文本文件中的指定文本，并提交一个新版本。修改或补充文件的一部分时用它，不必重写整个文件。只要有一处编辑匹配失败，文件就不变（422 `edit_no_match` 或 `edit_ambiguous`）。超过 1 MiB 的文件不能编辑：用 `mira.files.write` 替换整个文件。

### 参数

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `space_id` | `string` | 可选 | Space id，或 `ext:<external_id>`（带有你自己的 id 的 Space）。不传时用你的默认 Space。 长度 1 到 256 |
| `path` | `string` | 必填 | 绝对路径，如 `/notes/plan.md`。 长度 1 到 4096 |
| `edits` | `object[]` | 必填 | 1 到 100 处替换，按顺序执行。`old_text` 必须在文件中恰好出现一次；要替换所有出现的位置，把 `replace_all` 设为 `true`。`new_text` 可以为空，表示删除。 1 到 100 项 |
| `edits[].old_text` | `string` | 必填 | 最短 1 |
| `edits[].new_text` | `string` | 必填 |  |
| `edits[].replace_all` | `boolean` | 可选 | 默认 false |
| `if_match` | `string` | 可选 | 你上次读到的 `etag`（`meta` 视图中的 `file.etag`，或 `mira.files.list` 返回的 `etag`）。如果文件在那之后有变更，调用以 412 `precondition_failed` 失败。 长度 1 到 256 |
| `session_id` | `string` | 可选 | 本次修改所属对话的 id，由你指定，与传给 `mira.conversation.ingest` 的相同。它记录在版本上。 长度 1 到 256 |
| `wait_seconds` | `integer` | 可选 | 等待索引完成后再返回的最长秒数。无论是否等到，写入都已提交。 1 到 10 |
| `idempotency_key` | `string` | 可选 | 只在 24 小时内重试完全相同的调用时发送同一个键：服务会再次返回第一次的结果。 长度 1 到 256 |

## 把文件移入废纸篓

`mira.files.delete`

把一个文件移入废纸篓。文件已过时或误写时用它；要修改文件内容，请写入或编辑文件。`mira.trash.restore` 可以恢复它，所需的 `entry_id` 来自 `mira.trash.list`。

**注解** `destructiveHint` `idempotentHint`

### 参数

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `space_id` | `string` | 可选 | Space id，或 `ext:<external_id>`（带有你自己的 id 的 Space）。不传时用你的默认 Space。 长度 1 到 256 |
| `path` | `string` | 必填 | 绝对路径，如 `/notes/plan.md`。 长度 1 到 4096 |
| `if_match` | `string` | 可选 | 你上次读到的 `etag`（`meta` 视图中的 `file.etag`，或 `mira.files.list` 返回的 `etag`）。如果文件在那之后有变更，调用以 412 `precondition_failed` 失败。 长度 1 到 256 |

## 搜索

`mira.search`

搜索具体内容，返回排序后的片段，每条带有 `entry_id`、`citation_id` 以及路径或网址。明确要查找的内容时调用此工具；在陈述先前说过、决定过或保存过的内容之前，也应先调用此工具。`include` 为 `["memory"]` 时同时搜索记忆。64 KiB 以内的文本写入后即可按词检索，索引完成后可按语义检索。结果中的 `pending_processing` 表示所检索的 Space 中有相应数量的 Entry 仍在处理、可能缺失：如果需要的内容可能在其中，请稍后再搜索。如需为整个任务收集上下文，请使用 `mira.context`。

**注解** `readOnlyHint` `idempotentHint`

`tools/list` 为它提供 `outputSchema`；从协议版本 `2025-06-18` 起，调用成功时还返回 `structuredContent`。

### 参数

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `query` | `string` | 必填 | 要检索的内容，可使用自然语言或关键词。 长度 1 到 1000 |
| `space_ids` | `string[]` | 可选 | 要读取的 Space：id、`default` 或 `ext:<external_id>`。不传时读取 Key 能读的全部 Space，而不只是你的默认 Space；只针对一个用户或项目时传一个 Space。能读超过 200 个 Space 的 Key 必须指定 Space。 1 到 64 项 |
| `path` | `string` | 可选 | 只返回这棵子树或这一个文件里的结果。 长度 1 到 4096 |
| `include` | `"memory"[]` | 可选 | `["memory"]` 让结果包含记忆。 1 项 |
| `limit` | `integer` | 可选 | 最多返回的命中数。默认 20，最多 50。 1 到 50 |
| `filter` | `object` | 可选 | 按 `metadata`（精确匹配；`{any: [...]}` 匹配列出的任一值）、`source_types` 以及 `occurred_from` / `occurred_to`（RFC 3339，含两端）收窄。至少给出一个条件。记忆没有元数据，所以按元数据筛选时不包含记忆。 |
| `filter.metadata` | `object` | 可选 |  |
| `filter.source_types` | `string[]` | 可选 | 1 到 8 项 |
| `filter.occurred_from` | `string (date-time)` | 可选 |  |
| `filter.occurred_to` | `string (date-time)` | 可选 |  |
| `reference_time` | `string (date-time)` | 可选 | 查询或任务中的相对时间（昨天、上周）从哪一刻算起，RFC 3339。默认是此刻。 |
| `timezone` | `string` | 可选 | 提问者的 IANA 时区，如 `Asia/Shanghai`。默认是部署的时区。 长度 1 到 64 |

## 构建任务上下文

`mira.context`

在 token 预算内为一个任务构建上下文。规划任务之前调用它，任务变化时再调用一次。它返回 `pack_id`、`memory_view`（已确认的记忆，对每个任务都相同）、`items`（为这个任务从记忆、任务点名的文件、近期修改、知识和技能中选出的片段，每条带 `citation_id`）和 `route`（用了哪些来源以及原因）。来源为 `skills` 的条目是 `/.mirabase/skills/` 下某个文件的一行摘要：要看正文，按它的路径读取文件。用过 `items` 之后，用 `mira.context.feedback` 报告。

**注解** `readOnlyHint` `idempotentHint`

`tools/list` 为它提供 `outputSchema`；从协议版本 `2025-06-18` 起，调用成功时还返回 `structuredContent`。

### 参数

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `task` | `string` | 必填 | 用一两句话描述任务，最多 1000 字符，使用用户的语言。写出某个文件的路径，结果就会包含这个文件。 长度 1 到 1000 |
| `space_ids` | `string[]` | 可选 | 要读取的 Space：id、`default` 或 `ext:<external_id>`。不传时读取 Key 能读的全部 Space，而不只是你的默认 Space；只针对一个用户或项目时传一个 Space。能读超过 200 个 Space 的 Key 必须指定 Space。 1 到 64 项 |
| `purpose` | `task \| coding \| research \| audit` | 可选 | 决定预算在各来源之间如何分配。不传时根据任务推断。 |
| `weights` | `object` | 可选 | 每个来源 0 到 1 的偏好。`0` 关闭这个来源。 |
| `weights.memory` | `number` | 可选 | 0 到 1 |
| `weights.agent_profile` | `number` | 可选 | 0 到 1 |
| `weights.skills` | `number` | 可选 | 0 到 1 |
| `weights.files` | `number` | 可选 | 0 到 1 |
| `weights.changes` | `number` | 可选 | 0 到 1 |
| `weights.knowledge` | `number` | 可选 | 0 到 1 |
| `tier` | `fast \| standard \| deep` | 可选 | `fast` 只按词匹配，不调用模型。`standard`（默认）增加语义检索和重排序。`deep` 考察的候选是默认的两倍。 |
| `budget_tokens` | `integer` | 可选 | 整个响应的 token 预算，500 到 16000。默认 4000。 500 到 16000 |
| `have_memory_etag` | `string` | 可选 | 上一个上下文包返回的 `memory_view_etag`。`memory_view` 没有变化时不再返回。 长度 1 到 128 |
| `filter` | `object` | 可选 | 按 `metadata`（精确匹配；`{any: [...]}` 匹配列出的任一值）、`source_types` 以及 `occurred_from` / `occurred_to`（RFC 3339，含两端）收窄。至少给出一个条件。记忆没有元数据，所以按元数据筛选时不包含记忆。 |
| `filter.metadata` | `object` | 可选 |  |
| `filter.source_types` | `string[]` | 可选 | 1 到 8 项 |
| `filter.occurred_from` | `string (date-time)` | 可选 |  |
| `filter.occurred_to` | `string (date-time)` | 可选 |  |
| `reference_time` | `string (date-time)` | 可选 | 查询或任务中的相对时间（昨天、上周）从哪一刻算起，RFC 3339。默认是此刻。 |
| `timezone` | `string` | 可选 | 提问者的 IANA 时区，如 `Asia/Shanghai`。默认是部署的时区。 长度 1 到 64 |

## 报告用到的上下文

`mira.context.feedback`

报告上下文包里实际用到了哪些条目。完成这个包所服务的回答或步骤后调用一次，带上你依据的每个条目的 `citation_id`；一条都没用到时不要调用。它只发送 id，不发送内容，重复报告也是安全的。

**注解** `idempotentHint`

### 参数

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `pack_id` | `string` | 必填 | `mira.context` 结果中的 `pack_id`。 长度 1 到 256 |
| `used_citation_ids` | `string[]` | 必填 | 这个包里的一个或多个引用 id，如 `c1` 和 `c3`。不在包里的 id 会被拒绝。 1 到 256 项 |

## 显示近期动态

`mira.activity`

显示一个 Space 近期由谁修改了什么，按主体和文件分组。在其他人或其他 Agent 也会写入的 Space 里编辑文件之前调用它，以免覆盖进行中的工作。

**注解** `readOnlyHint` `idempotentHint`

`tools/list` 为它提供 `outputSchema`；从协议版本 `2025-06-18` 起，调用成功时还返回 `structuredContent`。

### 参数

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `space_id` | `string` | 可选 | Space id，或 `ext:<external_id>`（带有你自己的 id 的 Space）。不传时用你的默认 Space。 长度 1 到 256 |
| `days` | `integer` | 可选 | 回看多少天。默认 7，最多 30。 1 到 30 |

## 列出记忆

`mira.memory.list`

列出记忆，最新的在前，每条带 id、`scope`、`kind`、`status` 和正文。要找到待遗忘记忆的 id、确认某条陈述尚未保存，或被问到具体记住了什么时调用它。不传 `status` 时返回 `candidate` 和 `confirmed` 的记忆。`q` 只保留正文包含该短语的记忆；它是字面匹配，要按语义搜索，用 `mira.search` 并带 `include` 为 `["memory"]`。

**注解** `readOnlyHint` `idempotentHint`

`tools/list` 为它提供 `outputSchema`；从协议版本 `2025-06-18` 起，调用成功时还返回 `structuredContent`。

### 参数

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `space_id` | `string` | 可选 | 只列这个 Space 的记忆；`default` 指你的默认 Space，`ext:<external_id>` 指带有你自己的 id 的 Space。不传时列出你能读的全部 Space，加上你的账户记忆：这个工具不会退回到你的默认 Space。 长度 1 到 256 |
| `scope` | `project \| agent \| account` | 可选 | 只保留一种范围的记忆。 |
| `status` | `candidate \| confirmed \| rejected \| superseded` | 可选 | `candidate` 等待审核，检索不使用；`confirmed` 检索会使用；`rejected` 和 `superseded` 是历史记录。 |
| `kind` | `string` | 可选 | 只保留一种类型，如 `preference`、`decision` 或 `progress`。 长度 1 到 64 |
| `q` | `string` | 可选 | 记忆正文必须包含的短语：字面匹配，不区分大小写。 长度 1 到 200 |
| `cursor` | `string` | 可选 | 上一页返回的 `next_cursor`。 长度 1 到 1024 |
| `limit` | `integer` | 可选 | 每页最多返回的记忆数。 1 到 100 |

## 记住一条陈述

`mira.memory.remember`

写入一条已确认的记忆：一句自成一体、在这段对话之外依然成立的陈述。用户说出长期的偏好、决定或事实（“从现在起”“我们决定”“记住”）时调用它；工作未完成就要停下时也调用它（`kind` 为 `progress`）。要替换错误或过时的记忆，用 `mira.memory.correct`。调用返回后，`mira.memory.list` 即可列出这条记忆；处理完成后它出现在 `memory_view` 和 `mira.search` 中。先用 `mira.search`（`include` 为 `["memory"]`）或 `mira.memory.list` 确认它尚未保存：完全相同的陈述会返回已有的记忆，换了说法的会另存为新记忆。不要用它保存文档或表格（用 `mira.files.write`）、整段对话（用 `mira.conversation.ingest`）、与已有记忆矛盾的内容，以及密码、密钥或令牌。

**注解** `idempotentHint`

### 参数

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `scope` | `project \| agent \| account` | 必填 | `agent`：你自己在一个 Space 里的笔记，只有你和 Space 所有者能读；需要 Agent 的 Key。`project`：与 Space 里的所有人共享；需要 `memory:confirm`，并且你是 Space 所有者，或者你是在这个 Space 里写入模式为 `direct` 的 Agent。`account`：跨 Space 跟随一个人；需要 `memory:confirm`，Agent 的 Key 以及限定了 Space 或元数据的 Key 会被拒绝。 |
| `space_id` | `string` | 可选 | 用于 `project` 和 `agent` 记忆。不传时用你的默认 Space。账户记忆不需要传。 长度 1 到 256 |
| `kind` | `string` | 必填 | 对 `project` 和 `agent`，取以下之一：`preference`（某人希望事情怎么做）、`decision`（已经定下的事，包括可以依据的事实）、`progress`（未完成的工作进行到哪里）。账户记忆有自己的类型，如 `role`、`preference`、`commitment`、`person` 或 `fact`。 长度 1 到 64 |
| `text` | `string` | 必填 | 陈述，一两句话，最多 2000 字符。 最短 1 |
| `pinned` | `boolean` | 可选 | 为 `true` 时，在 `memory_view` 中排在未置顶的记忆之前。不适用于账户记忆。 |
| `idempotency_key` | `string` | 可选 | 只在 24 小时内重试完全相同的调用时发送同一个键：服务会再次返回第一次的结果。 长度 1 到 256 |

## 遗忘记忆

`mira.memory.forget`

彻底删除一条记忆，无法撤销。只在用户要求你遗忘某件事时调用它。要替换错误或过时的记忆，用 `mira.memory.correct`，它会把旧陈述保留为历史记录。用 `mira.memory.list` 查找 id。从对话中提炼的记忆不会再次被提炼；来源对话仍可搜索，并以 `remaining_sources` 返回。

**注解** `destructiveHint` `idempotentHint`

### 参数

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `memory_id` | `string` | 必填 | 记忆的 id，来自 `mira.memory.list`。 长度 1 到 256 |

## 保存对话

`mira.conversation.ingest`

把一批对话消息保存为一个新的 Entry，并由服务决定从中记住什么。任务或对话结束时，或者上下文被压缩之前调用它；但如果宿主应用或插件已经保存了对话，或要求你不要发送，就不要调用。只发送之前没有发送过的用户和助手消息：同一条消息在另一次调用中再发一次，会被保存两次。对话随即可以搜索，调用返回后服务从中提炼记忆。结果中的 `memory_status` 说明这些记忆是否生效：`confirmed`；或者在 Key 缺少 `memory:confirm`、或者是写入模式为提案的 Agent 时为 `candidate`。`candidate` 记忆在有人确认之前（按用户的意见调用 `mira.memory.review`）不参与检索。不要包含工具输出或机密信息。

### 参数

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `space_id` | `string` | 可选 | Space id，或 `ext:<external_id>`（带有你自己的 id 的 Space）。不传时用你的默认 Space。 长度 1 到 256 |
| `session_id` | `string` | 必填 | 你为这段对话指定的 id。同一段对话的每一批都使用同一个值，它修改的文件也使用这个值。 长度 1 到 256 |
| `messages` | `object[]` | 必填 | 1 到 1000 条消息，按说出的先后顺序排列。 1 到 1000 项 |
| `messages[].role` | `string` | 必填 | `user`、`assistant` 或其他说话人。 长度 1 到 64 |
| `messages[].content` | `string` | 必填 | 说了什么，以文本表示。 最短 1 |
| `messages[].timestamp` | `string (date-time)` | 可选 | 说话的时间，RFC 3339。 |
| `messages[].name` | `any` | 可选 | 接收但忽略。 |
| `messages[].tool_calls` | `any` | 可选 | 接收但忽略。 |
| `messages[].tool_call_id` | `any` | 可选 | 接收但忽略。 |
| `messages[].function_call` | `any` | 可选 | 接收但忽略。 |
| `title` | `string` | 可选 | 默认为 `Conversation <session_id>`。 长度 1 到 512 |
| `redact_secrets` | `boolean` | 可选 | 请设为 `true`。它在保存任何内容之前替换看起来像凭据的内容（私钥、JWT、Bearer 令牌、常见的 API Key 格式、`password=...`），结果中的 `secrets_redacted` 是替换的次数。这是一道安全网，不是保证。 |
| `memory_instructions` | `string` | 可选 | 应用规定的、从这段对话中记住什么和忽略什么的规则，最多 2000 字符，如“记住饮食限制和过敏；忽略闲聊”。应用给了你这样的规则时传入，否则不传。每条记忆仍必须有消息中的引文作为依据。 长度 1 到 2000 |
| `idempotency_key` | `string` | 可选 | 只在 24 小时内重试完全相同的调用时发送同一个键：服务会再次返回第一次的结果。 长度 1 到 256 |

## 保存文本

`mira.text.ingest`

把一段文本保存为一个没有路径的新 Entry：邮件、会议记录、一条消息、粘贴的文档。用户给你一段要保存、但不属于某个文件路径的文本时调用它；以后要按名称编辑或读回的内容，改用 `mira.files.write`。保存后立即可以按词检索，索引完成后可以按语义检索。返回 `entry_id`、`version_id` 和 `job_id`。

### 参数

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `space_id` | `string` | 可选 | Space id，或 `ext:<external_id>`（带有你自己的 id 的 Space）。不传时用你的默认 Space。 长度 1 到 256 |
| `text` | `string` | 必填 | 要保存的文本，最多 2,000,000 个字符。 长度 1 到 2000000 |
| `title` | `string` | 可选 | 默认取第一行。 长度 1 到 512 |
| `occurred_at` | `string (date-time)` | 可选 | 内容发生的时间，RFC 3339，如会议或邮件的日期。按时间范围的搜索和关于当前状态的问题以它为准。 |
| `metadata` | `object` | 可选 | 以后用来筛选的标签，如 `{"customer": "acme"}`。键由 1 到 64 个 `a-z`、`0-9`、`_`、`.`、`-` 组成；每个值是字符串或字符串列表，全部值合计最多 32 个。 |
| `redact_secrets` | `boolean` | 可选 | 为 `true` 时，在保存任何内容之前替换看起来像凭据的内容。这是一道安全网，不是保证。 |
| `idempotency_key` | `string` | 可选 | 只在 24 小时内重试完全相同的调用时发送同一个键：服务会再次返回第一次的结果。 长度 1 到 256 |

## 保存网页

`mira.url.ingest`

抓取一个公开网页，把其中可读的文本保存为一个新 Entry。用户要求你保存或记住一个链接时调用它。网页由服务抓取，而不是由你抓取；无法抓取或没有可读文本的网页以 `url_fetch_failed` 或 `url_no_readable_content` 失败。返回 `entry_id`、`version_id` 和 `job_id`；任务成功后文本即可检索。

**注解** `openWorldHint`

### 参数

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `space_id` | `string` | 可选 | Space id，或 `ext:<external_id>`（带有你自己的 id 的 Space）。不传时用你的默认 Space。 长度 1 到 256 |
| `url` | `string` | 必填 | `http` 或 `https` 网址。 长度 1 到 8192 |
| `title` | `string` | 可选 | Entry 的标题。默认用网页自身的标题。 长度 1 到 512 |
| `occurred_at` | `string (date-time)` | 可选 | 网页内容发生的时间，RFC 3339，已知时传入。 |
| `metadata` | `object` | 可选 | 以后用来筛选的标签，如 `{"customer": "acme"}`。键由 1 到 64 个 `a-z`、`0-9`、`_`、`.`、`-` 组成；每个值是字符串或字符串列表，全部值合计最多 32 个。 |
| `idempotency_key` | `string` | 可选 | 只在 24 小时内重试完全相同的调用时发送同一个键：服务会再次返回第一次的结果。 长度 1 到 256 |

## 读取 Entry

`mira.entries.read`

按 id 读取一个 Entry：搜索命中、上下文条目或引用的文本，包括没有路径的内容（导入的文本、网页、对话）。片段不够、需要上下文时调用它。长文本分窗口返回：从 `content_window.next_offset` 继续。按路径已知的文件，用 `mira.files.read`。

**注解** `readOnlyHint` `idempotentHint`

### 参数

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `entry_id` | `string` | 必填 | Entry 的 id，如搜索命中、上下文条目或引用里的 `entry_id`。 长度 1 到 256 |
| `view` | `text \| meta \| table` | 可选 | `text`（默认）、`table` 或 `meta`。 |
| `version` | `string` | 可选 | 读取这个版本，如命中里的 `version_id`。不传时读取最新版本。不能与 `meta` 视图同时使用。 长度 1 到 256 |
| `offset` | `integer` | 可选 | 窗口的起点，以字符计：上一次调用返回的 `content_window.next_offset`。仅用于 `text`。 不小于 0 |
| `max_chars` | `integer` | 可选 | 窗口大小，以字符计。默认 16000，最多 100000。仅用于 `text`。 1 到 100000 |

## 带引用回答

`mira.answer`

根据已保存的内容回答问题，并引用来源。用户想要答案本身、而不是用于工作的材料时调用它；要为你自己的推理收集上下文，用 `mira.context`。它返回 `status`（`answered` 或 `abstained`）、带 `[c1]` 这类标记的 `answer`、`citations`（这些标记指向的片段，带 `entry_id`、路径和日期）以及 `pack_id`。`status` 为 `abstained` 表示已保存的内容不能回答这个问题：如实说明，不要凭记忆回答。回答需要几秒钟。

**注解** `readOnlyHint` `idempotentHint`

`tools/list` 为它提供 `outputSchema`；从协议版本 `2025-06-18` 起，调用成功时还返回 `structuredContent`。

### 参数

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `question` | `string` | 必填 | 问题，使用用户的语言。 长度 1 到 4000 |
| `space_ids` | `string[]` | 可选 | 要读取的 Space：id、`default` 或 `ext:<external_id>`。不传时读取 Key 能读的全部 Space，而不只是你的默认 Space；只针对一个用户或项目时传一个 Space。能读超过 200 个 Space 的 Key 必须指定 Space。 1 到 64 项 |
| `tier` | `fast \| standard \| deep` | 可选 | `fast` 只按词匹配。`standard`（默认）增加语义检索和重排序。`deep` 考察的候选是默认的两倍。 |
| `budget_tokens` | `integer` | 可选 | 模型读取的证据的 token 预算。默认 4000。 500 到 16000 |
| `weights` | `object` | 可选 | 每个来源 0 到 1 的偏好。`0` 关闭这个来源。建议不传：此时不使用近期修改和技能，这适合问答。 |
| `weights.memory` | `number` | 可选 | 0 到 1 |
| `weights.agent_profile` | `number` | 可选 | 0 到 1 |
| `weights.skills` | `number` | 可选 | 0 到 1 |
| `weights.files` | `number` | 可选 | 0 到 1 |
| `weights.changes` | `number` | 可选 | 0 到 1 |
| `weights.knowledge` | `number` | 可选 | 0 到 1 |
| `history` | `object[]` | 可选 | 这段对话之前的轮次，最早的在前，以便理解追问。最多 10 轮。 最多 10 项 |
| `history[].role` | `user \| assistant` | 必填 |  |
| `history[].content` | `string` | 必填 | 长度 1 到 4000 |
| `output_language` | `string` | 可选 | 回答使用的语言，BCP 47 标签，如 `en` 或 `zh-CN`。默认与问题的语言相同。 长度 1 到 35 |
| `include` | `"evidence"[]` | 可选 | `["evidence"]` 还会列出模型读过的每个片段（不含正文），而不只是被引用的片段。 1 项 |
| `filter` | `object` | 可选 | 按 `metadata`（精确匹配；`{any: [...]}` 匹配列出的任一值）、`source_types` 以及 `occurred_from` / `occurred_to`（RFC 3339，含两端）收窄。至少给出一个条件。记忆没有元数据，所以按元数据筛选时不包含记忆。 |
| `filter.metadata` | `object` | 可选 |  |
| `filter.source_types` | `string[]` | 可选 | 1 到 8 项 |
| `filter.occurred_from` | `string (date-time)` | 可选 |  |
| `filter.occurred_to` | `string (date-time)` | 可选 |  |
| `reference_time` | `string (date-time)` | 可选 | 查询或任务中的相对时间（昨天、上周）从哪一刻算起，RFC 3339。默认是此刻。 |
| `timezone` | `string` | 可选 | 提问者的 IANA 时区，如 `Asia/Shanghai`。默认是部署的时区。 长度 1 到 64 |

## 更正记忆

`mira.memory.correct`

一步把一条记忆替换为更正后的陈述：旧记忆关闭，新记忆取而代之。用户说某条已保存的记忆有误或其中的值已经变化，而你知道正确的说法时调用它（“不是上海，是杭州”）。用 `mira.memory.list` 查找 id。旧陈述保留为历史记录，不会被彻底删除。结果是新记忆，其中的 `supersedes` 指出被它替换的那一条。要删除一条记忆而不替换，用 `mira.memory.forget`。

### 参数

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `memory_id` | `string` | 必填 | 要替换的记忆的 id，来自 `mira.memory.list`。 长度 1 到 256 |
| `text` | `string` | 必填 | 更正后的陈述，一两句话。 长度 1 到 2000 |
| `idempotency_key` | `string` | 可选 | 只在 24 小时内重试完全相同的调用时发送同一个键：服务会再次返回第一次的结果。 长度 1 到 256 |

## 审核候选记忆

`mira.memory.review`

处理一条等待审核的记忆（在 `mira.memory.list` 中 `status` 为 `candidate`）。只在用户告诉你这条候选是否正确之后调用它：`confirm` 让它生效，`reject` 将它排除，并且同一句话在这个 Space 里不会再被提炼。不要自行判断后确认。

**注解** `idempotentHint`

### 参数

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `memory_id` | `string` | 必填 | 候选记忆的 id，来自 `mira.memory.list`。 长度 1 到 256 |
| `decision` | `confirm \| reject` | 必填 | `confirm` 或 `reject`。 |

## 列出废纸篓

`mira.trash.list`

列出一个 Space 的废纸篓里有什么：每个 Entry 带 id、原来的路径和删除时间。用户想找回被删除的内容时调用它，为 `mira.trash.restore` 找到 id。

**注解** `readOnlyHint` `idempotentHint`

`tools/list` 为它提供 `outputSchema`；从协议版本 `2025-06-18` 起，调用成功时还返回 `structuredContent`。

### 参数

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `space_id` | `string` | 可选 | Space id，或 `ext:<external_id>`（带有你自己的 id 的 Space）。不传时用你的默认 Space。 长度 1 到 256 |
| `limit` | `integer` | 可选 | 每页条数。默认 50。 1 到 200 |
| `cursor` | `string` | 可选 | 上一页返回的 `next_cursor`。 长度 1 到 1024 |

## 从废纸篓恢复

`mira.trash.restore`

把废纸篓里的一个 Entry 恢复到原来的路径。用户要求撤销删除时调用它。如果另一个文件已经占用了这个路径，调用以 `path_conflict` 失败，不会自动改名：先移动或删除那个文件，或者告知用户。已彻底删除的 Entry 无法恢复。

**注解** `idempotentHint`

### 参数

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `entry_id` | `string` | 必填 | 废纸篓里的 Entry 的 id，来自 `mira.trash.list`。 长度 1 到 256 |
| `idempotency_key` | `string` | 可选 | 只在 24 小时内重试完全相同的调用时发送同一个键：服务会再次返回第一次的结果。 长度 1 到 256 |

## 读取记忆（需要部署开启）

`mira.memory.get`

> 这个工具需要部署开启离线整理（`memory-dreaming`）。未开启的部署上没有这个工具。

按 id 读取一条记忆，以及它所依据的版本和引文。依赖或更正一条记忆之前，用它核实记忆的来源。id 来自 `mira.memory.list`，或 `/.mirabase/memory/MEMORY.md`、`RECENT.md` 的 References 部分。

**注解** `readOnlyHint` `idempotentHint`

`tools/list` 为它提供 `outputSchema`；从协议版本 `2025-06-18` 起，调用成功时还返回 `structuredContent`。

### 参数

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `memory_id` | `string` | 必填 | 记忆的 id。 长度 1 到 256 |
| `include_provenance` | `boolean` | 可选 | 默认 `true`。为 `false` 时不返回来源。 |
