Running AI: Three Ways

Everything AI does in Mikipage — finding which notes belong to a page, writing the page, suggesting new pages, answering questions — needs a language model. There are three ways to get one, and the difference between them is simply who pays for the model call.

	Who runs the model	What it costs you
On the website	Mikipage	AI credits
Via MCP	Your AI assistant	Nothing — your existing subscription
Via the API	Your choice	Credits, or nothing if you run it yourself

If you already pay for Claude or a similar assistant, you never need to spend credits: ask it over MCP when you want something done now ([1]), and run the refresh script on a schedule to keep everything current (see Keeping pages current with your own AI below).

1. On the website

The simplest path. You click a button, Mikipage runs the AI on its own infrastructure, and your AI credits pay for it.

What you can trigger

Operation	Where	Credits
Refresh All — update every page in the space	Organize	Yes (needs 50+)
Refresh — update one page	the page itself	Yes
Suggest pages — AI proposes pages from your recent notes	Organize	Yes
Add to related Pages (Automatic) — match a note against the space's pages	a note	Yes
AI Polish — AI-assisted edit of a note	markdown editor toolbar	Yes
Chat — ask questions about your notes	the chat button, any page	Yes
Accepting a suggestion, attaching a page by hand, pinning a note	—	No

Two things on that list deserve a note of their own.

AI Polish is the only AI operation that touches a note, and it's deliberately timid: it appends its version to the bottom of your note rather than replacing what you wrote. You can pass instructions and choose a model. Nothing else in Mikipage ever modifies a note.

Chat is grounded in your own notes and your groups' notes — it reads your corpus with tools rather than searching the web. Opened from a note or a page, it knows about that page and can answer questions on it.

How AI runs behave

All of it is fire-and-forget. You trigger a run, get a toast saying it started, and carry on working; a notification arrives when it's done and the affected page updates itself. You never wait on a spinner.

Changes to your notes don't apply themselves — they wait for the next refresh. Edit a note and the pages built from it are marked stale; refresh, and the new version is folded in. Removing or deleting a note works the same way, except the cleanup is best-effort: a routine refresh strips what was directly cited to that note, and a Full refresh is the reliable way to clear the rest. See [2].

AI credits

New accounts start with 500 free credits.
Below 10 credits, AI buttons switch off with "Low credit, cannot run AI". Refresh All needs 50, since it's a batch.
Your balance shows next to every AI button, and in full — with a transaction-by-transaction ledger — under Account → Usage.
Credits are consumed in proportion to the work actually done. Content that hasn't meaningfully changed since it was last processed isn't reprocessed, so refreshing a page that's barely moved costs very little.

See [3] for where pricing is headed.

Who pays

Whoever presses the button pays. AI credits come out of the balance of the person who started the run — not the owner of whatever the run touched.

That matters most in a group:

Refresh a page a teammate created, and you pay for it.
Run Refresh All on a group space, and you pay for the whole sweep — including the work it does on other members' pages and notes.
Nothing you own is ever billed for a run somebody else started. Sharing a page into a group does not put your balance behind it.

Runs you perform yourself — through MCP or the API with your own model — cost no credits at all, whoever owns the page. See [3].

2. Via MCP — use your own AI subscription

This is the recommended path for on-demand work if you already pay for an AI assistant.

MCP (Model Context Protocol) connects Mikipage to an assistant like Claude as a tool it can use. When you ask your assistant to refresh your pages, your assistant does the reading and the writing, using the subscription you already have, and hands the results back to Mikipage.

No Mikipage credits are consumed — and not as a billing courtesy. No MCP tool can trigger a server-side AI run at all; there is nothing for Mikipage to charge for. The thinking happens entirely on your assistant's side.

In practice this works well for:

"Refresh all my pages" — the assistant asks Mikipage what's out of date, works through it, and writes each page back.
"Update this page" — read the page and its notes, synthesize a fresh version.
Capturing from a conversation — "save that to Mikipage" mid-chat.

For refreshing everything on a regular schedule, the refresh script below is the better tool: an assistant working through MCP gets the same result but spends many times more of your subscription's tokens doing it.

Setup takes about a minute: [1].

3. Via the API — either way, your choice

The REST API is the complete feature set, and it exposes the choice directly. An AI run is created with POST /{notes,pages,spaces}/{id}/runs, and one field decides who does the work:

execution: "server" queues the job on Mikipage's infrastructure. Billed to your credits.
execution: "client" returns an llm_input payload instead of running anything. You send that to whichever model you like — Claude, OpenAI, something local — and post the result back. No credits are charged, because Mikipage never called a model.
execution: "external" is for when you did the whole thing yourself — your own prompt, your own model, the result written back through the ordinary PATCH routes. It records the run so the server knows the page has been generated (otherwise its next server-side refresh treats it as brand new and does a full, credited regeneration). MCP clients send this automatically.

That second mode is how MCP-style clients work, and it's available to your own scripts too. The reference runner is miki_client/scripts/ai_refresh.py in the open-source Python SDK: a Refresh All for your personal space or any of your groups that runs on your machine against your own model — Claude Agent SDK, Codex SDK, or an Anthropic API key out of the box — and charges nothing. Its siblings work the same way: ai_suggest.py runs Suggest Pages (with the theme note) on a space, and ai_edit_note.py edits one note.

Run types cover the whole surface: page refresh, analyze, generate, note-to-page matching, page-to-note matching, note editing, page suggestion, and space-wide refresh-all.

Full details, endpoints, and the Python SDK: [4].

Keeping pages current with your own AI

If you want your pages kept up to date automatically, on your own AI subscription and without spending credits, we recommend running ai_refresh.py on a schedule. It's the reference runner from section 3. Each run sweeps your personal space and every group you own, doing the same work as Refresh All. Only what has changed since the last run is processed, so running it often stays cheap.

ai_refresh.py ships with the miki_client Python SDK (see [4] for availability). Two one-time steps, from the miki_client folder:

uv run scripts/auth.py                 # log in once in the browser; the session is cached
uv run scripts/ai_refresh.py --dry-run all   # preview what a sweep would do

It uses your local Claude Code login by default. Add --provider codex to use your local Codex login (Luna for light runs, Terra for heavy runs, both at low reasoning effort), or --provider anthropic to use an ANTHROPIC_API_KEY; install the Anthropic extra first with uv sync --extra anthropic. Options go before the command: ai_refresh.py --provider codex all.

There are two good ways to put it on a schedule.

Option 1: cron

Any scheduler that runs a command works. For example, a crontab entry that sweeps every six hours:

0 */6 * * * cd /path/to/miki_client && uv run scripts/auth.py --check && uv run scripts/ai_refresh.py --self-test && uv run scripts/ai_refresh.py all >> ~/mikipage-refresh.log 2>&1

The two checks up front make a broken run fail loudly instead of quietly doing nothing:

auth.py --check confirms your Mikipage login still works, and never opens a browser.
ai_refresh.py --self-test confirms your model can actually answer.

Things to get right:

PATH. Scheduled jobs start with a bare environment, so make sure uv and the default provider's Claude runtime are on the job's PATH.
Logging back in. The cached login lasts about a month. When auth.py --check starts failing, run uv run scripts/auth.py again by hand.
macOS. A scheduled job may not read the same Claude Code or Codex credentials as your terminal. If --self-test fails only when scheduled, that's why; --provider anthropic with an API key avoids it.

Option 2: an AI assistant's scheduled tasks

If you use an assistant that can run commands on a schedule, such as Claude Cowork, create a scheduled routine that runs the same command. For example: "Every six hours, run uv run scripts/ai_refresh.py all in my miki_client folder, and tell me if it fails."

The assistant only starts the script and reads its output. The model calls inside the sweep are made by the script itself, so it costs the same as running it from cron. What you gain is a harness that notices failures. If the Mikipage login has expired, it can tell you instead of leaving a log nobody reads.

What about MCP?

An assistant connected over MCP can do the same sweep ("refresh all my pages") on a schedule, and the result is the same. Today, though, it spends many times more of your subscription's tokens than ai_refresh.py does for the same work, which adds up quickly when it runs several times a day. We're working on bringing that cost down. If you need to run the sweep over MCP anyway, email support@mikipage.com and we'll send you a how-to.

FAQ

How many notes can be processed in a single page?

A language model can only read so much at once, so a refresh cannot feed it an unlimited number of notes. When a page has more than fits, the notes are handled in three bands:

Read in full — as much note text as fits, which is most pages entirely.
Abridged — notes past that point are included as their short AI summary instead of in full, so the page still knows about them.
Left out — only what does not fit even as a summary. A line at the top of the page says how many notes were abridged and how many were left out.

The exact ceilings are in [5].

We recommend keeping a page under about 100 notes. That is advice, not the enforced limit — the real one is comfortably higher. But a page pulling in several hundred notes is usually trying to cover too much: it reads worse to a person, and every note costs credits to process. Somewhere well under 100, a page stays sharp for AI and for you.

Three things worth knowing:

Order decides what gets condensed. Pinned notes are read first, then the most recently updated. So when a page is over the limit, it is the older, unpinned notes that are abridged or dropped.
Pin what must not be condensed. Pinning gives a note priority: it is read in full while unpinned notes are being condensed or dropped. What pinning does not do is create extra room — the context window is the same either way. A page whose pinned notes alone exceed the limit will have pinned notes condensed too. Priority decides who goes first, not how many fit.
Only longer notes have a summary to fall back on. A note has one once Mikipage has analyzed it, which happens for notes over roughly 200 words. A shorter note needs no summary — it is already short enough to include whole.

Does a bigger page cost more credits?

Yes, roughly in proportion to how much note text a refresh actually reads. A very large page can cost several times what a small one does, and Refresh All multiplies that across every page in the space — which is why it requires a larger balance to start.

Two things soften it: content that has not meaningfully changed since it was last processed is not reprocessed, so refreshing a barely-moved page costs very little; and running via MCP or execution: "client" costs no Mikipage credits at all, whatever the page's size.

A note on the alpha

AI updates are user-triggered. There is no server-side sweeper refreshing your pages on a schedule — if a page is out of date, it stays that way until you (or your AI assistant) ask for a refresh. A scheduled sweeper is planned; credits will apply to it when it arrives.

[1] — connect an AI assistant
[2] — what a refresh actually does
[4] — the complete surface
[3] — credits and pricing