Mind-o-Mat
Local Second-Brain system for Obsidian-compatible Markdown vaults with deterministic indexing, LLM wiki ingestion, QMD hybrid search, and PWA web UI.
Overview
Mind-o-Mat is the core CLI, API server, and web application for a local, Git-backed Second-Brain system built around Obsidian-compatible Markdown vaults. It cleanly separates logic and UI (this tool repository) from notes and data (a separate vault repository such as Mind-o-Mat-Vault), while also serving as the backend for the native Android client (Mind-o-Mat-App).
System Architecture
┌─────────────────────────────────────────────────────────────┐
│ Mind-o-Mat (Tool) │
│ │
│ ┌───────────┐ ┌──────────┐ ┌──────────┐ ┌────────────┐ │
│ │ CLI │ │ Indexer │ │ Ingest │ │ Webapp │ │
│ │ init- │ │ scan + │ │ LLM + │ │ React + │ │
│ │ vault, │ │ parse │ │ confl. │ │ Cytosc. │ │
│ │ index, │ │ + stale │ │ + watch │ │ + Tiptap │ │
│ │ ingest, │ │ + dupl. │ │ + TFIDF │ │ + PWA │ │
│ │ sync │ │ │ │ │ │ Manifest │ │
│ └─────┬─────┘ └─────┬────┘ └────┬─────┘ └──────┬─────┘ │
│ │ │ │ │ │
└────────┼──────────────┼────────────┼───────────────┼────────┘
│ │ │ │
│ ▼ │ ▼
│ landkarte.json │ Browser / PWA / App
│ │ │ │
│ └─────┬──────┘ │
│ ▼ │
│ 00_Inbox/*.md │
│ │ │
▼ ▼ ▼
┌─────────────────────────────────────────────────────┐
│ Mind-o-Mat-Vault (Data) │
│ 00_Inbox/ 01_Daily/ 10_Wiki/ 20_Projekte/ ... │
│ 99_System/Konfig.md (thresholds, AI config) │
└─────────────────────────────────────────────────────┘
│
▼ git push (mindomat sync)
┌────────────┐
│ Gitea │
│ Remote │
└────────────┘
The 5 Building Blocks
| # | Component | Purpose | AI? | Location |
|---|---|---|---|---|
| 1 | Vault | Markdown files, single source of truth | No | Separate Vault repo |
| 2 | Indexer | Deterministic scanner: parses frontmatter, extracts wikilinks, detects stale notes & duplicates | No | This tool repo |
| 3 | QMD | Local hybrid search (BM25 + vector embeddings + re-ranking) via @tobilu/qmd |
Local models | Installed in vault / container |
| 4 | Wiki (Ingest) | Maintains curated wiki pages via LLM with deterministic conflict pre-check | Yes (MiniMax API) | This tool repo |
| 5 | Webapp / PWA | Interactive knowledge graph, cluster map, radial view, note list, Tiptap editor, Android TWA support | No | This tool repo (webapp/) |
Features
- Vault Initialization (
init-vault): Creates the 12-directory Obsidian-compatible structure (00_Inbox/,01_Daily/,10_Wiki/,20_Projekte/,90_Templates/,99_System/, etc.),.gitignore,99_System/Konfig.md,10_Wiki/_Schema.md,CLAUDE.md, two starter demo notes, and initializes Git onmainwith optional Gitea remote setup. - Deterministic Vault Indexer (
index):- Parses YAML frontmatter (
gray-matter) and classifies notes intoinbox,daily,wiki,project, orunknown. - Extracts
[[wikilinks]]and detects orphaned/dead links. - Detects stale notes (
veraltet) based onaktualisiert/createdagainstveraltet_schwellwert_monate(default: 12 months; wiki pages are exempt). - Detects exact duplicates via SHA-256 body content hashes and similar notes via TF-IDF cosine similarity (
> 0.15in system index). - Generates deterministic outputs:
landkarte.json,99_System/Index.md, and10_Wiki/Index.md.
- Parses YAML frontmatter (
- AI Wiki Ingestion (
ingest):- Processes notes from
00_Inbox/into curated pages under10_Wiki/Seiten/using MiniMax Chat Completions (MiniMax-M3by default) following10_Wiki/_Schema.md. - Runs deterministic conflict pre-checking (
preCheckConflictchecking German negation terms + shared keywords) before calling the LLM. - Supports
--mock(offline simulated responses),--note <file>,--dry-run, and--watch/-w(Chokidar inbox file watcher). - Automatically moves processed notes to
00_Inbox/Verarbeitet/<date>/or failed notes to00_Inbox/Problemfaelle/with logs in99_System/Logs/.
- Processes notes from
- Gitea Synchronization (
sync):- Uses a lockfile (
99_System/Skripte/Lock/Sync.lock) and writes daily logs (99_System/Logs/Sync_YYYY-MM-DD.md). - Stages and commits local changes, runs
git pull --rebase --autostash, and pushes toorigin main.
- Uses a lockfile (
- Production Webapp & Notes API (
server.mjs):- Serves the Vite-built React + TypeScript PWA (
webapp/dist) alongside REST endpoints (/api/status,/api/notes,/api/notes/:id,/api/capture,/api/sync,/landkarte.json,/note). - Supports optional HMAC-SHA256 Bearer token authentication (
<timestamp>.<hmac-sha256-hex>) and CORS origin allowlisting. - Runs automatic background Git sync + re-indexing every 5 minutes when the mounted vault is a Git repository.
- In Docker (
entrypoint.sh), pulls/clones the vault, runs initial indexing, starts the QMD MCP daemon on port8181, and serves the webapp/API on port5173.
- Serves the Vite-built React + TypeScript PWA (
- Interactive PWA Frontend (
webapp/):- 5 Views: Force-directed Graph (
cytoscapecoselayout), Note List (with live filtering), Cluster Map, Radial View, and Tiptap WYSIWYG/Markdown Split-Preview Editor (@tiptap/react+marked+turndown). - Quick "+ Neue Notiz" creation dialog, node inspection sidebar, and PWA manifest / service worker (
webapp/public/manifest.webmanifest,service-worker.js) with TWA packaging support (scripts/build-twa.mjs,webapp/TWA-BUILD.md).
- 5 Views: Force-directed Graph (
How It Works & Tech Stack
| Layer | Technology | Details |
|---|---|---|
| Runtime | Node.js >=22.0.0 (ESM) |
TypeScript 5.6 compiled to dist/ |
| CLI Binary | bin/mindomat.mjs |
Exposes mindomat command (init-vault, index, ingest, sync) |
| Backend Server | Express 4 (server.mjs), gray-matter, chokidar |
Production static + Notes API server; Vite middleware in dev (src/notes-api-server.ts) |
| Frontend (PWA) | React 18, Vite 5, Cytoscape 3.30, Tiptap 3, Marked, Turndown | Built to webapp/dist/ |
| Hybrid Search | @tobilu/qmd |
BM25 + local GGUF embeddings & re-ranking; MCP HTTP daemon |
| LLM Integration | MiniMax API (/chat/completions) |
Configured via 99_System/Konfig.md + MINIMAX_API_KEY |
| Testing & Quality | Vitest 5, Playwright, Testing Library, ESLint 9, Prettier | Unit, integration, and E2E tests in tests/ |
| Container | Multi-stage Dockerfile (node:22-bookworm-slim) + tini |
Runs as non-root node user |
Ports
| Port | Service | Description |
|---|---|---|
5173 |
Webapp & Notes API | Express production server (server.mjs) and Vite dev server |
8181 |
QMD MCP Daemon | Started inside Docker by entrypoint.sh (qmd mcp --http --daemon --host 0.0.0.0 --port 8181) |
Prerequisites & Installation
Prerequisites
- Node.js
>= 22.0.0and npm - Git (for vault initialization and
sync) - Optional for hybrid search:
@tobilu/qmd(npm install -g @tobilu/qmd) - Optional for container deployment: Docker
Local Installation
git clone https://git.orfel.de/Jannik/Mind-o-Mat.git
cd Mind-o-Mat
npm install
npm run build
npm link
Install frontend dependencies and build the webapp:
cd webapp
npm install
npm run build
Initialize a Vault & Set Up QMD (One-Time)
# 1. Create a complete vault structure (12 folders, config, 2 demo notes, git init)
mindomat init-vault C:\GitHub\My-Vault
# 2. Configure Gitea remote (if not passed via --remote)
cd C:\GitHub\My-Vault
git remote add origin https://git.orfel.de/YourUser/My-Vault.git
git push -u origin main
# 3. Install and configure QMD hybrid search (downloads ~2 GB models on first embed)
npm install -g @tobilu/qmd
qmd collection add 00_Inbox --name inbox
qmd collection add 01_Daily --name daily
qmd collection add 10_Wiki --name wiki
qmd collection add 20_Projekte --name projekte
qmd embed
# 4. Generate initial vault index
mindomat index
Docker Deployment
Build and run the multi-stage container image:
docker build -t mindomat .
docker run -d \
--name mindomat \
-p 5173:5173 \
-p 8181:8181 \
-e MINDOMAT_VAULT_PATH=/vault \
-e MINIMAX_API_KEY=sk-your-key \
-e NOTES_API_TOKEN=your-hmac-secret \
-v /path/to/your/vault:/vault \
-v mindomat-qmd-cache:/data \
mindomat
If VAULT_SYNC_TOKEN is provided and /vault/.git does not yet exist, entrypoint.sh automatically clones https://<VAULT_SYNC_TOKEN>@git.orfel.de/Jannik/Mind-o-Mat-Vault.git into /vault, runs an initial mindomat index, starts qmd mcp on 8181, and starts node server.mjs on 5173.
Configuration
Copy .env.example to .env (note: the CLI itself reads process environment variables directly; in PowerShell use $env:VAR = "..." or in Bash export VAR=... — see docs/SECRETS.md for details).
| Variable | Default / Example | Description |
|---|---|---|
MINIMAX_API_KEY |
— | MiniMax API key for live ingest (or whichever env name is set in 99_System/Konfig.md under ki_api_key_env) |
MINDOMAT_VAULT_PATH |
/vault (Docker), C:/GitHub/Mind-o-Mat-Vault (Vite dev) |
Path to the target Markdown vault |
PORT |
5173 |
HTTP port for server.mjs |
NOTES_API_TOKEN |
(empty = auth disabled) | Shared HMAC-SHA256 secret required for Bearer auth on API endpoints |
NOTES_API_ALLOWED_ORIGINS |
(empty = all origins) | Comma-separated CORS allowlist (e.g. https://mindomat.orfel.de) |
VAULT_SYNC_TOKEN |
— | Gitea access token used by entrypoint.sh to clone/pull the vault repository |
QMD_CACHE_DIR |
/data (Docker) |
Cache directory for QMD inside the container |
QMD_CACHE_PATH |
99_System/Cache |
Optional QMD cache path inside the vault |
GITEA_REMOTE |
— | Optional Gitea remote URL reference |
Token Generation & Additional Docs
- Generate an API Bearer token (
<timestamp>.<hmac-sha256-hex>):$env:NOTES_API_TOKEN = "your-hmac-secret" npm run token-gen - See
docs/SECRETS.mdfor.env, Gitea CI secrets, and optionalageencryption workflows. - See
docs/BACKUP.md,docs/MIGRATION.md,docs/openapi.yaml, andwebapp/TWA-BUILD.mdfor backup strategies, API specs, and Android TWA packaging.
Usage
CLI Reference
mindomat --version # Show version (0.1.0)
mindomat --help # Show CLI help
mindomat init-vault <path> # Initialize a new vault
# --remote <url> Set Gitea origin URL
# --no-commit Create structure without initial commit
# --no-interactive Skip interactive prompts
# --force Overwrite existing vault config
mindomat index --vault <path> # Deterministically index vault -> landkarte.json + Index.md files
# (or set MINDOMAT_VAULT_PATH)
mindomat ingest --vault <path> # Process 00_Inbox/*.md -> 10_Wiki/Seiten/*.md
# --mock Simulate LLM response without API key
# --note <filename> Process only a single inbox note
# --dry-run Preview without writing/moving files
# --watch, -w Watch 00_Inbox/ continuously
mindomat sync --vault <path> # Commit local changes, git pull --rebase --autostash, git push origin main
# --message, -m Custom commit message
# --force Ignore existing Sync.lock file
Example Workflow
# 1. Create an inbox note
echo "[[Coffee]] tastes great." > C:\GitHub\My-Vault\00_Inbox\2026-09-05_Note.md
# 2. Ingest inbox notes into the wiki
mindomat ingest --vault C:\GitHub\My-Vault
# 3. Rebuild deterministic graph index
mindomat index --vault C:\GitHub\My-Vault
# 4. Start Webapp (dev mode)
cd C:\GitHub\Mind-o-Mat\webapp
npm run dev
# Opens http://localhost:5173
# 5. Sync vault to Gitea
mindomat sync --vault C:\GitHub\My-Vault
Production HTTP API Endpoints (server.mjs)
| Method | Endpoint | Auth | Description |
|---|---|---|---|
GET |
/api/status |
No | Health/status check (ok, name, version, authRequired) |
GET |
/landkarte.json |
No | Serves vault landkarte.json (runs indexer on demand if missing) |
GET |
/note?path=<relPath> |
No | Returns raw Markdown content { content } for a vault path |
GET |
/api/notes |
Bearer* | Lists note IDs and metadata summaries from 00_Inbox, 10_Wiki/Seiten, 01_Daily, 20_Projekte |
GET |
/api/notes/:id |
Bearer* | Returns full note content and parsed frontmatter |
PUT |
/api/notes/:id |
Bearer* | Saves note content and triggers background re-indexing |
POST |
/api/capture |
Bearer* | Quick-capture endpoint (text, title, tags, autoIngest, autoSync, targetFolder) used by the Android app |
POST |
/api/sync |
Bearer* | Triggers mindomat sync --vault <VAULT_PATH> |
*Bearer auth is enforced when NOTES_API_TOKEN is set (same-origin browser requests from allowed origins are exempted in server.mjs).
Running Tests & Checks
npm test # Run Vitest unit/integration tests
npm run test:e2e # Run Playwright E2E tests
npm run lint # ESLint check
npm run format:check # Prettier check
npm run build # Compile TypeScript CLI/core
cd webapp && npm run build # Build Vite PWA bundle
Project Structure
Mind-o-Mat/
├── bin/
│ └── mindomat.mjs # CLI executable entrypoint
├── docs/
│ ├── BACKUP.md # 3-tier backup & disaster recovery guide
│ ├── MIGRATION.md # Migration notes
│ ├── SECRETS.md # Secret management (.env, CI, age)
│ └── openapi.yaml # OpenAPI 3.1 spec for Notes API
├── scripts/
│ ├── build-twa.mjs # Android TWA build helper (Bubblewrap / PWABuilder)
│ └── token-gen.mjs # HMAC-SHA256 Bearer token generator
├── src/
│ ├── cli/
│ │ ├── index.ts # CLI argument parser & command router
│ │ ├── index-cmd.ts # `mindomat index` implementation
│ │ ├── ingest.ts # `mindomat ingest` implementation
│ │ ├── init-vault.ts # `mindomat init-vault` implementation
│ │ └── sync.ts # `mindomat sync` implementation
│ ├── templates/
│ │ ├── CLAUDE.md # Agent guide template copied into new vaults
│ │ └── _Schema.md # Wiki schema template copied into 10_Wiki/
│ ├── index.ts # Package exports
│ ├── ingest.ts # Conflict pre-check, Jaccard & TF-IDF cosine similarity
│ ├── llm.ts # MiniMax HTTP client & mock response generator
│ ├── notes-api-server.ts # NotesApi class (used by Vite middleware & tests)
│ ├── vault-path.ts # Vault path resolution & validation
│ └── watcher.ts # Chokidar inbox file watcher
├── tests/ # Vitest unit/integration tests & Playwright E2E specs
├── webapp/
│ ├── public/
│ │ ├── .well-known/assetlinks.json
│ │ ├── icon-192.svg
│ │ ├── icon-512.svg
│ │ ├── manifest.webmanifest
│ │ └── service-worker.js
│ ├── src/
│ │ ├── App.tsx # Main shell, Cytoscape graph, list view, sidebar
│ │ ├── ClusterMap.tsx # Cluster visualization tab
│ │ ├── RadialView.tsx # Radial ego-graph tab
│ │ ├── Editor.tsx # Tiptap + Markdown split preview editor
│ │ ├── EditorWithLoad.tsx
│ │ ├── NewNoteDialog.tsx
│ │ ├── landkarte.ts
│ │ ├── note-loader.ts
│ │ ├── notes-api.ts
│ │ └── sync-queue.ts
│ ├── TWA-BUILD.md # Play Store / TWA packaging guide
│ ├── twa-manifest.json
│ └── vite.config.ts # Vite config with integrated NotesApi middleware
├── .env.example # Environment template
├── Dockerfile # Multi-stage production container (Node 22 + QMD)
├── entrypoint.sh # Container startup (Git sync, index, QMD MCP, server.mjs)
├── package.json
└── server.mjs # Express production server + 5-min auto-sync loop
License
This project's own code and configuration are dedicated to the public domain under CC0 1.0 Universal — see LICENSE.
External dependencies installed via package managers or Docker images retain their respective open-source licenses.