# MCP

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

API reference. Base URL: `https://api.mirabase.dev`

## 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)](https://mirabase.io/developers/agents.md#protocol-versions)

### Responses

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

### Response headers

- `Mcp-Protocol-Version`

### Error statuses

`400` `401` `403` `404` `405` `422` `429` `500` `503` See [Errors](https://mirabase.io/developers/conventions.md#errors) for the error shape and [Error codes](https://mirabase.io/developers/errors.md) for what each code means.

### Example request

```bash
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](https://mirabase.io/developers/conventions.md#errors) for the error shape and [Error codes](https://mirabase.io/developers/errors.md) for what each code means.

### Example request

```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

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.

- `mira.whoami` Show key identity
- `mira.files.list` List files
- `mira.files.read` Read file
- `mira.files.write` Write file
- `mira.files.edit` Edit file
- `mira.files.delete` Move file to trash
- `mira.search` Search
- `mira.context` Build task context
- `mira.context.feedback` Report used context
- `mira.activity` Show recent activity
- `mira.memory.list` List memories
- `mira.memory.remember` Remember statement
- `mira.memory.forget` Forget memory
- `mira.conversation.ingest` Store conversation
- `mira.text.ingest` Store text
- `mira.url.ingest` Store web page
- `mira.entries.read` Read Entry
- `mira.answer` Answer with citations
- `mira.memory.correct` Correct memory
- `mira.memory.review` Review candidate memory
- `mira.trash.list` List trash
- `mira.trash.restore` Restore from trash
- `mira.memory.get` Read memory (Deployment option)

## 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

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `space_id` | `string` | Optional | Space id, or ext:<external_id> for the Space that carries your own id. Omit to use your default Space. length 1..256 |
| `path` | `string` | Optional | Directory to list. Omit for the root. length 1..4096 |
| `recursive` | `boolean` | Optional | true lists the whole subtree. |
| `cursor` | `string` | Optional | next_cursor from the previous page. length 1..1024 |
| `limit` | `integer` | Optional | Maximum 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

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `space_id` | `string` | Optional | Space id, or ext:<external_id> for the Space that carries your own id. Omit to use your default Space. length 1..256 |
| `path` | `string` | Required | Absolute path, such as /notes/plan.md. length 1..4096 |
| `view` | `text \| meta \| table` | Optional | text (the default), table or meta. |
| `version` | `string` | Optional | Read this older version. Omit for the latest. length 1..256 |
| `offset` | `integer` | Optional | Where the window starts, in characters: content_window.next_offset from the previous call. view text only. >= 0 |
| `max_chars` | `integer` | Optional | Window 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

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `space_id` | `string` | Optional | Space id, or ext:<external_id> for the Space that carries your own id. Omit to use your default Space. length 1..256 |
| `path` | `string` | Required | Absolute path, such as /notes/plan.md. Missing directories are created. length 1..4096 |
| `content` | `string` | Required | The whole file, as text. |
| `media_type` | `string` | Optional | Defaults to text/markdown. Use text/csv for a table. length 1..256 |
| `if_match` | `string` | Optional | The 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_only` | `boolean` | Optional | true fails with 412 precondition_failed if the file already exists. |
| `session_id` | `string` | Optional | Your 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_seconds` | `integer` | Optional | Hold the response up to this many seconds until indexing finishes. The write is committed either way. 1..10 |
| `idempotency_key` | `string` | Optional | Send 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

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `space_id` | `string` | Optional | Space id, or ext:<external_id> for the Space that carries your own id. Omit to use your default Space. length 1..256 |
| `path` | `string` | Required | Absolute path, such as /notes/plan.md. length 1..4096 |
| `edits` | `object[]` | Required | 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_text` | `string` | Required | min length 1 |
| `edits[].new_text` | `string` | Required |  |
| `edits[].replace_all` | `boolean` | Optional | default: false |
| `if_match` | `string` | Optional | The 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_id` | `string` | Optional | Your 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_seconds` | `integer` | Optional | Hold the response up to this many seconds until indexing finishes. The write is committed either way. 1..10 |
| `idempotency_key` | `string` | Optional | Send 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

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `space_id` | `string` | Optional | Space id, or ext:<external_id> for the Space that carries your own id. Omit to use your default Space. length 1..256 |
| `path` | `string` | Required | Absolute path, such as /notes/plan.md. length 1..4096 |
| `if_match` | `string` | Optional | The 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

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `query` | `string` | Required | What to look for, in natural language or keywords. length 1..1000 |
| `space_ids` | `string[]` | Optional | 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 |
| `path` | `string` | Optional | Restrict results to this subtree or file. length 1..4096 |
| `include` | `"memory"[]` | Optional | ["memory"] adds memories to the results. items 1..1 |
| `limit` | `integer` | Optional | Maximum number of hits. Defaults to 20, at most 50. 1..50 |
| `filter` | `object` | Optional | Narrow 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.metadata` | `object` | Optional |  |
| `filter.source_types` | `string[]` | Optional | items 1..8 |
| `filter.occurred_from` | `string (date-time)` | Optional |  |
| `filter.occurred_to` | `string (date-time)` | Optional |  |
| `reference_time` | `string (date-time)` | Optional | The moment relative time in the query or task (yesterday, last week) is counted from, RFC 3339. Defaults to now. |
| `timezone` | `string` | Optional | IANA 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

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `task` | `string` | Required | The 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_ids` | `string[]` | Optional | 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 |
| `purpose` | `task \| coding \| research \| audit` | Optional | Sets how the budget is split between sources. Omit to have it inferred from the task. |
| `weights` | `object` | Optional | Per-source preference from 0 to 1. 0 turns a source off. |
| `weights.memory` | `number` | Optional | 0..1 |
| `weights.agent_profile` | `number` | Optional | 0..1 |
| `weights.skills` | `number` | Optional | 0..1 |
| `weights.files` | `number` | Optional | 0..1 |
| `weights.changes` | `number` | Optional | 0..1 |
| `weights.knowledge` | `number` | Optional | 0..1 |
| `tier` | `fast \| standard \| deep` | Optional | fast matches words only and calls no model. standard (the default) adds semantic search and reranking. deep considers twice as many candidates. |
| `budget_tokens` | `integer` | Optional | Token budget for the whole response, 500 to 16000. Defaults to 4000. 500..16000 |
| `have_memory_etag` | `string` | Optional | memory_view_etag from an earlier pack. memory_view is left out while it is unchanged. length 1..128 |
| `filter` | `object` | Optional | Narrow 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.metadata` | `object` | Optional |  |
| `filter.source_types` | `string[]` | Optional | items 1..8 |
| `filter.occurred_from` | `string (date-time)` | Optional |  |
| `filter.occurred_to` | `string (date-time)` | Optional |  |
| `reference_time` | `string (date-time)` | Optional | The moment relative time in the query or task (yesterday, last week) is counted from, RFC 3339. Defaults to now. |
| `timezone` | `string` | Optional | IANA 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

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `pack_id` | `string` | Required | pack_id of the mira.context result. length 1..256 |
| `used_citation_ids` | `string[]` | Required | 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

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `space_id` | `string` | Optional | Space id, or ext:<external_id> for the Space that carries your own id. Omit to use your default Space. length 1..256 |
| `days` | `integer` | Optional | How 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

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `space_id` | `string` | Optional | Only 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 |
| `scope` | `project \| agent \| account` | Optional | Keep the memories of one scope. |
| `status` | `candidate \| confirmed \| rejected \| superseded` | Optional | candidate waits for review and is not used in retrieval; confirmed is used in retrieval; rejected and superseded are history. |
| `kind` | `string` | Optional | Keep one kind, such as preference, decision or progress. length 1..64 |
| `q` | `string` | Optional | A phrase the memory text must contain: a literal match that ignores case. length 1..200 |
| `cursor` | `string` | Optional | next_cursor from the previous page. length 1..1024 |
| `limit` | `integer` | Optional | Maximum 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

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `scope` | `project \| agent \| account` | Required | agent: 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_id` | `string` | Optional | For project and agent memory. Omit to use your default Space. Account memory takes none. length 1..256 |
| `kind` | `string` | Required | For 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 |
| `text` | `string` | Required | The statement, in one or two sentences, at most 2000 characters. min length 1 |
| `pinned` | `boolean` | Optional | true lists it ahead of unpinned memories in memory_view. Not for account memory. |
| `idempotency_key` | `string` | Optional | Send 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

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `memory_id` | `string` | Required | id 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

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `space_id` | `string` | Optional | Space id, or ext:<external_id> for the Space that carries your own id. Omit to use your default Space. length 1..256 |
| `session_id` | `string` | Required | Your id for the conversation. Use the same one for every batch of that conversation, and for the files it changes. length 1..256 |
| `messages` | `object[]` | Required | 1 to 1000 messages, in the order they were said. items 1..1000 |
| `messages[].role` | `string` | Required | user, assistant or any other speaker. length 1..64 |
| `messages[].content` | `string` | Required | What was said, as text. min length 1 |
| `messages[].timestamp` | `string (date-time)` | Optional | When it was said, RFC 3339. |
| `messages[].name` | `any` | Optional | Accepted and ignored. |
| `messages[].tool_calls` | `any` | Optional | Accepted and ignored. |
| `messages[].tool_call_id` | `any` | Optional | Accepted and ignored. |
| `messages[].function_call` | `any` | Optional | Accepted and ignored. |
| `title` | `string` | Optional | Defaults to Conversation <session_id>. length 1..512 |
| `redact_secrets` | `boolean` | Optional | Set 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_instructions` | `string` | Optional | The 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_key` | `string` | Optional | Send 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

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `space_id` | `string` | Optional | Space id, or ext:<external_id> for the Space that carries your own id. Omit to use your default Space. length 1..256 |
| `text` | `string` | Required | The text to store, up to 2,000,000 characters. length 1..2000000 |
| `title` | `string` | Optional | Defaults to the first line. length 1..512 |
| `occurred_at` | `string (date-time)` | Optional | 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. |
| `metadata` | `object` | Optional | Labels 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_secrets` | `boolean` | Optional | true replaces what looks like a credential before anything is stored. A safety net, not a guarantee. |
| `idempotency_key` | `string` | Optional | Send 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

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `space_id` | `string` | Optional | Space id, or ext:<external_id> for the Space that carries your own id. Omit to use your default Space. length 1..256 |
| `url` | `string` | Required | An http or https URL. length 1..8192 |
| `title` | `string` | Optional | A title for the Entry. Defaults to the page's own. length 1..512 |
| `occurred_at` | `string (date-time)` | Optional | When the page's content happened, RFC 3339, if you know it. |
| `metadata` | `object` | Optional | Labels 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_key` | `string` | Optional | Send 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

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `entry_id` | `string` | Required | id of the Entry, such as the entry_id of a search hit, a context item or a citation. length 1..256 |
| `view` | `text \| meta \| table` | Optional | text (the default), table or meta. |
| `version` | `string` | Optional | Read this version, such as the version_id of the hit. Omit for the latest. Not with view meta. length 1..256 |
| `offset` | `integer` | Optional | Where the window starts, in characters: content_window.next_offset from the previous call. view text only. >= 0 |
| `max_chars` | `integer` | Optional | Window 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

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `question` | `string` | Required | The question, in the user's language. length 1..4000 |
| `space_ids` | `string[]` | Optional | 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 |
| `tier` | `fast \| standard \| deep` | Optional | fast matches words only. standard (the default) adds semantic search and reranking. deep considers twice as many candidates. |
| `budget_tokens` | `integer` | Optional | Token budget for the evidence the model reads. Defaults to 4000. 500..16000 |
| `weights` | `object` | Optional | Per-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.memory` | `number` | Optional | 0..1 |
| `weights.agent_profile` | `number` | Optional | 0..1 |
| `weights.skills` | `number` | Optional | 0..1 |
| `weights.files` | `number` | Optional | 0..1 |
| `weights.changes` | `number` | Optional | 0..1 |
| `weights.knowledge` | `number` | Optional | 0..1 |
| `history` | `object[]` | Optional | Earlier turns of this conversation, oldest first, so a follow-up question can be understood. At most 10. max items 10 |
| `history[].role` | `user \| assistant` | Required |  |
| `history[].content` | `string` | Required | length 1..4000 |
| `output_language` | `string` | Optional | BCP 47 tag of the language to answer in, such as en or zh-CN. Defaults to the question's. length 1..35 |
| `include` | `"evidence"[]` | Optional | ["evidence"] also lists every passage the model read (without text), not only the cited ones. items 1..1 |
| `filter` | `object` | Optional | Narrow 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.metadata` | `object` | Optional |  |
| `filter.source_types` | `string[]` | Optional | items 1..8 |
| `filter.occurred_from` | `string (date-time)` | Optional |  |
| `filter.occurred_to` | `string (date-time)` | Optional |  |
| `reference_time` | `string (date-time)` | Optional | The moment relative time in the query or task (yesterday, last week) is counted from, RFC 3339. Defaults to now. |
| `timezone` | `string` | Optional | IANA 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

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `memory_id` | `string` | Required | id of the memory to replace, from mira.memory.list. length 1..256 |
| `text` | `string` | Required | The corrected statement, in one or two sentences. length 1..2000 |
| `idempotency_key` | `string` | Optional | Send 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

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `memory_id` | `string` | Required | id of the candidate, from mira.memory.list. length 1..256 |
| `decision` | `confirm \| reject` | Required | confirm 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

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `space_id` | `string` | Optional | Space id, or ext:<external_id> for the Space that carries your own id. Omit to use your default Space. length 1..256 |
| `limit` | `integer` | Optional | Page size. Defaults to 50. 1..200 |
| `cursor` | `string` | Optional | next_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

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `entry_id` | `string` | Required | id of the trashed Entry, from mira.trash.list. length 1..256 |
| `idempotency_key` | `string` | Optional | Send the same key only to retry the identical call within 24 hours: the first result is returned again. length 1..256 |

## Read memory (Deployment 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

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `memory_id` | `string` | Required | id of the memory. length 1..256 |
| `include_provenance` | `boolean` | Optional | Defaults to true. false skips the sources. |
