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.

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, the provider is Ollama. Keep the default local endpoint
(http://localhost:11434/v1) or point it at a remote Ollama host.
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.

Zero-touch setup: for a local endpoint, pressing Save installs Ollama if it's missing, starts the service, and pulls the model you selected — with a progress checklist, and Cancel / Retry if anything fails. Steps that are already done are skipped, so retrying never re-downloads. On Android and iOS, Ollama works against a remote endpoint; automatic local install is desktop-only.

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

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 instance, and the model must show as installed. Pressing Save re-runs the install/start/pull 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.

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.

Something else is broken, or missing. Use Settings → About → Send feedback, or write to feedback@mindmapchat.app. 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.