User guide

This is the same manual the app bundles under Settings → About → User guide, rendered from the very same file — so it cannot drift from the one on your machine.

Why MindMap Chat instead of a plain chatbot

• Visual context is preserved. Relationships between ideas stay visible while you learn,
instead of being buried in a scrolling chat transcript.
• AI is scoped, not global. Each conversation can be tied to a single node, a branch, or the
whole map — you control the context.
• Edits are explicit. AI suggestions are shown for review before anything changes; you apply,
keep, or undo with one tap.
• Your data stays yours. No account required. The database and settings live in a folder you
own — and because they are encrypted at rest (AES-256, your passphrase), you can safely back them up to or sync them through public cloud storage.
• Works offline. Semantic search uses a bundled embedding model. Once models are pulled, AI
chat also works without internet.

Features at a glance

Who it is for

• Students building revision maps for exams, courses and reading lists.
• Self-learners breaking down technical or academic topics into manageable branches.
• Researchers collecting concepts, relationships and source links in one visual space.
• Teachers and mentors preparing structured topic overviews that can be expanded with AI.

System requirements

Older systems are not supported: on macOS below 14 the app refuses to open, and on Linux the packages fail to install against an older glibc. No GPU and no AI model are required — the editor, import and offline semantic search work on any machine that meets the above.

Getting started

1. Create a map. Tap New map in the library's top bar, type a name, and it becomes the root
node of a fresh map. Or tap Template to start from a skeleton instead of a blank canvas — a study/revision map, book or paper notes, a project/decision map, or a short tour of the app whose nodes you can ask questions about.
2. Or import what you already have. Freeplane .mm and XMind .xmind files are supported.
Every import creates a fresh, independent copy, so re-importing is always safe.
3. Set up AI — see Configuring AI below.
4. Select a node to reveal the floating action bar, and start asking.

An example learning workflow

1. Import a Freeplane or XMind map from a course, article, or your previous notes.
2. Clean up the layout with Auto-align so the structure is easier to scan.
3. Open one branch and ask AI to explain, summarize or compare the concept.
4. Save the answer as a node note so the explanation stays attached to the topic.
5. Expand the map with AI-suggested child nodes, then review and apply only the changes you want.
6. Come back later and use semantic search to find ideas by meaning, not just exact wording.

Working with maps

Organize and reshape ideas visually

• Pan and zoom across a hierarchical tree layout; expand and collapse branches while reviewing.
• Rename, delete, restyle and re-parent nodes. Drag a node onto another to make it a child; the
whole subtree follows.
• Restyle nodes — shape (oval, fork, bubble, round-rect, diamond, parallelogram, hexagon, cloud),
fill colour, font, border — and pick up to 5 icons per node.
• Auto-align rebalances an imported layout, and can be undone like any other edit.
• Right-click (or long-press on touch) any node for the full menu without selecting it first.
• Undo / redo covers every edit, including drags, styling, notes and AI changes.

Node properties

Tap Properties in the node action bar for a read-only sheet showing the node's link, tags, attributes, detail text and note preview. Notes and details render LaTeX formulas and inline text styles. The AI Research button opens the research panel directly from here.

Rich text

Select text in a note or detail and apply bold, italic, underline, strikethrough or highlight from the compact toolbar. You can also style any chat message — yours or the AI's — with the Style button under the bubble. Styling composes with the existing Markdown and LaTeX rendering.

Import

• Freeplane .mm, and XMind .xmind (both the legacy XML and the XMind 2020+ JSON formats).
• Multi-sheet XMind workbooks are preserved as multiple sheets inside one imported map.
• UTF-8 text survives across scripts — Cyrillic, CJK, RTL text and emoji.
• Root branches are auto-balanced left/right when the source file puts everything on one side.

Export / Share is temporarily unavailable. The HTML and Markdown output was not good enough

to ship; the feature returns in a later update.

The AI features

Node-focused chat

Select a node and press Chat about node with AI (the chat-bubble icon) to open a full-screen, multi-turn conversation scoped to that node. The AI is given the node's text, its details and note, its parent, its children, its ancestry path and the map outline as background. History is kept per node, so you can reopen the conversation any time.

Map-level chat

Chat about map with AI injects the whole tree as context — pure conversation, with no automatic edits. Map chat history is persisted too and survives restarts.

Extend with AI (node and map)

The Extend dialogs fire their prompt automatically on open. The response streams in for you to read, and if the model proposes structural changes you'll see N changes ready to apply:

• Apply commits them as a single undoable batch.
• Cancel discards them.
• Applied edits are highlighted in amber, with a Keep / Undo banner.

Every applied AI edit is recorded as an audit trail. Nodes that received AI contributions show a ✨ badge; tapping it opens the properties sheet at the AI Contributions section, with the model name, timestamp and a preview of each change.

AI Research notes

From a node's properties sheet, tap AI Research. A question is pre-filled ("Tell me about …") — edit it and press Ask. The response streams in and renders LaTeX. If the node has no note yet the answer is saved as its note automatically; if it already has one, you're asked to confirm before replacing it. Either way it's undoable.

Semantic search (offline)

Semantic search runs directly on the canvas, using embeddings stored on your device.

• A floating search bar appears at the top of the canvas.
• Results are matched by meaning, not just exact text. Matched nodes glow amber; the focused result
is emphasised more strongly.
• Esc clears the focused selection while keeping the query and its highlights.
• The first search on a map may run an indexing pass — progress is shown, and Cancel stops it
while keeping the work already done. Later searches are faster.

Configure the model under Settings → AI → Embedding model: local-hash-384 (lightweight) or all-minilm-l6-v2 (higher quality). Both ship inside the app, so search works offline out of the box. Changing the model clears stored embeddings and re-indexes on the next search; **Recompute embeddings now** forces a full re-index immediately.

Configuring AI

1. Open Settings (the gear icon in the toolbar).
2. On the AI tab, pick a Provider. Ollama and LM Studio run on your own hardware;
Claude (Anthropic) and OpenAI run on theirs. For a local runtime, keep the default endpoint (http://localhost:11434/v1 for Ollama, http://localhost:1234/v1 for LM Studio) or point it at a host elsewhere on your network — switching provider re-points the address for you. A cloud provider has a fixed address and asks for an API key instead.
3. Pick a Model from the curated list. On a local runtime each shows an installed/missing badge,
and choosing one that isn't installed triggers an automatic download when you press Save.
4. Choose the Embedding model used by offline semantic search.
5. Toggle Include map context to inject the current map outline into the AI's system prompt.

Guided setup: for a local endpoint, pressing Save installs the runtime if it's missing and starts its server — with a progress checklist, and Cancel / Retry if anything fails. Steps that are already done are skipped. If the model you picked isn't there yet, the Downloads panel opens and fetches it. Two limits are worth knowing: on Linux, LM Studio ships only as an AppImage and has to be installed by hand (Ollama installs automatically there); and a remote LM Studio cannot be fetched into, because LM Studio downloads models through its own command-line tool on the machine running it — the app says so rather than offering a download that could not work. On Android and iOS neither runtime runs on the device, so both work against a remote endpoint only — there the AI tab asks for the Server address of the computer running the runtime (just the IP or host name, e.g. 192.168.1.50) and composes the endpoint for you, showing the address it will connect to. The port comes from the runtime you picked and follows it when you switch; open Port · Change underneath if your server listens somewhere else.

Using a cloud provider

Claude (Anthropic) and OpenAI are optional, and nothing about the local runtimes changes if you never touch them. What changes if you do is worth being plain about: the model runs on the provider's servers, so what it needs to answer — the outline of the map you are working on, the text and notes of the node you act on, and the messages in that chat — is sent to them over the internet. Your maps stay encrypted on this device, and your API key is stored encrypted here too, but what you send for a reply is handled under their terms and they bill you for it.

The app asks before this can happen. Choosing a cloud provider opens a dialog naming it and listing what is sent; declining leaves your selection where it was, and until you accept, the AI features stay switched off for that provider. A banner in Settings repeats it, and a Cloud chip sits beside the title in the chat window.

Setting up a Claude API key, step by step

API access is billed separately from any Claude subscription. A Claude Pro or Max plan does not include API credit, and a token from claude setup-token is a Claude Code credential that this app cannot use. You need an API key from the Console.

1. Go to platform.claude.com and sign in (the same account as Claude.ai works).
2. Add credit under Settings → Billing. There is no free tier for the API, and a key with no
credit behind it authenticates fine and then fails on the first message.
3. Open Settings → API keys and press Create key.
4. Name it something you will recognise later — "MindMap Chat" — and choose an expiration. Never
is fine for a key that stays on your own machine; a dated one means remembering to replace it.
5. Scope it to a single workspace if you are offered the choice. This is the step that saves you
trouble: a key tied to one workspace needs nothing else. A key that spans several has to name the workspace on every request, and the app will ask you for the ID below.
6. Copy the key — it starts sk-ant-api… and is shown once — and paste it into API key in the
app.
7. Press Test connection. All four checks should go green.

If the test says a workspace ID is required, your key is not tied to one workspace. Open Settings → Workspaces in the Console, copy the value from the ID column (it starts wrkspc_), and paste it into Workspace ID in the app. Creating a new key scoped to one workspace works just as well and leaves the field empty.

Setting up an OpenAI API key, step by step

The same trap in a different shape: API access is billed separately from ChatGPT. A Plus, Pro or Team subscription does not include API credit, and a ChatGPT login is not an API key.

1. Go to platform.openai.com and sign in (the same account as ChatGPT works).
2. Add credit under Settings → Billing. A key with no credit behind it authenticates fine and
then fails on the first message.
3. Open API keys and press Create new secret key.
4. Name it something you will recognise later — "MindMap Chat" — and pick the project you added
credit to. A project-scoped key needs nothing else: the app sends no organisation or project header, so the key's own project is the one billed. That is why there is no workspace field here.
5. Copy the key — it starts sk- and is shown once — and paste it into API key in the app.
6. Press Test connection. All four checks should go green.

If the connection test reports insufficient_quota, the project has no credit left, whatever your ChatGPT plan says.

Your key is stored in the same encrypted database as your maps, per provider — configuring one does not overwrite another's, and nothing is written to the settings file in clear text.

Under Cost and size you will find:

• what this session has cost, in tokens the provider itself reported. Tokens rather than money,
because prices change and a figure the app quoted from memory could be wrong in a direction that matters. Your provider's dashboard is the authority on the bill.
• Ask before sending more than — a ceiling on one request, 32k tokens by default. A large map is
both a bill and the thing leaving your device; over this size the request is refused and tells you the number rather than being sent quietly. Set it to No limit if you would rather it did not.
• Scrub identifiers before sending, off by default. It replaces email addresses, IP and MAC
addresses, GUIDs, file paths and token-shaped strings with placeholders. It is defence in depth, not a guarantee — and because the map is what gets sent, the model then answers about the placeholder, so a map full of real addresses gets worse replies with this on.

If a map must never leave this device, use Ollama or LM Studio. That is the only guarantee.

Who is responsible for what

MindMap Chat is not affiliated with Anthropic or OpenAI, and does not resell, host or intermediate their services. When you enable one, you are using your own account with that provider, and that is an agreement between you and them: their terms of service, privacy policy, acceptable-use policy, pricing and availability govern it. Any account, billing, quota or support matter is yours to take up with them directly — this app has no visibility into your account and cannot act on your behalf.

Warranty and liability are the licence's, not a second set of terms. This software already ships under the Elastic License 2.0, whose No Liability section reads:

As far as the law allows, the software comes as is, without any warranty or condition, and the

licensor will not be liable to you for any damages arising out of these terms or the use or

nature of the software, under any kind of legal claim.

That covers anything that goes wrong when a provider is involved — outages, rate limits, models changed or withdrawn, refused or wrong answers, how the provider handles what is sent, a suspended account, or charges made to it — for the same reason it covers everything else. The full text is in Settings → About.

Deleting a chat here deletes it here. Clear conversation removes the messages from this device's encrypted database and makes no network call — there is nothing to delete at the provider in the sense you might expect, because the API is stateless and keeps no conversation of its own. What it does keep is the requests already sent, for as long as its retention policy says. Nothing in this app can reach that; the provider's privacy policy governs it.

What the app does guarantee is narrow and worth stating plainly: it will not send anything to a provider you have not selected and agreed to.

Read the provider's terms and privacy policy before you turn this on:

• Anthropic — Consumer Terms,
Commercial Terms, Privacy Policy, Usage Policy
• OpenAI — Terms of use,
Privacy policy, Usage policies

Which model should I pick?

The app supports a fixed list of models — the ones covered by its automated tests against a real LLM. Nearly all of the local ones are offered on both runtimes, so switching runtime does not change what the AI can do; the one exception is Bonsai (27B), which LM Studio publishes and Ollama does not. Download is disk space; Roughly needs is the memory the model wants while it is answering, which is video memory on a GPU or system memory without one — and for a cloud model, both are its provider's problem rather than yours.

If you are unsure, start with Gemma 3n (e4B) — it is the lightest — or Qwen 2.5 (7B) for a better balance of quality and speed. The 32B model is noticeably slower and only worth it if you have the memory for it: on a machine that cannot hold it, it still answers, but by falling back to system memory, and a single reply can take minutes instead of seconds.

Qwen 3.6 (35B-A3B) is the best quality on the list, and it works differently from the others: it reasons before it answers, writing out its thinking first. That thinking is not the answer, so the app keeps it out of your notes — but in chat you can open the Reasoning line above a reply to read how it got there. Expect the first words of an answer to take longer to appear than with the other models; the app says "Thinking…" while that is happening. It is a mixture-of-experts model, so despite being the largest download it is faster than the 32B once it starts writing. For chat the app turns the reasoning off, because a conversation should not pause for a minute before its first word.

Qwen 3.8 (27B) reasons in the same way, and the same Reasoning line shows its thinking. It is a dense model rather than a mixture-of-experts, so it wants the memory of the 32B class and writes at a similar pace; chat turns the reasoning off, as it does for Qwen 3.6.

Muse Glimmer (28B) also reasons, and unlike the Qwen models it offers no way to switch that off — so every reply, chat included, pauses to think before its first word. It writes long, detailed answers, which is what makes it worth the wait when it is expanding a map rather than holding a conversation.

Bonsai (27B) is the one model offered on LM Studio only. It is quantized down to a single bit per parameter, so a 27B model fits in about 8 GB — by far the most capability per gigabyte on the list — and it reasons before answering too. Being compressed that hard, expect it to be less reliable than the larger downloads on long, detailed answers.

A model that does not fit is a slowness problem, not an error — nothing breaks, it just gets slow.

Downloads

The download icon beside the Model heading opens a panel listing every supported model for the current runtime, with what's ongoing, what failed, what's installed, and what's still available. Several models can download at once, and the panel can be closed and reopened without interrupting anything — a download keeps running while you use the app.

Cancel behaves differently on the two runtimes, and the button says which:

• Ollama — Cancel stops the download. Ollama keeps the layers it already fetched, so starting
again resumes rather than beginning from scratch.
• LM Studio — Detach only stops the app watching. The transfer belongs to the LM Studio
application and carries on there; Reattach picks it up again mid-file. To actually stop it, use LM Studio's own Downloads panel. For the same reason a transfer you started in LM Studio shows up here on its own, marked as one the app didn't start.

If a download stops making progress it's shown as Stalled, not failed — with LM Studio the transfer may still be alive, and the app says so instead of guessing. LM Studio also reports progress as a plain percentage for some models, so a size and a time remaining aren't always available.

Settings are saved inside your data directory, so they travel with the database when you move or back up your data folder.

Set up LM Studio manually

On Windows, winget install -e --id ElementLabs.LMStudio; on macOS, brew install --cask lm-studio (Apple Silicon only); on Linux, download the AppImage from lmstudio.ai, chmod +x it and run it — it needs FUSE, e.g. sudo apt install libfuse2.

Then:

1. Open the LM Studio app once. That first launch is what installs its lms command-line tool,
which the app uses to start the server and download models. If MindMap Chat says the tool isn't set up yet, this is the step you are missing — do it and press Retry.
2. Download a model, either in LM Studio's own browser or with lms get qwen/qwen2.5-7b -y.
3. Start the server with lms server start -p 1234.
4. In the app, open Settings → AI, choose LM Studio, leave the Base URL as
http://localhost:1234/v1, pick the matching Model, and press Save.

The first reply from a model can take a while — LM Studio loads it into memory on demand. Later replies are fast.

Share one LM Studio server across your network

Same idea as sharing Ollama, with two differences. Start the server bound to every interface with lms server start --bind 0.0.0.0 -p 1234 (by default it listens only on localhost), and allow inbound TCP port 1234 through the host's firewall — see Opening the port on your firewall below. On each client, open Settings → AI, choose LM Studio, and set the Base URL to http://<host-ip>:1234/v1. On a phone or tablet, enter just the address (<host-ip>) — the app adds the port and the /v1.

Because model downloads go through the lms tool on the host, download the models you want to share on that machine — a client cannot fetch into a remote LM Studio.

Set up Ollama manually

If you'd rather not use the zero-touch flow — or you're on a platform where it isn't available — you can install Ollama yourself:

1. Download and install Ollama for your operating system from its website. On Linux you can also run
the official install script; on Windows and macOS use the installer.
2. Ollama runs as a background service and listens on http://localhost:11434 by default.
3. Pull one of the supported models from a terminal, using the model key from the table above — for
example ollama pull qwen2.5:7b or ollama pull gemma3n:e4b. A model outside that list can be pulled, but the app will not offer it.
4. In the app, open Settings → AI, leave the Base URL as http://localhost:11434/v1, pick the
matching Model, and press Save. The model's badge should read installed.

Share one Ollama server across your network

You don't need Ollama on every device. Run it once on a single capable PC (plenty of RAM and, ideally, a GPU) and let every other computer, laptop, tablet, or phone on the same network use it.

On the machine that will host Ollama:

1. Set OLLAMA_HOST=0.0.0.0 in Ollama's environment so it accepts connections from other devices,
then restart the Ollama service. (By default Ollama only listens on localhost, which other machines can't reach.)
2. Pull the models you want to share, as above.
3. Allow inbound TCP port 11434 through that machine's firewall so other devices can connect —
see Opening the port on your firewall below.
4. Note the host's LAN address, e.g. 192.168.1.50.

On every client device:

1. Open Settings → AI.
2. Set the Base URL to http://<host-ip>:11434/v1 — for example http://192.168.1.50:11434/v1.
On a phone or tablet the field asks for the Server address instead: type 192.168.1.50 and the app composes the rest. localhost there means the phone itself and is refused.
3. Pick a model that the host has pulled, and press Save.

The desktop-only auto-install runs per machine; clients don't install anything — they just point at the shared host. The app shows a small notice under the endpoint when it is on your network rather than on this device.

Opening the port on your firewall

Two separate things have to be true before another machine can reach your server, and each one fails silently on its own: the server has to listen on every interface (the steps above), and the firewall has to allow the port inbound (the commands below). If you only do one, the connection simply times out with nothing to explain why.

Use 11434 for Ollama or 1234 for LM Studio. Each command below allows the port for your **local network only**.

Before you run these. Neither Ollama nor LM Studio asks for a password. Anyone who can reach

that port can use your machine's GPU, see which models you have, and load or unload them. That is

usually fine on a home network and a bad idea on a shared, office, hotel, or campus one. Two rules

keep it sensible: allow the port to your local network only, never to "any" address; and **never

forward this port on your router** — that is the mistake people reach for when a client still

can't connect, and it puts an unauthenticated server on the public internet for anyone to find.

You set this up at your own risk.

Windows. Open PowerShell as Administrator and run, on one line:

New-NetFirewallRule -DisplayName "Ollama LAN" -Direction Inbound -Action Allow -Protocol TCP -LocalPort 11434 -Profile Private -RemoteAddress LocalSubnet

-Profile Private is what keeps this off untrusted networks. It is worth checking that Windows actually classifies your network as Private, because a private rule does nothing on a network marked Public — the rule looks perfectly correct while the port stays shut. Run Get-NetConnectionProfile to see. If it says Public and this is your own network, change it with Set-NetConnectionProfile -InterfaceAlias "<name>" -NetworkCategory Private. Don't do that on public Wi-Fi.

One more Windows setting can defeat the rule while everything looks right: **Block all incoming connections, including those in the list of allowed apps** (Windows Security → Firewall & network protection → your active network). While that is ticked, Windows discards every inbound allow rule, so the rule exists, is enabled, is on the correct profile — and the port stays shut. Check it with Get-NetFirewallProfile | Select-Object Name, Enabled, AllowInboundRules: AllowInboundRules : False on the profile you are on is the culprit, and Set-NetFirewallProfile -Profile Private -AllowInboundRules True (as Administrator) undoes it.

Linux. With ufw, replacing the network with your own:

sudo ufw allow from 192.168.1.0/24 to any port 11434 proto tcp

Then check it took effect with sudo ufw status. If that says inactive, the rule is stored but nothing is enforcing it, and the port is governed by whatever else your distribution uses.

macOS. The built-in firewall allows or blocks whole applications, not individual ports. Check whether it is on at all under System Settings → Network → Firewall. If it is off, the port is already reachable and there is nothing to do. If it is on, allow the application with sudo /usr/libexec/ApplicationFirewall/socketfilterfw --add $(which ollama) followed by the same command with --unblockapp in place of --add. For LM Studio, use /Applications/LM Studio.app instead of $(which ollama).

To undo any of this, remove the rule rather than turning the firewall off — use Remove-NetFirewallRule -DisplayName "Ollama LAN" on Windows, sudo ufw status numbered followed by sudo ufw delete <number> on Linux, or --blockapp in place of --unblockapp on macOS.

Keep your endpoint on your own network

Where Ollama runs decides where your map content goes. Everything the AI sees — your map outline, notes, and chat — is sent to whatever Base URL you configure.

• On this device (localhost / 127.0.0.1) — nothing leaves the machine. Best for privacy.
• On your LAN (a 192.168.x, 10.x, or *.local host) — content stays on your own network.
The app shows an info notice; make sure the host is a machine you trust, since anyone who can reach it can read your prompts.
• On the public internet (a routable IP or a domain like ollama.example.com) — content leaves
your network entirely. The app shows a strong warning here.

⚠️ **Don't point the app at an Ollama or OpenAI-compatible endpoint on the public internet unless

you run and trust that server.** Doing so streams your private map content off your network, where

it may be logged or retained. The same caution applies to any remote, API-key-protected endpoint:

a remote endpoint is off-network regardless of whether it needs a key.

Your local database is always encrypted at rest, but that protection does not extend to content you send to a remote endpoint — which is exactly why the endpoint you choose matters. When sharing over a LAN, prefer plain HTTP only on a network you control; treat anything reachable from outside as public.

Your data

Where it lives

By default the app uses the platform's application-support directory:

To put it somewhere else, set a custom path in Settings → Data.

Changing the directory starts a guided migration: if the destination is empty, your database is moved there; if a database already exists there, the app switches to it without copying or overwriting anything. The destination database is never overwritten.

What is in that folder

Three files, and it is worth knowing which is which before you copy or sync any of them.

Copying or syncing all three is a complete backup; there is nothing else to take. Your key file, if you use one, is the exception in the other direction: keep it somewhere other than beside the database it unlocks.

Diagnostics are not in there. logs/ holds the last 20 sessions — which model was asked what, how long it took, what failed, in sizes and counts only, never the text of a prompt and never your API key — and it stays in the app's own application-support folder even if you move your data elsewhere, so a backup does not carry it and neither does a move. It is the one part you might want to hand to someone else.

Encryption & privacy

Everything meaningful is encrypted at rest, so you can safely keep or sync your data folder on public cloud storage (Google Drive, Dropbox, OneDrive, a USB stick).

• The whole database — nodes, notes, AI chat history — is encrypted with SQLCipher
(AES-256-CBC, per-page HMAC-SHA-512). It is tamper-evident as well as private.
• Your settings are encrypted too, so your AI API key is never written in cleartext.
• Your passphrase is stretched into a key with Argon2id and is never stored. Nothing on disk can
decrypt your data without it — which also means there is no recovery if you lose it.
• Optional key file as a second factor, and an optional remember on this device that caches
the key in the OS keychain (off by default).

Manage all of this under Settings → Security: change the passphrase or key file, toggle device caching, or Lock now to clear the key from memory. Changing your passphrase re-encrypts the database with a crash-safe procedure that rolls back if interrupted, so a rotation can never lock you out.

⚠️ Keep your passphrase safe. If you use a key file, store it separately from the database —

in the same cloud folder it adds no protection. There is no recovery if both are lost.

Display settings

Settings → Display has a global text-size control (Small / Normal / Large / XL) that applies to the app's UI text and persists across restarts. Map-canvas labels stay a fixed size so zoom behaves predictably.

Updates

The app checks a release feed on startup and tells you when a newer version is available; you can turn this off in Settings → About. Updates show what's new, download with live progress and a Cancel button, and verify the download's integrity before installing.

Settings → About also has a manual Check for updates, a preview of the release notes, and Skip this version.

Troubleshooting

The AI says it can't connect, or the model is missing

Check Settings → AI: the base URL must point at a running Ollama or LM Studio instance, and the model must show as installed. Pressing Save re-runs the install/start/download flow. The app tells you which step failed and offers Retry. Common errors are reported plainly: 401 means the API key, 404 means the base URL or model name, and timeouts mean the host is unreachable. If you're pointing at a shared box, re-check the steps under Share one Ollama server across your network or Share one LM Studio server across your network — usually the server was not started so other devices can reach it (OLLAMA_HOST=0.0.0.0, or lms server start --bind 0.0.0.0), or its port (11434 / 1234) is blocked by the host's firewall.

LM Studio: the app says its command-line tool isn't set up

LM Studio installs its lms tool the first time the app runs, so a freshly installed LM Studio does not have it yet. Open the LM Studio desktop app once, then press Retry. This is the most common LM Studio hiccup, and it is not a sign that anything is broken.

LM Studio: the model list is empty

Its server isn't running. Start it with lms server start, or open LM Studio and start the server from its Developer tab.

LM Studio: the first reply takes a minute

Expected — LM Studio loads a model into memory on demand, and the first request pays that cost. Keep LM Studio running and later replies are fast.

Semantic search finds nothing, or seems stale

The map may not be indexed yet — run the search once and let the indexing pass finish. If results still look wrong (for example after changing the embedding model), use **Settings → AI → Recompute embeddings now**.

The app asks for a passphrase I don't recognise

You have pointed the app at a data directory whose database was encrypted with different credentials. Either enter that database's passphrase, or switch back to your own data directory in Settings → Data.

"Database credentials missing"

The database is encrypted, but the file holding its credentials header is gone. Restore that file, or point the app at the correct data directory. The app deliberately will not set up a new key over the existing data — that would strand it permanently.

Linux: the window opens but the canvas is blank

This affects KDE with an NVIDIA GPU on an X11 session. Log in to a Plasma (Wayland) session instead — the app renders correctly there on the same hardware. GNOME sessions are unaffected.

Linux (Snap): the window is black and the display fix doesn't help

The Snap is sandboxed, so on some systems it can't reach your host's GPU drivers (notably certain NVIDIA setups) and has no working OpenGL — the window stays black. **Install the .deb package directly instead:** it runs unsandboxed and uses your system's own GPU drivers, exactly like any native app. This is a display-only limitation — local AI is unaffected either way, because Ollama runs as a separate service outside the app and keeps full GPU access regardless of how the app is packaged.

Fedora KDE (Snap): Discover hangs on "Refreshing Snap" after installing

Installing any Snap pulls in snapd, which activates Discover's Snap Store plugin (plasma-discover-snap). On Plasma 6.7.0–6.7.3 that plugin never reports that it has finished, so Discover's Updates page waits forever and hides your regular package updates too. It is an upstream Discover bug (KDE bug 500513), not a problem with your system or with this app — snapd itself works normally, and sudo dnf upgrade in a terminal is unaffected. Until the fix ships, remove the plugin and keep it from coming back with the next Plasma update. Run sudo dnf remove plasma-discover-snap, then add the line excludepkgs=plasma-discover-snap to /etc/dnf/dnf.conf.

Discover then updates normally again; Snaps stay installed and are managed with the snap command.

Something else is broken, or missing

Use Settings → About → Send feedback, or write to [email protected]. It opens your mail app with the version already filled in. This app is free and built by one person; what's missing or broken is the most useful thing you can send.

License

MindMap Chat is released under the Elastic License 2.0 — the full text is available in the app under Settings → About → License.

Free to use for personal and commercial work, and free to copy, share and modify. You may not offer it to others as a hosted or managed service, circumvent its license-key functionality, or remove its licensing notices.