# Build on Mirabase

What the SDKs, MCP, skills, skills stored in a Space, webhooks, and provider plugins are each for and how they combine; the core calls of an application; and how to write and check a skill of your own.

## Ways to build

| Piece | Who uses it, for what |
| --- | --- |
| [SDKs](https://mirabase.io/developers/sdks.md) (TypeScript, Python) | Your application code calls `/v2`: write files and conversations, get context packs, answer with citations. |
| [MCP server](https://mirabase.io/developers/agents.md) | Agents read and write files, search, get context, answer, and manage memory through the `mira.*` tools, with the same permissions as `/v2`. Branches, access management, and binary uploads are REST only. |
| [Skills](https://mirabase.io/developers/skills.md) | Agent hosts load them, so the Agent knows when to call which tool, in what order, and what to ask the user first. |
| Skills in a Space | Any Agent that calls `mira.context`: context packs offer the skills stored in the Space, with nothing to install on each Agent. |
| [Webhooks and the change feed](https://mirabase.io/developers/sync.md) | Your services run their own processing when files in a Space change, such as rebuilding an index or notifying a team. |
| Provider plugins | A self-hosted engine uses them to replace the embedding, rerank, answer, distill, classify, OCR, transcription, or web search implementation. The hosted service loads no plugins. |

### Choosing a piece

- Your product calls Mirabase: use an SDK.
- An Agent calls Mirabase: connect MCP, and install skills that tell it how.
- One procedure for every Agent of a team: store the skill in a Space.
- Changes in Mirabase must trigger your own systems: use webhooks or the change feed.
- A different model in your own deployment: write a provider plugin.

## The core loop

The program below shows four common calls: write a file by path, store a conversation, get a context pack for a task to give your own model, or get an answer with citations directly. It runs in a Space of its own (`ext:example-core-loop`), so your other data is untouched. It needs only `MIRABASE_API_KEY`, for a key that can create a Space, read, write, and answer.

TypeScript:

```ts
import { Mirabase } from "@mirabase/sdk/developer";

const mb = new Mirabase(); // reads MIRABASE_API_KEY
// A Space of its own, created on the first run; the client reads and writes that Space only.
const space = await mb.spaceFor("example-core-loop", { name: "Core loop example" });

// 1. A file at a stable path. The same bytes again create no new version.
await space.files.write(
  "/handbook/travel.md",
  "# Travel policy\n\nHotels up to 180 euros a night are approved automatically.\nBook economy for flights under six hours.\n",
);

// 2. A conversation. Memories are distilled from it in the background.
await space.conversations.add(
  [
    { role: "user", content: "I'm going to Berlin for the trade fair on 12 March. I prefer hotels near the fair." },
    { role: "assistant", content: "Noted: Berlin, 12 March, a hotel close to the fair." },
  ],
  { sessionId: "core-loop-demo", redactSecrets: true },
);
await space.spaces.waitUntil({ waitTimeoutMs: 120_000 }); // searchable by meaning

// 3. Context for your own model: memories and passages within a token budget, each with a citation id.
const pack = await space.context("Book a hotel for the Berlin trip within policy.", { budget_tokens: 1500 }); // API field names stay snake_case
// ...send pack.items to your model; afterwards report the citation ids it actually used:
// await space.context.feedback(pack.pack_id, usedCitationIds);

// 4. Or a cited answer from Mirabase. It abstains when the evidence is not there.
const answer = await space.answer("How much can a hotel cost per night without approval?");
console.log(answer.status, answer.answer, answer.citations.map((citation) => citation.path ?? citation.url ?? citation.entry_id));
```

Python:

```python
from mirabase import Mirabase

mb = Mirabase()  # reads MIRABASE_API_KEY
# A Space of its own, created on the first run; the client reads and writes that Space only.
space = mb.space_for("example-core-loop", name="Core loop example")

# 1. A file at a stable path. The same bytes again create no new version.
space.files.write(
    "/handbook/travel.md",
    "# Travel policy\n\nHotels up to 180 euros a night are approved automatically.\n"
    "Book economy for flights under six hours.\n",
)

# 2. A conversation. Memories are distilled from it in the background.
space.conversations.add(
    [
        {"role": "user", "content": "I'm going to Berlin for the trade fair on 12 March. I prefer hotels near the fair."},
        {"role": "assistant", "content": "Noted: Berlin, 12 March, a hotel close to the fair."},
    ],
    session_id="core-loop-demo",
    redact_secrets=True,
)
space.spaces.wait_until(timeout=120)  # searchable by meaning

# 3. Context for your own model: memories and passages within a token budget, each with a citation id.
pack = space.context("Book a hotel for the Berlin trip within policy.", budget_tokens=1500)
# ...send pack["items"] to your model; afterwards report the citation ids it actually used:
# space.context.feedback(pack["pack_id"], used_citation_ids)

# 4. Or a cited answer from Mirabase. It abstains when the evidence is not there.
answer = space.answer("How much can a hotel cost per night without approval?")
print(answer["status"], answer["answer"], [c.get("path") or c.get("url") or c["entry_id"] for c in answer["citations"]])
```

- `spaceFor` (`space_for` in Python) creates the Space on the first run and finds the same one afterwards; the client it returns reads and writes that Space only. With one Space per end user, and your server picking the client for the signed-in user, each user's data stays apart. Pinning a client is a default, not a permission boundary: the key itself can still read every Space it can see. For a hard boundary, issue a key limited to that user's Space; see [Permissions](https://mirabase.io/developers/permissions.md).
- Text up to 64 KiB can be found by its words as soon as it is written, and by meaning once processing finishes; to wait for that, call `waitUntil` (`wait_until` in Python).
- `context.feedback` reports which items your model used. It sends citation ids only, never content.
- The full runnable version is `examples/core-loop` in the open-source repository; source available when the open-source repository is published.

## Write a skill

The skill template is a small working skill, `changelog`: it drafts a changelog entry from what changed in a Space and the decisions stored there, and writes it to `/changelog/<version>.md` once the user approves. Copy it, then change it in this order:

1. Name the folder and `name` the same: lowercase words joined by hyphens, at most 64 characters.
2. Write the description first: an Agent decides whether to load a skill from its description alone, and the description stays in context all the time. Say what the skill does, give two or three real user requests, and name the neighbouring skills under “Not for”. Keep it under 650 characters.
3. Write the steps: name the exact tool or endpoint in each, and say what to do on the likely errors. For every action that cannot be undone or that reaches outside, say to ask the user first.
4. Delete the template's comments: the whole file is read every time the skill loads.
5. Before you tune the description, write the trigger file: requests that should load your skill, and close ones that should load another.

The check that comes with the template confirms that every `mira.*` tool and `/v2` endpoint your skill names exists, and scores your requests and the official ones with a lexical router that sees only names and descriptions. If your description takes requests meant for another skill, change the description, not the request. Source for the template and the check available when the open-source repository is published.

## Store a skill in a Space

A file written to `/.mirabase/skills/<name>/SKILL.md` becomes a skills source for context packs: when an Agent calls `mira.context`, an item whose `source` is `skills` is a one-line summary of the skill's description, and the Agent reads the full file with `mira.files.read` before following it. A team's procedures can then reach every Agent through the Space, with nothing to install on each one. The official skills have the Agent ask the user before following a skill from a Space for the first time, and again after it changes, and never run scripts stored in a Space.

curl:

```bash
curl -X PUT "https://api.mirabase.dev/v2/spaces/ext:team-handbook/files?path=/.mirabase/skills/changelog/SKILL.md" \
  -H "Authorization: Bearer $MIRABASE_API_KEY" \
  -H "Content-Type: text/markdown" \
  --data-binary @changelog/SKILL.md
```

TypeScript:

```ts
import { readFile } from "node:fs/promises";
import { Mirabase } from "@mirabase/sdk/developer";

const team = new Mirabase().space("ext:team-handbook"); // the Space whose Agents should see the skill
await team.files.write("/.mirabase/skills/changelog/SKILL.md", await readFile("changelog/SKILL.md", "utf8"));
```

Python:

```python
from pathlib import Path

from mirabase import Mirabase

team = Mirabase().space("ext:team-handbook")  # the Space whose Agents should see the skill
team.files.write("/.mirabase/skills/changelog/SKILL.md", Path("changelog/SKILL.md").read_text())
```

- Only that level counts: the `SKILL.md` in each folder under `/.mirabase/skills/`. Other files in the same folder are the skill's own reference material, for Agents to read, never to run.
- The skills source has its own share of a pack's budget. At a small budget the summary may not fit, and `route` reports `budget_too_small` for that source, so keep descriptions short.

> **Warning:** A skill stored in a Space is content like any other: whoever can write the Space can change what Agents are told. Give write access to that folder only to members you trust (limit the others with write roots; see [Permissions](https://mirabase.io/developers/permissions.md)), and keep rules that must never change in the Agent's own skills folder.

## React to changes

To run your own processing when files change (rebuild derived files, mirror to another system, notify a team), let Mirabase push changes with a [webhook](https://mirabase.io/developers/sync.md#webhooks), or long-poll the [change feed](https://mirabase.io/developers/sync.md#loop) from a cursor. Both carry the same events; a webhook needs a public HTTPS address, the change feed does not.

## Provider plugins (self-hosted)

A self-hosted Mirabase engine calls models and tools through ports: embedding, rerank, answer, distill, classify, OCR, transcription, and web search. A plugin is an ES module that exports `{ name, register(api) }` and registers an implementation for a port in `register`; a deployment loads it with the `MIRABASE_PROVIDER_PLUGINS` environment variable and selects it with that port's variable.

- A plugin runs inside the engine with the engine's permissions. Load only code you wrote or reviewed. The hosted service loads no plugins.
- A conformance kit checks each port's contract (a reranker returns the candidates' own `index`, cancellation stops at once, and so on) and does not depend on a test framework.
- The plugin interface, each port's contract, and an example plugin are in `docs/providers.md` in the open-source repository; source available when the open-source repository is published.

## Next steps

- [Skills](https://mirabase.io/developers/skills.md): the official skills and the two scenario skills.
- [SDKs](https://mirabase.io/developers/sdks.md): install an SDK, and see its error types and retries.
- [Retrieval and context](https://mirabase.io/developers/retrieval.md): a context pack's budget, sources, and feedback.
