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 or LM Studio. Keep that runtime's default
local 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.
3. Pick a Model from the curated list — each shows an installed/missing badge. 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.

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 them 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.

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.

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.