Skip to content
Developer docs
Docs menu

The same API as Model Context Protocol tools, for Agents.

MCP handshake

GET/mcp

MCP handshake over Streamable HTTP. Accept: text/event-stream alone returns 405: this service does not push. Needs no capability of its own: tools lists only the tools the key's capabilities allow.

Capability No capability is checked.

Guide: Connect an Agent (MCP)

Responses

Response headers

  • Mcp-Protocol-Version

Error statuses

400 401 403 404 405 422 429 500 503 See Errors for the error shape and Error codes for what each code means.

Example request

curl
curl "https://api.mirabase.dev/mcp" \
  -H "Authorization: Bearer $MIRABASE_API_KEY"

Example response

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

Call MCP

POST/mcp

The MCP JSON-RPC endpoint. A request is rate limited as a read, and each tool call is then limited as the /v2 request it makes, so one tool call uses two tokens. Needs no capability of its own: each tool checks the capability it needs, and tools/list lists only the tools the key's capabilities allow. x-mirabase-mcp-tools on this operation lists every tool as tools/list returns it: name, title, description, annotations, inputSchema, and, for the read-only tools with a stable result, outputSchema. A tool with feature exists only on deployments that enable that feature. Supported protocol versions are 2025-11-25, 2025-06-18, 2025-03-26, and 2024-11-05. initialize uses the version the client asks for when it is supported, otherwise 2025-11-25. Later requests follow the MCP-Protocol-Version header: without it a request is treated as 2025-03-26, and an unsupported version returns 400 with JSON-RPC error -32000. From 2025-06-18, tools/list includes outputSchema and a successful call of such a tool also returns structuredContent. Arguments that do not match inputSchema return JSON-RPC error -32602 before 2025-11-25, and from 2025-11-25 a tool result with isError: true and code validation_error.

Capability No capability is checked.

Request body

text/plain DevMcpRequest A JSON-RPC 2.0 request, or a batch of up to 32. Methods are defined by MCP; tools/call takes a tool from x-mirabase-mcp-tools and arguments that match its inputSchema.

Responses

  • 200 text/plain DevMcpResponse, text/event-stream; charset=utf-8 string
  • 202 No response body

Response headers

  • Mcp-Protocol-Version

Error statuses

400 401 403 404 422 429 500 503 See Errors for the error shape and Error codes for what each code means.

Example request

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

Every tool tools/list returns. A tool's arguments are the fields of arguments in tools/call; tools/list lists only the tools the key's capabilities allow.

Show key identity

mira.whoami

Returns who this key acts as: the principal and its kind (human or agent), effective_capabilities and any Spaces or metadata the key is limited to. Call it after a 403 or 404 you did not expect, and before you choose a scope for mira.memory.remember.

Annotations readOnlyHint idempotentHint

tools/list gives it an outputSchema; from protocol version 2025-06-18, a successful call also returns structuredContent.

Arguments

Takes no arguments.

List files

mira.files.list

Lists a directory: each file with its path, size_bytes, etag and modified_at. Call it to see what a Space already holds before you choose a path for a new file, or when you know the folder but not the file name. To find a file by what it says, use mira.search.

Annotations readOnlyHint idempotentHint

tools/list gives it an outputSchema; from protocol version 2025-06-18, a successful call also returns structuredContent.

Arguments

FieldTypeDescription
space_idstringSpace id, or ext:<external_id> for the Space that carries your own id. Omit to use your default Space.length 1..256
pathstringDirectory to list. Omit for the root.length 1..4096
recursivebooleantrue lists the whole subtree.
cursorstringnext_cursor from the previous page.length 1..1024
limitintegerMaximum number of nodes per page.1..100

Read file

mira.files.read

Reads one file by path. view text (the default) returns its text in windows: while content_window.truncated is true, call again with offset set to content_window.next_offset. view table returns the columns and rows of a CSV file or spreadsheet. view meta returns the Entry, with file.etag to pass as if_match and knowledge.state for indexing progress. view text works on a text file as soon as it is written. view table, and view text of any other format, return 404 content_not_ready until processing finishes: read again shortly. 422 view_not_available means the file has no such view.

Annotations readOnlyHint idempotentHint

Arguments

FieldTypeDescription
space_idstringSpace id, or ext:<external_id> for the Space that carries your own id. Omit to use your default Space.length 1..256
pathRequiredstringAbsolute path, such as /notes/plan.md.length 1..4096
viewtext | meta | tabletext (the default), table or meta.
versionstringRead this older version. Omit for the latest.length 1..256
offsetintegerWhere the window starts, in characters: content_window.next_offset from the previous call. view text only.>= 0
max_charsintegerWindow size in characters. Defaults to 16000, at most 100000. view text only.1..100000

Write file

mira.files.write

Creates or replaces a text file at a path. Call it when a task produces a document meant for later use (notes, a report, a plan, a specification or a table as CSV with media_type text/csv), or when the user asks you to keep a text. Use a stable path and write later versions to the same path: every write adds a version and earlier versions are kept (identical content adds none), so do not create copies such as plan-v2.md. The write is committed and readable when the call returns; text up to 64 KiB is searchable by its words on the next call, and by meaning once indexed. content is text: this tool cannot carry binary files. Not for a single fact or preference (use mira.memory.remember), and never for scratch output or for passwords, keys or tokens.

Annotations idempotentHint

Arguments

FieldTypeDescription
space_idstringSpace id, or ext:<external_id> for the Space that carries your own id. Omit to use your default Space.length 1..256
pathRequiredstringAbsolute path, such as /notes/plan.md. Missing directories are created.length 1..4096
contentRequiredstringThe whole file, as text.
media_typestringDefaults to text/markdown. Use text/csv for a table.length 1..256
if_matchstringThe etag you last read (file.etag from view meta, or etag from mira.files.list). The call fails with 412 precondition_failed if the file has changed since.length 1..256
create_onlybooleantrue fails with 412 precondition_failed if the file already exists.
session_idstringYour id for the conversation this change came from, the same one you pass to mira.conversation.ingest. It is stored on the version.length 1..256
wait_secondsintegerHold the response up to this many seconds until indexing finishes. The write is committed either way.1..10
idempotency_keystringSend the same key only to retry the identical call within 24 hours: the first result is returned again.length 1..256

Edit file

mira.files.edit

Replaces exact text in an existing UTF-8 text file and commits a new version. Call it when you correct or extend part of a file, instead of writing the whole file again. If any edit fails to match, nothing changes (422 edit_no_match or edit_ambiguous). A file over 1 MiB cannot be edited: replace it with mira.files.write.

Arguments

FieldTypeDescription
space_idstringSpace id, or ext:<external_id> for the Space that carries your own id. Omit to use your default Space.length 1..256
pathRequiredstringAbsolute path, such as /notes/plan.md.length 1..4096
editsRequiredobject[]1 to 100 replacements, applied in order. old_text must appear exactly once in the file, or set replace_all to true to replace every occurrence. new_text may be empty to delete.items 1..100
edits[].old_textRequiredstringmin length 1
edits[].new_textRequiredstring
edits[].replace_allbooleandefault: false
if_matchstringThe etag you last read (file.etag from view meta, or etag from mira.files.list). The call fails with 412 precondition_failed if the file has changed since.length 1..256
session_idstringYour id for the conversation this change came from, the same one you pass to mira.conversation.ingest. It is stored on the version.length 1..256
wait_secondsintegerHold the response up to this many seconds until indexing finishes. The write is committed either way.1..10
idempotency_keystringSend the same key only to retry the identical call within 24 hours: the first result is returned again.length 1..256

Move file to trash

mira.files.delete

Moves a file to the trash. Use it when a file is obsolete or was written by mistake; to change what a file says, write or edit it instead. mira.trash.restore brings it back, with the entry_id from mira.trash.list.

Annotations destructiveHint idempotentHint

Arguments

FieldTypeDescription
space_idstringSpace id, or ext:<external_id> for the Space that carries your own id. Omit to use your default Space.length 1..256
pathRequiredstringAbsolute path, such as /notes/plan.md.length 1..4096
if_matchstringThe etag you last read (file.etag from view meta, or etag from mira.files.list). The call fails with 412 precondition_failed if the file has changed since.length 1..256

Search

mira.search

Searches for something specific and returns ranked passages, each with its entry_id, citation_id and path or url. Call it when you know what you are looking for, and before you state what was said, decided or stored earlier. include ["memory"] also searches memories. Text up to 64 KiB is searchable by its words right after it is written, and by meaning after indexing finishes. pending_processing in the result means that many Entries in the searched Spaces are still being processed and may be missing: search again shortly if what you need could be among them. To gather context for a whole task, use mira.context.

Annotations readOnlyHint idempotentHint

tools/list gives it an outputSchema; from protocol version 2025-06-18, a successful call also returns structuredContent.

Arguments

FieldTypeDescription
queryRequiredstringWhat to look for, in natural language or keywords.length 1..1000
space_idsstring[]Spaces to read from: ids, default, or ext:<external_id>. Omit to read every Space the key can read, not only your default Space; pass one Space to keep to one user or project. A key that can read more than 200 Spaces must name them.items 1..64
pathstringRestrict results to this subtree or file.length 1..4096
include"memory"[]["memory"] adds memories to the results.items 1..1
limitintegerMaximum number of hits. Defaults to 20, at most 50.1..50
filterobjectNarrow by metadata (exact match; {any: [...]} matches any listed value), source_types and occurred_from / occurred_to (RFC 3339, inclusive). Give at least one condition. Memories have no metadata, so a metadata filter leaves them out.
filter.metadataobject
filter.source_typesstring[]items 1..8
filter.occurred_fromstring (date-time)
filter.occurred_tostring (date-time)
reference_timestring (date-time)The moment relative time in the query or task (yesterday, last week) is counted from, RFC 3339. Defaults to now.
timezonestringIANA time zone of the person asking, such as Asia/Shanghai. Defaults to the deployment's.length 1..64

Build task context

mira.context

Builds the context for a task within a token budget. Call it before you plan a task, and again when the task changes. It returns pack_id, memory_view (the confirmed memories, the same for every task), items (passages chosen for this task from memories, files the task names, recent changes, knowledge and skills, each with a citation_id) and route (which sources were used and why). An item whose source is skills is a one-line summary of a file under /.mirabase/skills/: read the file at its path for the body. After you use items, report them with mira.context.feedback.

Annotations readOnlyHint idempotentHint

tools/list gives it an outputSchema; from protocol version 2025-06-18, a successful call also returns structuredContent.

Arguments

FieldTypeDescription
taskRequiredstringThe task in one or two sentences, up to 1000 characters, in the user's language. Name a file's path to have that file included.length 1..1000
space_idsstring[]Spaces to read from: ids, default, or ext:<external_id>. Omit to read every Space the key can read, not only your default Space; pass one Space to keep to one user or project. A key that can read more than 200 Spaces must name them.items 1..64
purposetask | coding | research | auditSets how the budget is split between sources. Omit to have it inferred from the task.
weightsobjectPer-source preference from 0 to 1. 0 turns a source off.
weights.memorynumber0..1
weights.agent_profilenumber0..1
weights.skillsnumber0..1
weights.filesnumber0..1
weights.changesnumber0..1
weights.knowledgenumber0..1
tierfast | standard | deepfast matches words only and calls no model. standard (the default) adds semantic search and reranking. deep considers twice as many candidates.
budget_tokensintegerToken budget for the whole response, 500 to 16000. Defaults to 4000.500..16000
have_memory_etagstringmemory_view_etag from an earlier pack. memory_view is left out while it is unchanged.length 1..128
filterobjectNarrow by metadata (exact match; {any: [...]} matches any listed value), source_types and occurred_from / occurred_to (RFC 3339, inclusive). Give at least one condition. Memories have no metadata, so a metadata filter leaves them out.
filter.metadataobject
filter.source_typesstring[]items 1..8
filter.occurred_fromstring (date-time)
filter.occurred_tostring (date-time)
reference_timestring (date-time)The moment relative time in the query or task (yesterday, last week) is counted from, RFC 3339. Defaults to now.
timezonestringIANA time zone of the person asking, such as Asia/Shanghai. Defaults to the deployment's.length 1..64

Report used context

mira.context.feedback

Reports which items of a context pack you actually used. Call it once after you finish the answer or step the pack was built for, with the citation_id of every item you relied on; do not call it if you used none. It sends ids only, no content, and repeating a report is safe.

Annotations idempotentHint

Arguments

FieldTypeDescription
pack_idRequiredstringpack_id of the mira.context result.length 1..256
used_citation_idsRequiredstring[]One or more citation ids from that pack, such as c1 and c3. An id that is not in the pack is refused.items 1..256

Show recent activity

mira.activity

Shows who changed what in a Space recently, grouped by principal and by file. Call it before you edit files in a Space that other people or Agents also write to, so that you do not overwrite work in progress.

Annotations readOnlyHint idempotentHint

tools/list gives it an outputSchema; from protocol version 2025-06-18, a successful call also returns structuredContent.

Arguments

FieldTypeDescription
space_idstringSpace id, or ext:<external_id> for the Space that carries your own id. Omit to use your default Space.length 1..256
daysintegerHow many days to look back. Defaults to 7, at most 30.1..30

List memories

mira.memory.list

Lists memories, newest first, each with its id, scope, kind, status and text. Call it to find the id of a memory to forget, to check that a statement is not already stored, or when asked exactly what is remembered. Without status it returns candidate and confirmed memories. q keeps the memories whose text contains that phrase; it is a literal match, so to search by meaning use mira.search with include ["memory"].

Annotations readOnlyHint idempotentHint

tools/list gives it an outputSchema; from protocol version 2025-06-18, a successful call also returns structuredContent.

Arguments

FieldTypeDescription
space_idstringOnly memories of this Space; default names your default Space, ext:<external_id> the Space that carries your own id. Omit for every Space you can read, plus your account memory: this tool does not fall back to your default Space.length 1..256
scopeproject | agent | accountKeep the memories of one scope.
statuscandidate | confirmed | rejected | supersededcandidate waits for review and is not used in retrieval; confirmed is used in retrieval; rejected and superseded are history.
kindstringKeep one kind, such as preference, decision or progress.length 1..64
qstringA phrase the memory text must contain: a literal match that ignores case.length 1..200
cursorstringnext_cursor from the previous page.length 1..1024
limitintegerMaximum number of memories per page.1..100

Remember statement

mira.memory.remember

Writes one confirmed memory: a single self-contained statement that stays true beyond this conversation. Call it when the user states a lasting preference, decision or fact ("from now on", "we decided", "remember that"), or when you stop with work unfinished (kind progress). To replace a wrong or outdated memory, use mira.memory.correct. The memory is listed by mira.memory.list when the call returns, and appears in memory_view and in mira.search after processing. First check that it is not already stored, with mira.search (include ["memory"]) or mira.memory.list: the identical statement returns the existing memory; a reworded one is stored as new. Do not store documents or tables (use mira.files.write), whole conversations (use mira.conversation.ingest), a memory that contradicts an existing one, or passwords, keys or tokens.

Annotations idempotentHint

Arguments

FieldTypeDescription
scopeRequiredproject | agent | accountagent: your own notes in a Space, readable only by you and the Space owner; needs an Agent key. project: shared with everyone in the Space; needs memory:confirm, and either you own the Space or you are an Agent whose write mode there is direct. account: follows one person across Spaces; needs memory:confirm, and is refused for Agent keys and for keys limited to certain Spaces or metadata.
space_idstringFor project and agent memory. Omit to use your default Space. Account memory takes none.length 1..256
kindRequiredstringFor project and agent, one of: preference (how someone wants things done), decision (something settled, including a fact to rely on), progress (where unfinished work stands). Account memory has its own kinds, such as role, preference, commitment, person or fact.length 1..64
textRequiredstringThe statement, in one or two sentences, at most 2000 characters.min length 1
pinnedbooleantrue lists it ahead of unpinned memories in memory_view. Not for account memory.
idempotency_keystringSend the same key only to retry the identical call within 24 hours: the first result is returned again.length 1..256

Forget memory

mira.memory.forget

Erases one memory permanently; it cannot be undone. Call it only when the user asks you to forget something. To replace a wrong or outdated memory, use mira.memory.correct, which keeps the old statement as history. Find the id with mira.memory.list. A memory distilled from a conversation is not distilled again; the source conversation stays searchable and is returned as remaining_sources.

Annotations destructiveHint idempotentHint

Arguments

FieldTypeDescription
memory_idRequiredstringid of the memory, from mira.memory.list.length 1..256

Store conversation

mira.conversation.ingest

Stores a batch of conversation messages as one new Entry and lets the service decide what to remember from it. Call it when a task or conversation ends, or before its context is compacted, unless the host application or a plugin already saves the conversation or tells you not to send it. Send only the user and assistant messages you have not sent before: a message sent again in another call is stored twice. The conversation becomes searchable, and memories are distilled from it after the call returns. memory_status in the result says whether they take effect: confirmed, or candidate when the key lacks memory:confirm or is an Agent in proposal write mode. Candidate memories are not used in retrieval until someone confirms them (mira.memory.review, on the user's word). Do not include tool output or secrets.

Arguments

FieldTypeDescription
space_idstringSpace id, or ext:<external_id> for the Space that carries your own id. Omit to use your default Space.length 1..256
session_idRequiredstringYour id for the conversation. Use the same one for every batch of that conversation, and for the files it changes.length 1..256
messagesRequiredobject[]1 to 1000 messages, in the order they were said.items 1..1000
messages[].roleRequiredstringuser, assistant or any other speaker.length 1..64
messages[].contentRequiredstringWhat was said, as text.min length 1
messages[].timestampstring (date-time)When it was said, RFC 3339.
messages[].nameanyAccepted and ignored.
messages[].tool_callsanyAccepted and ignored.
messages[].tool_call_idanyAccepted and ignored.
messages[].function_callanyAccepted and ignored.
titlestringDefaults to Conversation <session_id>.length 1..512
redact_secretsbooleanSet it to true. It replaces what looks like a credential (private keys, JWTs, bearer tokens, common API key formats, password=...) before anything is stored, and secrets_redacted in the result counts the replacements. It is a safety net, not a guarantee.
memory_instructionsstringThe application's rule for what to remember from this conversation and what to ignore, up to 2000 characters, such as "Remember dietary restrictions and allergies; ignore small talk". Send it when the application gave you such a rule; otherwise omit it. Every memory still has to be backed by a quote from the messages.length 1..2000
idempotency_keystringSend the same key only to retry the identical call within 24 hours: the first result is returned again.length 1..256

Store text

mira.text.ingest

Stores a text as one new Entry without a path: an email, a meeting transcript, a message, a pasted document. Call it when the user gives you a text to keep that does not belong at a file path; for something you will edit or read back by name, use mira.files.write instead. It is searchable by its words right away and by meaning after indexing. Returns entry_id, version_id and job_id.

Arguments

FieldTypeDescription
space_idstringSpace id, or ext:<external_id> for the Space that carries your own id. Omit to use your default Space.length 1..256
textRequiredstringThe text to store, up to 2,000,000 characters.length 1..2000000
titlestringDefaults to the first line.length 1..512
occurred_atstring (date-time)When the content happened, RFC 3339, such as the date of the meeting or email. Search by time range and questions about what is current go by it.
metadataobjectLabels to filter by later, such as {"customer": "acme"}. Keys are 1 to 64 of a-z, 0-9, '_', '.', '-'; each value is a string or a list of strings, at most 32 values in all.
redact_secretsbooleantrue replaces what looks like a credential before anything is stored. A safety net, not a guarantee.
idempotency_keystringSend the same key only to retry the identical call within 24 hours: the first result is returned again.length 1..256

Store web page

mira.url.ingest

Fetches a public web page and stores its readable text as one new Entry. Call it when the user asks you to save or remember a link. The page is fetched by the service, not by you; a page that cannot be fetched or has no readable text fails with url_fetch_failed or url_no_readable_content. Returns entry_id, version_id and job_id; the text is searchable once the job succeeds.

Annotations openWorldHint

Arguments

FieldTypeDescription
space_idstringSpace id, or ext:<external_id> for the Space that carries your own id. Omit to use your default Space.length 1..256
urlRequiredstringAn http or https URL.length 1..8192
titlestringA title for the Entry. Defaults to the page's own.length 1..512
occurred_atstring (date-time)When the page's content happened, RFC 3339, if you know it.
metadataobjectLabels to filter by later, such as {"customer": "acme"}. Keys are 1 to 64 of a-z, 0-9, '_', '.', '-'; each value is a string or a list of strings, at most 32 values in all.
idempotency_keystringSend the same key only to retry the identical call within 24 hours: the first result is returned again.length 1..256

Read Entry

mira.entries.read

Reads an Entry by its id: the text of a search hit, context item or citation, including content that has no path (ingested text, web pages, conversations). Call it when a passage is not enough and you need the surrounding text. Long text comes in windows: continue from content_window.next_offset. For a file you know by path, use mira.files.read.

Annotations readOnlyHint idempotentHint

Arguments

FieldTypeDescription
entry_idRequiredstringid of the Entry, such as the entry_id of a search hit, a context item or a citation.length 1..256
viewtext | meta | tabletext (the default), table or meta.
versionstringRead this version, such as the version_id of the hit. Omit for the latest. Not with view meta.length 1..256
offsetintegerWhere the window starts, in characters: content_window.next_offset from the previous call. view text only.>= 0
max_charsintegerWindow size in characters. Defaults to 16000, at most 100000. view text only.1..100000

Answer with citations

mira.answer

Answers a question from what is stored and cites its sources. Call it when the user wants the answer itself, not material to work with; to gather context for your own reasoning, use mira.context. It returns status (answered or abstained), answer with [c1]-style markers, citations (the passages those markers point to, with entry_id, path and dates) and pack_id. status abstained means the stored content does not answer the question: say so, do not answer from recollection. It takes several seconds.

Annotations readOnlyHint idempotentHint

tools/list gives it an outputSchema; from protocol version 2025-06-18, a successful call also returns structuredContent.

Arguments

FieldTypeDescription
questionRequiredstringThe question, in the user's language.length 1..4000
space_idsstring[]Spaces to read from: ids, default, or ext:<external_id>. Omit to read every Space the key can read, not only your default Space; pass one Space to keep to one user or project. A key that can read more than 200 Spaces must name them.items 1..64
tierfast | standard | deepfast matches words only. standard (the default) adds semantic search and reranking. deep considers twice as many candidates.
budget_tokensintegerToken budget for the evidence the model reads. Defaults to 4000.500..16000
weightsobjectPer-source preference from 0 to 1. 0 turns a source off. Omit it: recent changes and skills are then left out, which suits a question.
weights.memorynumber0..1
weights.agent_profilenumber0..1
weights.skillsnumber0..1
weights.filesnumber0..1
weights.changesnumber0..1
weights.knowledgenumber0..1
historyobject[]Earlier turns of this conversation, oldest first, so a follow-up question can be understood. At most 10.max items 10
history[].roleRequireduser | assistant
history[].contentRequiredstringlength 1..4000
output_languagestringBCP 47 tag of the language to answer in, such as en or zh-CN. Defaults to the question's.length 1..35
include"evidence"[]["evidence"] also lists every passage the model read (without text), not only the cited ones.items 1..1
filterobjectNarrow by metadata (exact match; {any: [...]} matches any listed value), source_types and occurred_from / occurred_to (RFC 3339, inclusive). Give at least one condition. Memories have no metadata, so a metadata filter leaves them out.
filter.metadataobject
filter.source_typesstring[]items 1..8
filter.occurred_fromstring (date-time)
filter.occurred_tostring (date-time)
reference_timestring (date-time)The moment relative time in the query or task (yesterday, last week) is counted from, RFC 3339. Defaults to now.
timezonestringIANA time zone of the person asking, such as Asia/Shanghai. Defaults to the deployment's.length 1..64

Correct memory

mira.memory.correct

Replaces one memory with a corrected statement in a single step: the old one is closed and the new one takes its place. Call it when the user says a stored memory is wrong or its value has changed and you know the right statement ("not Shanghai, Hangzhou"). Find the id with mira.memory.list. The old statement is kept as history, not erased. The result is the new memory; its supersedes names the one it replaced. To drop a memory without a replacement, use mira.memory.forget.

Arguments

FieldTypeDescription
memory_idRequiredstringid of the memory to replace, from mira.memory.list.length 1..256
textRequiredstringThe corrected statement, in one or two sentences.length 1..2000
idempotency_keystringSend the same key only to retry the identical call within 24 hours: the first result is returned again.length 1..256

Review candidate memory

mira.memory.review

Settles a memory that is waiting for review (status candidate in mira.memory.list). Call it only when the user has told you whether the candidate is right: confirm puts it to work, reject keeps it out and the same sentence is not distilled again in that Space. Do not confirm on your own judgement.

Annotations idempotentHint

Arguments

FieldTypeDescription
memory_idRequiredstringid of the candidate, from mira.memory.list.length 1..256
decisionRequiredconfirm | rejectconfirm or reject.

List trash

mira.trash.list

Lists what is in the trash of a Space: each Entry with its id, the path it had and when it was deleted. Call it when the user wants something back that was deleted, to find the id for mira.trash.restore.

Annotations readOnlyHint idempotentHint

tools/list gives it an outputSchema; from protocol version 2025-06-18, a successful call also returns structuredContent.

Arguments

FieldTypeDescription
space_idstringSpace id, or ext:<external_id> for the Space that carries your own id. Omit to use your default Space.length 1..256
limitintegerPage size. Defaults to 50.1..200
cursorstringnext_cursor from the previous page.length 1..1024

Restore from trash

mira.trash.restore

Brings one trashed Entry back, at the path it had. Call it when the user asks to undo a delete. If another file now holds that path the call fails with path_conflict and nothing is renamed: move or delete that file first, or tell the user. An Entry that was purged cannot be restored.

Annotations idempotentHint

Arguments

FieldTypeDescription
entry_idRequiredstringid of the trashed Entry, from mira.trash.list.length 1..256
idempotency_keystringSend the same key only to retry the identical call within 24 hours: the first result is returned again.length 1..256

Read memoryDeployment option

mira.memory.get

This tool needs offline consolidation (memory-dreaming) enabled on the deployment. Where it is not enabled, the tool does not exist.

Reads one memory by id, with the versions and quotes it rests on. Call it to check where a memory came from before you rely on it or correct it. The id comes from mira.memory.list, or from the References of /.mirabase/memory/MEMORY.md or RECENT.md.

Annotations readOnlyHint idempotentHint

tools/list gives it an outputSchema; from protocol version 2025-06-18, a successful call also returns structuredContent.

Arguments

FieldTypeDescription
memory_idRequiredstringid of the memory.length 1..256
include_provenancebooleanDefaults to true. false skips the sources.