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

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

MCP 握手

GET/mcp

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

需要的能力 不检查能力。

指南:连接 Agent(MCP)

响应

响应头

  • Mcp-Protocol-Version

错误状态

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

请求示例

curl
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 错误结构见 错误,各错误码的含义见 错误码。

请求示例

curl
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 的能力允许调用的工具。

显示 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_idstringSpace id,或 ext:<external_id>(带有你自己的 id 的 Space)。不传时用你的默认 Space。长度 1 到 256
pathstring要列出的目录。不传时列出根目录。长度 1 到 4096
recursiveboolean为 true 时列出整棵子树。
cursorstring上一页返回的 next_cursor。长度 1 到 1024
limitinteger每页最多返回的节点数。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_idstringSpace id,或 ext:<external_id>(带有你自己的 id 的 Space)。不传时用你的默认 Space。长度 1 到 256
path必填string绝对路径,如 /notes/plan.md。长度 1 到 4096
viewtext | meta | tabletext(默认)、table 或 meta。
versionstring读取这个旧版本。不传时读取最新版本。长度 1 到 256
offsetinteger窗口的起点,以字符计:上一次调用返回的 content_window.next_offset。仅用于 text。不小于 0
max_charsinteger窗口大小,以字符计。默认 16000,最多 100000。仅用于 text。1 到 100000

写入文件

mira.files.write

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

注解 idempotentHint

参数

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

编辑文件

mira.files.edit

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

参数

字段类型说明
space_idstringSpace 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_allboolean默认 false
if_matchstring你上次读到的 etag(meta 视图中的 file.etag,或 mira.files.list 返回的 etag)。如果文件在那之后有变更,调用以 412 precondition_failed 失败。长度 1 到 256
session_idstring本次修改所属对话的 id,由你指定,与传给 mira.conversation.ingest 的相同。它记录在版本上。长度 1 到 256
wait_secondsinteger等待索引完成后再返回的最长秒数。无论是否等到,写入都已提交。1 到 10
idempotency_keystring只在 24 小时内重试完全相同的调用时发送同一个键:服务会再次返回第一次的结果。长度 1 到 256

把文件移入废纸篓

mira.files.delete

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

注解 destructiveHint idempotentHint

参数

字段类型说明
space_idstringSpace id,或 ext:<external_id>(带有你自己的 id 的 Space)。不传时用你的默认 Space。长度 1 到 256
path必填string绝对路径,如 /notes/plan.md。长度 1 到 4096
if_matchstring你上次读到的 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_idsstring[]要读取的 Space:id、default 或 ext:<external_id>。不传时读取 Key 能读的全部 Space,而不只是你的默认 Space;只针对一个用户或项目时传一个 Space。能读超过 200 个 Space 的 Key 必须指定 Space。1 到 64 项
pathstring只返回这棵子树或这一个文件里的结果。长度 1 到 4096
include"memory"[]["memory"] 让结果包含记忆。1 项
limitinteger最多返回的命中数。默认 20,最多 50。1 到 50
filterobject按 metadata(精确匹配;{any: [...]} 匹配列出的任一值)、source_types 以及 occurred_from / occurred_to(RFC 3339,含两端)收窄。至少给出一个条件。记忆没有元数据,所以按元数据筛选时不包含记忆。
filter.metadataobject
filter.source_typesstring[]1 到 8 项
filter.occurred_fromstring (date-time)
filter.occurred_tostring (date-time)
reference_timestring (date-time)查询或任务中的相对时间(昨天、上周)从哪一刻算起,RFC 3339。默认是此刻。
timezonestring提问者的 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_idsstring[]要读取的 Space:id、default 或 ext:<external_id>。不传时读取 Key 能读的全部 Space,而不只是你的默认 Space;只针对一个用户或项目时传一个 Space。能读超过 200 个 Space 的 Key 必须指定 Space。1 到 64 项
purposetask | coding | research | audit决定预算在各来源之间如何分配。不传时根据任务推断。
weightsobject每个来源 0 到 1 的偏好。0 关闭这个来源。
weights.memorynumber0 到 1
weights.agent_profilenumber0 到 1
weights.skillsnumber0 到 1
weights.filesnumber0 到 1
weights.changesnumber0 到 1
weights.knowledgenumber0 到 1
tierfast | standard | deepfast 只按词匹配,不调用模型。standard(默认)增加语义检索和重排序。deep 考察的候选是默认的两倍。
budget_tokensinteger整个响应的 token 预算,500 到 16000。默认 4000。500 到 16000
have_memory_etagstring上一个上下文包返回的 memory_view_etag。memory_view 没有变化时不再返回。长度 1 到 128
filterobject按 metadata(精确匹配;{any: [...]} 匹配列出的任一值)、source_types 以及 occurred_from / occurred_to(RFC 3339,含两端)收窄。至少给出一个条件。记忆没有元数据,所以按元数据筛选时不包含记忆。
filter.metadataobject
filter.source_typesstring[]1 到 8 项
filter.occurred_fromstring (date-time)
filter.occurred_tostring (date-time)
reference_timestring (date-time)查询或任务中的相对时间(昨天、上周)从哪一刻算起,RFC 3339。默认是此刻。
timezonestring提问者的 IANA 时区,如 Asia/Shanghai。默认是部署的时区。长度 1 到 64

报告用到的上下文

mira.context.feedback

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

注解 idempotentHint

参数

字段类型说明
pack_id必填stringmira.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_idstringSpace id,或 ext:<external_id>(带有你自己的 id 的 Space)。不传时用你的默认 Space。长度 1 到 256
daysinteger回看多少天。默认 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_idstring只列这个 Space 的记忆;default 指你的默认 Space,ext:<external_id> 指带有你自己的 id 的 Space。不传时列出你能读的全部 Space,加上你的账户记忆:这个工具不会退回到你的默认 Space。长度 1 到 256
scopeproject | agent | account只保留一种范围的记忆。
statuscandidate | confirmed | rejected | supersededcandidate 等待审核,检索不使用;confirmed 检索会使用;rejected 和 superseded 是历史记录。
kindstring只保留一种类型,如 preference、decision 或 progress。长度 1 到 64
qstring记忆正文必须包含的短语:字面匹配,不区分大小写。长度 1 到 200
cursorstring上一页返回的 next_cursor。长度 1 到 1024
limitinteger每页最多返回的记忆数。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 | accountagent:你自己在一个 Space 里的笔记,只有你和 Space 所有者能读;需要 Agent 的 Key。project:与 Space 里的所有人共享;需要 memory:confirm,并且你是 Space 所有者,或者你是在这个 Space 里写入模式为 direct 的 Agent。account:跨 Space 跟随一个人;需要 memory:confirm,Agent 的 Key 以及限定了 Space 或元数据的 Key 会被拒绝。
space_idstring用于 project 和 agent 记忆。不传时用你的默认 Space。账户记忆不需要传。长度 1 到 256
kind必填string对 project 和 agent,取以下之一:preference(某人希望事情怎么做)、decision(已经定下的事,包括可以依据的事实)、progress(未完成的工作进行到哪里)。账户记忆有自己的类型,如 role、preference、commitment、person 或 fact。长度 1 到 64
text必填string陈述,一两句话,最多 2000 字符。最短 1
pinnedboolean为 true 时,在 memory_view 中排在未置顶的记忆之前。不适用于账户记忆。
idempotency_keystring只在 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_idstringSpace id,或 ext:<external_id>(带有你自己的 id 的 Space)。不传时用你的默认 Space。长度 1 到 256
session_id必填string你为这段对话指定的 id。同一段对话的每一批都使用同一个值,它修改的文件也使用这个值。长度 1 到 256
messages必填object[]1 到 1000 条消息,按说出的先后顺序排列。1 到 1000 项
messages[].role必填stringuser、assistant 或其他说话人。长度 1 到 64
messages[].content必填string说了什么,以文本表示。最短 1
messages[].timestampstring (date-time)说话的时间,RFC 3339。
messages[].nameany接收但忽略。
messages[].tool_callsany接收但忽略。
messages[].tool_call_idany接收但忽略。
messages[].function_callany接收但忽略。
titlestring默认为 Conversation <session_id>。长度 1 到 512
redact_secretsboolean请设为 true。它在保存任何内容之前替换看起来像凭据的内容(私钥、JWT、Bearer 令牌、常见的 API Key 格式、password=...),结果中的 secrets_redacted 是替换的次数。这是一道安全网,不是保证。
memory_instructionsstring应用规定的、从这段对话中记住什么和忽略什么的规则,最多 2000 字符,如“记住饮食限制和过敏;忽略闲聊”。应用给了你这样的规则时传入,否则不传。每条记忆仍必须有消息中的引文作为依据。长度 1 到 2000
idempotency_keystring只在 24 小时内重试完全相同的调用时发送同一个键:服务会再次返回第一次的结果。长度 1 到 256

保存文本

mira.text.ingest

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

参数

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

保存网页

mira.url.ingest

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

注解 openWorldHint

参数

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

读取 Entry

mira.entries.read

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

注解 readOnlyHint idempotentHint

参数

字段类型说明
entry_id必填stringEntry 的 id,如搜索命中、上下文条目或引用里的 entry_id。长度 1 到 256
viewtext | meta | tabletext(默认)、table 或 meta。
versionstring读取这个版本,如命中里的 version_id。不传时读取最新版本。不能与 meta 视图同时使用。长度 1 到 256
offsetinteger窗口的起点,以字符计:上一次调用返回的 content_window.next_offset。仅用于 text。不小于 0
max_charsinteger窗口大小,以字符计。默认 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_idsstring[]要读取的 Space:id、default 或 ext:<external_id>。不传时读取 Key 能读的全部 Space,而不只是你的默认 Space;只针对一个用户或项目时传一个 Space。能读超过 200 个 Space 的 Key 必须指定 Space。1 到 64 项
tierfast | standard | deepfast 只按词匹配。standard(默认)增加语义检索和重排序。deep 考察的候选是默认的两倍。
budget_tokensinteger模型读取的证据的 token 预算。默认 4000。500 到 16000
weightsobject每个来源 0 到 1 的偏好。0 关闭这个来源。建议不传:此时不使用近期修改和技能,这适合问答。
weights.memorynumber0 到 1
weights.agent_profilenumber0 到 1
weights.skillsnumber0 到 1
weights.filesnumber0 到 1
weights.changesnumber0 到 1
weights.knowledgenumber0 到 1
historyobject[]这段对话之前的轮次,最早的在前,以便理解追问。最多 10 轮。最多 10 项
history[].role必填user | assistant
history[].content必填string长度 1 到 4000
output_languagestring回答使用的语言,BCP 47 标签,如 en 或 zh-CN。默认与问题的语言相同。长度 1 到 35
include"evidence"[]["evidence"] 还会列出模型读过的每个片段(不含正文),而不只是被引用的片段。1 项
filterobject按 metadata(精确匹配;{any: [...]} 匹配列出的任一值)、source_types 以及 occurred_from / occurred_to(RFC 3339,含两端)收窄。至少给出一个条件。记忆没有元数据,所以按元数据筛选时不包含记忆。
filter.metadataobject
filter.source_typesstring[]1 到 8 项
filter.occurred_fromstring (date-time)
filter.occurred_tostring (date-time)
reference_timestring (date-time)查询或任务中的相对时间(昨天、上周)从哪一刻算起,RFC 3339。默认是此刻。
timezonestring提问者的 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_keystring只在 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 | rejectconfirm 或 reject。

列出废纸篓

mira.trash.list

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

注解 readOnlyHint idempotentHint

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

参数

字段类型说明
space_idstringSpace id,或 ext:<external_id>(带有你自己的 id 的 Space)。不传时用你的默认 Space。长度 1 到 256
limitinteger每页条数。默认 50。1 到 200
cursorstring上一页返回的 next_cursor。长度 1 到 1024

从废纸篓恢复

mira.trash.restore

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

注解 idempotentHint

参数

字段类型说明
entry_id必填string废纸篓里的 Entry 的 id,来自 mira.trash.list。长度 1 到 256
idempotency_keystring只在 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_provenanceboolean默认 true。为 false 时不返回来源。