MCP
Markdown 版同一套接口,以 Model Context Protocol 工具的形式提供给 Agent。
MCP 握手
GET/mcp
基于 Streamable HTTP 的 MCP 握手。仅携带 Accept: text/event-stream 时返回 405:该服务不推送。本身不需要任何能力:tools 只列出这个 Key 的能力允许的工具。
需要的能力 不检查能力。
响应
200application/jsonDevMcpHandshake
响应头
Mcp-Protocol-Version
错误状态
400 401 403 404 405 422 429 500 503 错误结构见 错误,各错误码的含义见 错误码。
请求示例
curl "https://api.mirabase.dev/mcp" \
-H "Authorization: Bearer $MIRABASE_API_KEY"响应结构示例
{
"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。
响应
200text/plainDevMcpResponse,text/event-stream; charset=utf-8string202无响应体
响应头
Mcp-Protocol-Version
错误状态
400 401 403 404 422 429 500 503 错误结构见 错误,各错误码的含义见 错误码。
请求示例
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读取 Entrymira.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。
参数
读取文件
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
参数
搜索
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。
参数
列出记忆
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
参数
列出废纸篓
mira.trash.list
列出一个 Space 的废纸篓里有什么:每个 Entry 带 id、原来的路径和删除时间。用户想找回被删除的内容时调用它,为 mira.trash.restore 找到 id。
注解 readOnlyHint idempotentHint
tools/list 为它提供 outputSchema;从协议版本 2025-06-18 起,调用成功时还返回 structuredContent。
参数
从废纸篓恢复
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 时不返回来源。 |
