Configuration

Mindbaton works with no configuration at all. When you want to change something, put NAME=value lines in mindbaton.env next to server.py (the installer creates one; mindbaton.env.example lists everything) and restart Mindbaton. Real environment variables win over the file. With Docker, use a mindbaton.env next to compose.yaml, or -e NAME=value with docker run.

Settings#

For the Claude Desktop bridge (mcp_stdio.py), set these in the Claude Desktop config, not in mindbaton.env:

The optional AI#

Everything Mindbaton understands — facts, topics, answers, redaction — comes from rules on your own computer. An AI is only used, if you add a key, to word things more nicely: hand-off summaries, topic names and summaries, and short answers on the search page (with the memories they came from).

• Free keys: Google AI Studio (Gemini) or Groq. Paid keys: OpenAI or Claude. Paste any of them on the Setup page (AI keys); each is tested before it's saved. Remove key takes one out again, and pasting a new key over an old one replaces it.
• For the best results, use a paid key. A paid key has no free-tier quota to run out of, and you can pick a stronger model for it. Add one and choose it under Answer with to have it answer first; left on the default it only steps in when the free keys can't answer.
• Unless you choose otherwise it tries Gemini, then Groq, then OpenAI, then Claude, and uses the first that answers.
• Your choice. On the same card an admin can pick which key answers first (Answer with), the model each paid key runs, and the monthly limit for paid keys. Putting a paid key first means every summary and answer you ask for is charged to it, still within the limit. The choices apply to everyone on the install and survive restarts.
• What leaves your computer: the text of the chat or memories that particular summary, name or answer is about — sent to that provider only.
• No key, or MINDBATON_AI=0: Mindbaton uses rule-made topic names and a plain extract as the hand-off pack.

Paid keys: only when needed#

A paid key is there for when the free ones can't answer, not to be spent freely:

• Free first. A paid key is tried only when no free key is saved, or the free providers are busy or over their quota.
• The cheapest model of each provider by default, on short prompts (a long chat is cut to about 30,000 tokens).
• Nothing made ahead of time. A hand-off summary is written on a paid key when you ask for the hand-off, never just because you opened a chat. Topic names, which nobody waits for, use a paid key at most once an hour.
• A monthly limit. Mindbaton adds up what each paid answer cost, from the tokens the provider reports, and stops using paid keys for the month at MINDBATON_AI_MONTHLY_USD (2 US dollars unless you change it). Setup shows the running total. The count is kept in ai_usage.json, so a restart doesn't reset it.
• Answers are kept. The same summary, name or answer is never paid for twice while Mindbaton runs, and topic names are stored for good.
• It is an estimate: prices change, and a model Mindbaton has no price for is counted as an expensive one, so the limit errs early. Set a spending limit on the provider's site too; that one is the real backstop.
• A Gemini key from a Google project with billing turned on is charged by Google, and Mindbaton does not count it. Use a key from a free project, or set a budget in Google Cloud.
• Your keys, your bills. What a provider charges for a key you add is between you and that provider. Mindbaton's limit and total are estimates, not a guarantee, and the project is not responsible for any charges: see the Terms.

Keeping keys safe#

• A key is stored in ai_keys in your data folder, readable only by your user. It is never sent back to a browser, never written to a log, and never leaves the computer except to its own provider.
• Make a key just for Mindbaton, so you can revoke it without touching anything else. If the provider lets you restrict what a key can do or how much it can spend, do it.
• Pasting a key into Setup over plain http:// on a network you don't control lets others on that network read it. Use HTTPS (see Remote access), or put the key in mindbaton.env on the server instead.
• If a key leaks, revoke it on the provider's site first, then use Remove key and paste a new one.

Mindbaton's own model#

Rules read most of what you tell your AIs. For the rest (the way people really type: "5-a-side football every thursday", "zero caffeine since march") Mindbaton has its own small model: Qwen3.5-2B fine-tuned on made-up examples only, 1.3 GB.

• An admin chooses who reads on the Setup page, for everyone on the install:
  • Accurate: the model is the main reader. It reads every message typed in a chat, and the rules check each fact. On sentences it never saw, with wording no rule was written for, this caught 56 of 60 facts.
  • Light: the rules read alone. Nothing is downloaded and nothing runs in the background. On the same sentences the rules caught 33 of 60.
  • Until someone chooses, it works as before: on a computer with 12 GB of memory or more the model turns on by itself and reads only the messages the rules found nothing in.
• Choosing Accurate covers new messages from then on. Re-read everything on the same page has the model read the older ones too.
• The first time, it downloads the model and the llama.cpp engine (about 1.3 GB, once) into brain/ in your data folder.
• It reads one message at a time, at low priority on half the processor, and shuts the engine down after 5 idle minutes. It uses about 1.5 GB of memory while reading.
• On a laptop it waits for the charger. Only read while plugged in (Setup, on by default) is the switch: an admin can turn it off after a warning, and the model then reads on battery too, which drains it faster.
• Everything stays on your computer. The rules check every fact it reads (the words must be in your message, never from a question or a "maybe") before it's saved, and what it read is kept, so it never reads the same message twice.
• Mindbaton on a small server, but a laptop with memory to spare? Run llama-server on the laptop and set MINDBATON_BRAIN_URL on the server; it reads whenever the laptop is on.

What's in the data folder#

The folder is created readable only by you. Back it up — see backup and upgrade.

Command line#

Run these in the Mindbaton folder (Docker: prefix with docker compose exec mindbaton):

Team Baton#

MINDBATON_TEAM=0 is the default; 1 enables experimental shared projects after a host restart. MINDBATON_TEAM_DISCOVERY=1 enables IPv4 LAN discovery when Team Baton is on; use 0 to disable it. Set MINDBATON_PUBLIC_URL to the host’s HTTPS origin so discovered teammates can open it. Discovery uses UDP multicast 239.255.77.66:45837 on the server’s default interface, not the browser’s network. MINDBATON_TEAM_PRIVATE_CIDRS optionally lists peer CIDRs on an encrypted private network; it does not secure plain HTTP on a LAN. Otherwise cross-device project access requires HTTPS through a loopback TLS proxy. See Team Baton before enabling and for the multi-laptop release gate.