Jannik d0a46b7b65
CI / test (push) Canceled after 0s
CI / webapp (push) Canceled after 0s
chore(license): standardize on CC0-1.0 and third-party notices
2026-11-18 01:18:49 +01:00
2026-09-05 14:51:03 +02:00
2026-09-06 12:51:12 +02:00
2026-11-18 00:51:38 +01:00
2026-09-05 18:51:10 +02:00
2026-09-05 18:51:10 +02:00
2026-09-05 18:51:10 +02:00

Mind-o-Mat Logo

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.

🇬🇧 English · 🇩🇪 Deutsch


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 on main with optional Gitea remote setup.
  • Deterministic Vault Indexer (index):
    • Parses YAML frontmatter (gray-matter) and classifies notes into inbox, daily, wiki, project, or unknown.
    • Extracts [[wikilinks]] and detects orphaned/dead links.
    • Detects stale notes (veraltet) based on aktualisiert/created against veraltet_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.15 in system index).
    • Generates deterministic outputs: landkarte.json, 99_System/Index.md, and 10_Wiki/Index.md.
  • AI Wiki Ingestion (ingest):
    • Processes notes from 00_Inbox/ into curated pages under 10_Wiki/Seiten/ using MiniMax Chat Completions (MiniMax-M3 by default) following 10_Wiki/_Schema.md.
    • Runs deterministic conflict pre-checking (preCheckConflict checking 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 to 00_Inbox/Problemfaelle/ with logs in 99_System/Logs/.
  • 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 to origin main.
  • 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 port 8181, and serves the webapp/API on port 5173.
  • Interactive PWA Frontend (webapp/):
    • 5 Views: Force-directed Graph (cytoscape cose layout), 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).

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.0 and 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.md for .env, Gitea CI secrets, and optional age encryption workflows.
  • See docs/BACKUP.md, docs/MIGRATION.md, docs/openapi.yaml, and webapp/TWA-BUILD.md for 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.

S
Description
Lokales Second-Brain-System (CLI, Indexer, KI-Ingest, Express-API & React/Cytoscape-Webapp) für Markdown-Vaults.
Readme CC0-1.0
22 MiB
0 Stars 1 Watchers 0 Forks
Languages
TypeScript 85.8%
JavaScript 12%
Shell 1.1%
Dockerfile 0.8%
HTML 0.3%