From 8154234a5f49237739f4e8e6a98e1b2b3e841184 Mon Sep 17 00:00:00 2001 From: aniongithub Date: Sun, 10 May 2026 10:05:44 -0700 Subject: [PATCH 1/6] docs: update README for HTTPS, TLS, service management MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Add website badge and hero GIF (mind-map-save-edit-retrieve.gif) - Add 'Works with' line (Copilot, Claude, Cursor) - Update HTTP → HTTPS throughout - Update default port references (443) - Add installer details (hosts file, TLS, service setup) - Add Service Management section - Add TLS Setup section - Fix MCP tools count (8 → 9, register_sync was listed separately) - Update architecture diagram (HTTP Server → HTTPS Server) - Update Two Modes table (HTTP → HTTPS) - Fix CI/CD platforms count (4 → 6) - Standardize dashes (-- → —) --- README.md | 90 +++++++++++++++++++++++++++++++++++++++++-------------- 1 file changed, 67 insertions(+), 23 deletions(-) diff --git a/README.md b/README.md index 57c983b..2e8ec8d 100644 --- a/README.md +++ b/README.md @@ -1,28 +1,35 @@ # mind-map [![CI](https://github.com/aniongithub/mind-map/actions/workflows/ci.yml/badge.svg)](https://github.com/aniongithub/mind-map/actions/workflows/ci.yml) +[![Website](https://img.shields.io/badge/website-mind--map-blue)](https://www.anionline.me/mind-map) **A wiki for AI agents — and humans too.** `mind-map` is a wiki engine that stores pages as plain markdown files, indexes them with SQLite FTS5, and exposes them via MCP (for AI agents) and a REST API with web UI (for humans). One binary, zero runtime dependencies. +

+ mind-map agent demo +

+ +> Works with **GitHub Copilot**, **Claude**, **Cursor**, and any MCP-compatible client. + ## The Problem AI agents need persistent, structured memory. Today that means: -- **Desktop apps** -- tools like Tolaria require Node.js + Rust + WebKit + a display server just to give agents a knowledge base -- **No web access** -- the knowledge is locked in a desktop app only the local user can see -- **Can't deploy headless** -- needs a GUI environment even when no human is looking +- 🔴 **Desktop apps** — tools like Tolaria require Node.js + Rust + WebKit + a display server just to give agents a knowledge base +- 🔴 **No web access** — the knowledge is locked in a desktop app only the local user can see +- 🔴 **Can't deploy headless** — needs a GUI environment even when no human is looking ## The Solution -`mind-map` is a **server**, not an app. It runs anywhere -- your laptop, a container or a cloud VM. +`mind-map` is a **server**, not an app. It runs anywhere — your laptop, a container, or a cloud VM. -1. **Agents use stdio** -- `mind-map` with no args starts an MCP server on stdin/stdout -2. **Humans use the web UI** -- `mind-map serve` starts an HTTP server with REST API and browser UI -3. **One binary** -- Go, statically compiled, `curl | bash` to install -4. **Plain markdown** -- pages are `.md` files with YAML frontmatter. Git-friendly, portable, yours -5. **Multi-process safe** -- SQLite page locking lets multiple agents share the same wiki directory +1. **Agents use stdio** — `mind-map` with no args starts an MCP server on stdin/stdout +2. **Humans use the web UI** — `mind-map serve` starts an HTTPS server at `https://mind-map.local` +3. **One binary** — Go, statically compiled, `curl | bash` to install +4. **Plain markdown** — pages are `.md` files with YAML frontmatter. Git-friendly, portable, yours +5. **Multi-process safe** — SQLite page locking lets multiple agents share the same wiki directory ``` Agent: "What do we know about authentication?" @@ -45,6 +52,12 @@ curl -fsSL https://github.com/aniongithub/mind-map/releases/latest/download/inst Invoke-RestMethod https://github.com/aniongithub/mind-map/releases/latest/download/install.ps1 | Invoke-Expression ``` +The installer: +- Downloads the binary and adds it to PATH +- Adds `127.0.0.1 mind-map.local` to your hosts file +- Generates a local TLS certificate so `https://mind-map.local` works with no browser warnings +- Optionally installs mind-map as a persistent system service + Binaries available for **linux-x64**, **linux-arm64**, **darwin-x64**, **darwin-arm64**, **windows-x64**, and **windows-arm64**. ## Architecture @@ -54,8 +67,8 @@ graph TD A[Preact Web App] -->|REST API| B C[AI Agent] -->|MCP stdio| D - subgraph "mind-map serve" - B[HTTP Server] --> E[Wiki Engine] + subgraph "mind-map serve (HTTPS)" + B[HTTPS Server] --> E[Wiki Engine] end subgraph "mind-map (stdio)" @@ -66,18 +79,18 @@ graph TD E -->|read/write| G[Markdown Files] ``` -The web UI is a static Preact app served by `mind-map serve`. It uses a REST API to read and write pages. AI agents use stdio MCP -- each agent launches its own `mind-map` process. +The web UI is a static Preact app served by `mind-map serve` over HTTPS. It uses a REST API to read and write pages. AI agents use stdio MCP — each agent launches its own `mind-map` process. ## Two Modes | Mode | Command | Use case | |------|---------|----------| | **stdio** (default) | `mind-map` | AI agents (Copilot, Claude, Cursor) | -| **HTTP** | `mind-map serve` | Web UI for humans | +| **HTTPS** | `mind-map serve` | Web UI for humans at `https://mind-map.local` | Both modes use the same wiki engine and the same wiki directory (`~/.mind-map/wiki` by default). Multiple stdio processes can safely share the same wiki via SQLite page locking. -## MCP Tools (8 total) +## MCP Tools (9 total) | Tool | Description | |------|-------------| @@ -89,17 +102,16 @@ Both modes use the same wiki engine and the same wiki directory (`~/.mind-map/wi | `delete_page` | Delete a page from the wiki and search index | | `list_pages` | List pages, optionally filtered by path prefix | | `get_backlinks` | Get all pages that link to a given page | - | `register_sync` | Register a wiki path prefix to sync with a git remote | ## Wiki Features -- **YAML frontmatter** -- structured metadata on every page (`title`, `type`, `status`, custom fields) -- **Wikilinks** -- `[[target]]` and `[[display|target]]` syntax, resolved to clickable links -- **Backlink index** -- every page knows what links to it -- **Full-text search** -- SQLite FTS5 with ranked results and snippets -- **Multi-process safe** -- SQLite page locking for concurrent agent access -- **Git sync** -- sync wiki pages to GitHub repo wikis via configurable mappings +- **YAML frontmatter** — structured metadata on every page (`title`, `type`, `status`, custom fields) +- **Wikilinks** — `[[target]]` and `[[display|target]]` syntax, resolved to clickable links +- **Backlink index** — every page knows what links to it +- **Full-text search** — SQLite FTS5 with ranked results and snippets +- **Multi-process safe** — SQLite page locking for concurrent agent access +- **Git sync** — sync wiki pages to GitHub repo wikis via configurable mappings ## Web UI @@ -113,6 +125,38 @@ The built-in web UI is a metro-inspired, chromeless Preact app: The web UI speaks the same language as the wiki engine. If an agent creates a page via stdio, it appears in the browser. If you edit in the browser, the agent sees the change on its next read. +## Service Management + +The installer can set up mind-map as a persistent system service that starts on boot: + +```bash +# Install and start the service +sudo mind-map service install --addr 127.0.0.1:443 +sudo mind-map service start + +# Manage +sudo mind-map service status +sudo mind-map service stop +sudo mind-map service uninstall +``` + +## TLS Setup + +The installer automatically generates a local CA and server certificate so `https://mind-map.local` works without browser warnings. You can also manage certificates manually: + +```bash +# Generate certs (as your user) +mind-map tls generate + +# Install CA in system trust store (requires sudo on Linux) +sudo mind-map tls install-ca --tls-dir ~/.mind-map/tls + +# Remove everything +mind-map tls remove +``` + +On Linux, Chrome uses its own NSS certificate store. The installer handles this automatically if `libnss3-tools` is available. + ## MCP Client Configuration ```json @@ -128,7 +172,7 @@ The web UI speaks the same language as the wiki engine. If an agent creates a pa } ``` -That's it. No args needed -- stdio mode and `~/.mind-map/wiki` are the defaults. Override the directory with `--dir` if needed. +That's it. No args needed — stdio mode and `~/.mind-map/wiki` are the defaults. Override the directory with `--dir` if needed. ## Page Format @@ -185,7 +229,7 @@ devcontainer exec --workspace-folder . bash -c "go test ./..." ### CI/CD - **Pull Requests** — builds webui, runs `go vet`, `go test` in the devcontainer -- **Releases** — creating a GitHub release cross-compiles for all 4 platforms and uploads binaries + install scripts +- **Releases** — creating a GitHub release cross-compiles for all 6 platforms and uploads binaries + install scripts ## License From 6b594bcf033689238f54c34ce08d2d255adcce9d Mon Sep 17 00:00:00 2001 From: aniongithub Date: Sun, 10 May 2026 10:09:47 -0700 Subject: [PATCH 2/6] docs: add 'Why a wiki?' section positioning vs RAG/Obsidian References Karpathy's LLM Knowledge Base pattern. Highlights SQLite FTS5 as production-grade search vs hand-rolled scripts, server-first architecture vs desktop apps, and plain markdown portability. --- README.md | 11 +++++++++++ 1 file changed, 11 insertions(+) diff --git a/README.md b/README.md index 2e8ec8d..e926345 100644 --- a/README.md +++ b/README.md @@ -38,6 +38,17 @@ Agent: "What do we know about authentication?" → ✅ Full page with frontmatter, links, and backlinks ``` +## Why a wiki? + +The idea of [LLM-maintained knowledge bases](https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f) — where AI agents build and curate a persistent wiki rather than re-discovering answers via RAG — has been gaining traction. Tools like Obsidian work well as front-ends, but they're desktop apps that agents can't easily access. + +`mind-map` is purpose-built for this pattern: + +- **Server-first** — agents access it via MCP, humans via the browser. No desktop app, no GUI required +- **First-class search** — powered by [SQLite FTS5](https://www.sqlite.org/fts5.html), a production-grade full-text search engine with ranked results and snippets. No vibe-coded search scripts +- **Wikilinks + backlinks** — `[[target]]` syntax with a maintained backlink index, so the knowledge graph is always navigable +- **Plain markdown** — your data is `.md` files in a directory. `git diff` them, sync them, move them anywhere + ## Quick Install ### Linux / macOS From 8d5107ee98a1ac33452beb477e3e7152a27d2b18 Mon Sep 17 00:00:00 2001 From: aniongithub Date: Sun, 10 May 2026 10:12:24 -0700 Subject: [PATCH 3/6] docs: consolidate into 'Why a wiki?' with problem/solution table Merge The Problem, The Solution, and Why a wiki? into a single compact section with a two-column table. Moves it before the code example for better flow. --- README.md | 35 +++++++++-------------------------- 1 file changed, 9 insertions(+), 26 deletions(-) diff --git a/README.md b/README.md index e926345..7cc4009 100644 --- a/README.md +++ b/README.md @@ -13,23 +13,17 @@ > Works with **GitHub Copilot**, **Claude**, **Cursor**, and any MCP-compatible client. -## The Problem - -AI agents need persistent, structured memory. Today that means: - -- 🔴 **Desktop apps** — tools like Tolaria require Node.js + Rust + WebKit + a display server just to give agents a knowledge base -- 🔴 **No web access** — the knowledge is locked in a desktop app only the local user can see -- 🔴 **Can't deploy headless** — needs a GUI environment even when no human is looking - -## The Solution +## Why a wiki? -`mind-map` is a **server**, not an app. It runs anywhere — your laptop, a container, or a cloud VM. +The idea of [LLM-maintained knowledge bases](https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f) — where AI agents build and curate a persistent wiki rather than re-discovering answers via RAG — has been gaining traction. Tools like Obsidian work well as front-ends, but they're desktop apps that agents can't easily access. `mind-map` is purpose-built for this pattern. -1. **Agents use stdio** — `mind-map` with no args starts an MCP server on stdin/stdout -2. **Humans use the web UI** — `mind-map serve` starts an HTTPS server at `https://mind-map.local` -3. **One binary** — Go, statically compiled, `curl | bash` to install -4. **Plain markdown** — pages are `.md` files with YAML frontmatter. Git-friendly, portable, yours -5. **Multi-process safe** — SQLite page locking lets multiple agents share the same wiki directory +| The problem | The solution | +|---|---| +| Desktop apps (Tolaria, Obsidian) need Node.js, Rust, WebKit, or a display server | **Server-first** — one static binary, runs headless, `curl \| bash` to install | +| Knowledge locked in a desktop app only the local user can see | **Agents use MCP, humans use the browser** at `https://mind-map.local` | +| Can't deploy headless — needs a GUI even when no human is looking | **Runs anywhere** — laptop, container, cloud VM | +| Hand-rolled search scripts that break at scale | **First-class search** — [SQLite FTS5](https://www.sqlite.org/fts5.html) with ranked results and snippets | +| Knowledge re-discovered via RAG on every query | **Persistent wiki** — wikilinks, backlinks, and plain `.md` files that grow over time | ``` Agent: "What do we know about authentication?" @@ -38,17 +32,6 @@ Agent: "What do we know about authentication?" → ✅ Full page with frontmatter, links, and backlinks ``` -## Why a wiki? - -The idea of [LLM-maintained knowledge bases](https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f) — where AI agents build and curate a persistent wiki rather than re-discovering answers via RAG — has been gaining traction. Tools like Obsidian work well as front-ends, but they're desktop apps that agents can't easily access. - -`mind-map` is purpose-built for this pattern: - -- **Server-first** — agents access it via MCP, humans via the browser. No desktop app, no GUI required -- **First-class search** — powered by [SQLite FTS5](https://www.sqlite.org/fts5.html), a production-grade full-text search engine with ranked results and snippets. No vibe-coded search scripts -- **Wikilinks + backlinks** — `[[target]]` syntax with a maintained backlink index, so the knowledge graph is always navigable -- **Plain markdown** — your data is `.md` files in a directory. `git diff` them, sync them, move them anywhere - ## Quick Install ### Linux / macOS From f10893f57292fb8dc39fa751632829989d6a8f51 Mon Sep 17 00:00:00 2001 From: aniongithub Date: Sun, 10 May 2026 10:15:33 -0700 Subject: [PATCH 4/6] =?UTF-8?q?docs:=20reframe=20Obsidian=20comparison=20?= =?UTF-8?q?=E2=80=94=20agent=20and=20human=20on=20equal=20ground?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 7cc4009..bf35804 100644 --- a/README.md +++ b/README.md @@ -15,7 +15,7 @@ ## Why a wiki? -The idea of [LLM-maintained knowledge bases](https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f) — where AI agents build and curate a persistent wiki rather than re-discovering answers via RAG — has been gaining traction. Tools like Obsidian work well as front-ends, but they're desktop apps that agents can't easily access. `mind-map` is purpose-built for this pattern. +The idea of [LLM-maintained knowledge bases](https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f) — where AI agents build and curate a persistent wiki rather than re-discovering answers via RAG — has been gaining traction. Tools like Obsidian are built with the user in mind, not the agent. `mind-map` puts the agent and the human on equal ground. | The problem | The solution | |---|---| From 3f27c70c811b5457c4958f331f2fc6b4a1b47387 Mon Sep 17 00:00:00 2001 From: aniongithub Date: Sun, 10 May 2026 10:17:20 -0700 Subject: [PATCH 5/6] docs: add Quick Install intro paragraph --- README.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/README.md b/README.md index bf35804..54c8318 100644 --- a/README.md +++ b/README.md @@ -34,6 +34,8 @@ Agent: "What do we know about authentication?" ## Quick Install +Unlike other wiki knowledge bases, you don't need a tutorial, any system dependencies, or RAM-guzzling UIs. Just copy-paste the command for your OS into a terminal, answer a few questions, and it's up and running — accessible in a browser and via MCP. + ### Linux / macOS ```bash From ce80e6cc9f5d95b40505270a84edb156b800dc05 Mon Sep 17 00:00:00 2001 From: aniongithub Date: Sun, 10 May 2026 10:19:30 -0700 Subject: [PATCH 6/6] =?UTF-8?q?docs:=20rewrite=20Quick=20Install=20intro?= =?UTF-8?q?=20=E2=80=94=20zero=20manual=20setup?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 54c8318..7748b0a 100644 --- a/README.md +++ b/README.md @@ -34,7 +34,7 @@ Agent: "What do we know about authentication?" ## Quick Install -Unlike other wiki knowledge bases, you don't need a tutorial, any system dependencies, or RAM-guzzling UIs. Just copy-paste the command for your OS into a terminal, answer a few questions, and it's up and running — accessible in a browser and via MCP. +Unlike other wiki knowledge bases, you don't need a tutorial, system dependencies, or RAM-guzzling UIs. Just copy-paste the command for your OS into a terminal and answer a few questions. The installer downloads the binary, sets up HTTPS at `https://mind-map.local`, configures MCP for GitHub Copilot, Claude, Cursor, and VS Code, and installs agent skills — so every AI coding tool on your machine can use mind-map immediately. Zero manual setup. ### Linux / macOS