atlas-mind 0.8.3

Self-hostable, AI-native knowledge base engine — an external brain you share with your AI.

Atlas Mind

It's your mind, not someone else's.

Notion, and every hosted notes app, ask you to pour your thinking into their structure, on their servers, in their format. You rent the space; they hold the keys. Atlas Mind inverts that: your knowledge is plain files in your own git repository, served by an engine you can read line by line and throw away without losing a single note. Your AI comes to your library through an open protocol; it never pulls your brain into its own.

Own the data. Own the engine. Own the mind.

🔗 Try the live demo → (offline build, some features missing) · What is Atlas Mind?

Atlas Mind is a self-hostable wiki / knowledge base engine, and an external brain you share with your AI. It serves a single-page viewer from a folder of documents (a mind), keeping the engine (the code) cleanly decoupled from your content (your notes, in their own git repository). Built on three ideas:

• Multi-format, not just Markdown. Markdown is first-class (rendered, linked, searched). Standalone HTML decks and dashboards, PDFs, and Word .docx are previewed inline, converted to readable HTML in your browser, nothing uploaded anywhere.
• AI-native. It exposes an MCP endpoint (twenty-two tools to read, write, map, rewind and audit your mind), and atlas init scaffolds the conventions (AGENTS.md, agents/, ai-sessions/) so an assistant knows how to use your mind.
• Lightweight & self-contained. A single Python HTTP server on the standard library: no database, accounts and share links live as plain JSON on disk, frontend libraries and fonts are vendored. A running instance makes no third-party network calls: your mind never leaves your disk, and nothing you write trains anyone's model.

It is not a multi-tenant SaaS, a real-time collaborative editor, or a plugin marketplace. One focused mind per instance, fully yours.

Install

Installing puts a self-contained atlas command on your PATH (the viewer assets ship inside the package, no separate download).

# Easy way: uv or pipx (isolated env, no virtualenv to manage)
uv tool install atlas-mind        # or: pipx install atlas-mind
atlas serve ~/my-mind

# Run once without installing, straight from PyPI
uvx atlas-mind serve ~/my-mind    # or: pipx run atlas-mind serve ~/my-mind

# With pip (a virtualenv is recommended)
pip install atlas-mind

Requires Python >= 3.11 and a git repository for your content.

Quick start

atlas init ~/my-mind     # scaffold a mind: atlas.toml, example docs, AGENTS.md, git init
atlas serve ~/my-mind    # build once if needed, then serve on http://127.0.0.1:8765

init is never destructive (it refuses a non-empty directory without --force and keeps any file already present). serve listens on 127.0.0.1:8765 with authentication off by default. To produce the static viewer without serving: atlas build ~/my-mind [--offline].

See atlas --help for all commands (user, token, share, deploy).

Use it with your AI (MCP)

Atlas Mind is designed to be the external memory your assistant reads and writes. On a deployed instance, each user mints their own token from the web UI — Settings → Tokens — bound to their account; it prints the MCP URL to point your AI at.

Locally (or to script it), the CLI does the same:

atlas token create ~/my-mind --label claude
# → prints the MCP URL: https://<your-atlas>/mcp/<token>

The MCP endpoint exposes twenty-two tools in five groups:

• read: search_docs, read_doc, list_tree, recent_docs
• write: create_doc, edit_doc, move_doc (fixes incoming [[backlinks]]), delete_doc (soft-delete to .trash/)
• graph: get_links, get_backlinks, list_by_tag, get_mind_topology
• time-travel (your mind is a git repo): doc_history, doc_at, doc_diff, search_history, changelog, doc_blame, doc_revert
• activity (the attribution layer's read side): activity (who changed what, with AI-author detection), stale (docs untouched for months — obsolescence), contradictions (same-topic doc pairs to review)

atlas init scaffolds AGENTS.md + content/agents/ + content/ai-sessions/ so the assistant knows your conventions. There is also a REST API v1 (Bearer tokens, create-only writes) with a published OpenAPI 3.1 spec.

Features

• Reading: GitHub-flavoured Markdown (TOC, syntax highlighting, reading time, tag bar), inline preview of standalone HTML decks/dashboards, PDF, and .docx (converted in-browser, read-only). Download any file as its original.
• Navigation: collapsible tree, full-text search (server-side online, fuzzy MiniSearch offline), [[wikilinks]] + backlinks + "same subject", folder/frontmatter tags, mind-wide task rollup, command palette (Ctrl-K), pinned and recent docs.
• The Mind: a force-directed mind palace where every document and tag is a navigable node, colour-grouped by folder, recent nodes glowing, orphans dimmed.
• Editing: create / edit / rename / move / delete from the viewer (moving rewrites the wikilinks pointing at a doc), document templates, interactive task checkboxes, a categorised todos widget.
• History: every document git-versioned, with a revision list, clean diffs, view/restore of past versions (restore is a new commit), renames and moves followed.
• Activity: a home card over the attributed git history — a journal of who-changed-what (with AI-author detection and a per-doc history peek), a constellation of contributors, and a Health view that surfaces stale documents (obsolescence) and same-topic contradiction candidates for your AI to review.
• Annotations: notes anchored to a text selection, re-anchored on later visits, with one-click copy-all-notes as Markdown.
• Sharing: per-document access in cloud mode (private / shared with people or groups / common to the team), plus HMAC-signed public share links with optional expiry.
• Offline & PWA: a self-contained index-offline.html that works from file://, an installable PWA via service worker, live reload over SSE.
• i18n: French and English, a single carefully-built dark theme, re-skinnable via a CSS extension.

Self-hosting

• Cloud mode: accounts and login (admin / member roles), per-document access control, cookie sessions, optional TOTP 2FA with recovery codes, per-account lockout and per-IP login rate limiting, full CSRF defence.
• Deployment: atlas deploy ~/my-mind --target compose|systemd|fly; fly --wizard deploys end-to-end.
• Configuration: a small atlas.toml (brand prefix, port, auth, content paths).
• Updating: engine and content update independently, and upgrading the engine never touches your notes.

Documentation

The documentation is itself an Atlas mind — browse it in the live demo → (the guides/ and features/ sections).

Licence

AGPL v3, see LICENSE. The "Atlas" + "Mind" branding in the viewer and login page is a fixed part of the project.