19 KiB
Mind-o-Mat
Lokales Second-Brain-System für Obsidian-kompatible Markdown-Vaults mit deterministischer Indizierung, KI-Wiki-Ingest, QMD-Hybridsuche und PWA-Webapp.
Überblick
Mind-o-Mat ist die zentrale CLI-, API-Server- und Webapp-Codebasis für ein lokales, Git-basiertes Second-Brain-System auf Basis Obsidian-kompatibler Markdown-Vaults. Das System trennt Logik und Oberfläche (dieses Tool-Repository) strikt von Notizen und Daten (einem separaten Vault-Repository wie Mind-o-Mat-Vault) und dient zugleich als Backend für die native Android-App (Mind-o-Mat-App).
Systemarchitektur
┌─────────────────────────────────────────────────────────────┐
│ Mind-o-Mat (Tool) │
│ │
│ ┌───────────┐ ┌──────────┐ ┌──────────┐ ┌────────────┐ │
│ │ CLI │ │ Indexer │ │ Ingest │ │ Webapp │ │
│ │ init- │ │ scan + │ │ LLM + │ │ React + │ │
│ │ vault, │ │ parse │ │ Konfl. │ │ Cytosc. │ │
│ │ index, │ │ + Veral.│ │ + Watch │ │ + Tiptap │ │
│ │ ingest, │ │ + Dupl. │ │ + TFIDF │ │ + PWA │ │
│ │ sync │ │ │ │ │ │ Manifest │ │
│ └─────┬─────┘ └─────┬────┘ └────┬─────┘ └──────┬─────┘ │
│ │ │ │ │ │
└────────┼──────────────┼────────────┼───────────────┼────────┘
│ │ │ │
│ ▼ │ ▼
│ landkarte.json │ Browser / PWA / App
│ │ │ │
│ └─────┬──────┘ │
│ ▼ │
│ 00_Inbox/*.md │
│ │ │
▼ ▼ ▼
┌─────────────────────────────────────────────────────┐
│ Mind-o-Mat-Vault (Daten) │
│ 00_Inbox/ 01_Daily/ 10_Wiki/ 20_Projekte/ ... │
│ 99_System/Konfig.md (Schwellwerte, KI-Konfig) │
└─────────────────────────────────────────────────────┘
│
▼ git push (mindomat sync)
┌────────────┐
│ Gitea │
│ Remote │
└────────────┘
Die 5 Bausteine
| # | Baustein | Zweck | KI drin? | Ort |
|---|---|---|---|---|
| 1 | Vault | Markdown-Dateien, Single Source of Truth | Nein | Separates Vault-Repo |
| 2 | Indexer | Deterministischer Scanner: parst Frontmatter, extrahiert Wikilinks, erkennt Veraltet & Duplikate | Nein | Dieses Tool-Repo |
| 3 | QMD | Lokale Hybridsuche (BM25 + Vektor-Embeddings + Re-Ranking) via @tobilu/qmd |
Lokale Modelle | Im Vault / Container installiert |
| 4 | Wiki (Ingest) | Pflegt kuratierte Wiki-Seiten per LLM mit deterministischer Konflikt-Vorprüfung | Ja (MiniMax-API) | Dieses Tool-Repo |
| 5 | Webapp / PWA | Interaktiver Wissensgraph, Cluster-Karte, Radial-Ansicht, Notizenliste, Tiptap-Editor, Android-TWA | Nein | Dieses Tool-Repo (webapp/) |
Funktionen
- Vault-Initialisierung (
init-vault): Erstellt die 12-Ordner-Struktur (00_Inbox/,01_Daily/,10_Wiki/,20_Projekte/,90_Templates/,99_System/usw.),.gitignore,99_System/Konfig.md,10_Wiki/_Schema.md,CLAUDE.md, zwei Demo-Notizen und initialisiert Git auf dem Branchmaininklusive optionalem Gitea-Remote. - Deterministischer Vault-Indexer (
index):- Parst YAML-Frontmatter (
gray-matter) und klassifiziert Notizen ininbox,daily,wiki,projectoderunknown. - Extrahiert
[[Wikilinks]]und erkennt verwaiste/tote Links. - Erkennt veraltete Notizen (
veraltet) anhand vonaktualisiert/createdgegenveraltet_schwellwert_monate(Standard: 12 Monate; Wiki-Seiten sind ausgenommen). - Erkennt exakte Duplikate per SHA-256-Hash über den Body sowie ähnliche Notizen mittels TF-IDF-Cosinus-Ähnlichkeit (
> 0.15im System-Index). - Schreibt deterministische Ausgaben:
landkarte.json,99_System/Index.mdund10_Wiki/Index.md.
- Parst YAML-Frontmatter (
- KI-Wiki-Ingest (
ingest):- Verarbeitet Notizen aus
00_Inbox/in kuratierte Seiten unter10_Wiki/Seiten/mittels MiniMax Chat Completions (Standard:MiniMax-M3) gemäß10_Wiki/_Schema.md. - Führt vor dem LLM-Aufruf eine deterministische Konflikt-Vorprüfung (
preCheckConflictauf deutsche Verneinungswörter + gemeinsame Begriffe) durch. - Unterstützt
--mock(offline ohne API-Key),--note <Dateiname>,--dry-runsowie--watch/-w(Chokidar-Inbox-Watcher). - Verschiebt verarbeitete Notizen nach
00_Inbox/Verarbeitet/<Datum>/bzw. fehlerhafte Notizen nach00_Inbox/Problemfaelle/inklusive Log-Eintrag in99_System/Logs/.
- Verarbeitet Notizen aus
- Gitea-Synchronisation (
sync):- Arbeitet mit einem Lockfile (
99_System/Skripte/Lock/Sync.lock) und schreibt Tageslogs (99_System/Logs/Sync_YYYY-MM-DD.md). - Staged und committed lokale Änderungen, führt
git pull --rebase --autostashaus und pusht nachorigin main.
- Arbeitet mit einem Lockfile (
- Produktions-Webapp & Notes-API (
server.mjs):- Liefert die mit Vite gebaute React-TypeScript-PWA (
webapp/dist) sowie die REST-Endpunkte (/api/status,/api/notes,/api/notes/:id,/api/capture,/api/sync,/landkarte.json,/note) aus. - Unterstützt optionale HMAC-SHA256-Bearer-Token-Authentifizierung (
<timestamp>.<hmac-sha256-hex>) und CORS-Allowlisting. - Führt alle 5 Minuten automatisch einen Hintergrund-Git-Sync samt Re-Indizierung durch, sofern der gemountete Vault ein Git-Repository ist.
- Im Docker-Container (
entrypoint.sh) wird der Vault gepullt/geklont, initial indiziert, der QMD-MCP-Daemon auf Port8181gestartet und anschließendserver.mjsauf Port5173ausgeführt.
- Liefert die mit Vite gebaute React-TypeScript-PWA (
- Interaktive PWA-Oberfläche (
webapp/):- 5 Ansichten: Force-Directed-Graph (
cytoscapecose-Layout), Notizenliste (mit Live-Filter), Cluster-Karte, Radial-Ansicht und Tiptap-WYSIWYG/Markdown-Split-Editor (@tiptap/react+marked+turndown). - Dialog für „+ Neue Notiz“, Detail-Seitenleiste und PWA-Manifest/Service-Worker (
webapp/public/manifest.webmanifest,service-worker.js) inklusive TWA-Unterstützung (scripts/build-twa.mjs,webapp/TWA-BUILD.md).
- 5 Ansichten: Force-Directed-Graph (
Funktionsweise & Tech-Stack
| Ebene | Technologie | Details |
|---|---|---|
| Laufzeit | Node.js >=22.0.0 (ESM) |
TypeScript 5.6, kompiliert nach dist/ |
| CLI-Binary | bin/mindomat.mjs |
Stellt den Befehl mindomat bereit (init-vault, index, ingest, sync) |
| Backend-Server | Express 4 (server.mjs), gray-matter, chokidar |
Produktions-API & Static-Server; Vite-Middleware in Entwicklung (src/notes-api-server.ts) |
| Frontend (PWA) | React 18, Vite 5, Cytoscape 3.30, Tiptap 3, Marked, Turndown | Gebaut nach webapp/dist/ |
| Hybridsuche | @tobilu/qmd |
BM25 + lokale GGUF-Embeddings & Re-Ranking; MCP-HTTP-Daemon |
| LLM-Anbindung | MiniMax-API (/chat/completions) |
Konfiguriert über 99_System/Konfig.md + MINIMAX_API_KEY |
| Tests & Qualität | Vitest 5, Playwright, Testing Library, ESLint 9, Prettier | Unit-, Integrations- und E2E-Tests in tests/ |
| Container | Multi-Stage Dockerfile (node:22-bookworm-slim) + tini |
Läuft als Non-Root-Benutzer node |
Ports
| Port | Dienst | Beschreibung |
|---|---|---|
5173 |
Webapp & Notes-API | Express-Produktionsserver (server.mjs) und Vite-Dev-Server |
8181 |
QMD-MCP-Daemon | Wird im Docker-Container durch entrypoint.sh gestartet (qmd mcp --http --daemon --host 0.0.0.0 --port 8181) |
Voraussetzungen & Installation
Voraussetzungen
- Node.js
>= 22.0.0und npm - Git (für Vault-Initialisierung und
sync) - Optional für Hybridsuche:
@tobilu/qmd(npm install -g @tobilu/qmd) - Optional für Container-Betrieb: Docker
Lokale Installation
git clone https://git.orfel.de/Jannik/Mind-o-Mat.git
cd Mind-o-Mat
npm install
npm run build
npm link
Frontend-Abhängigkeiten installieren und Webapp bauen:
cd webapp
npm install
npm run build
Vault initialisieren & QMD einrichten (einmalig)
# 1. Komplette Vault-Struktur anlegen (12 Ordner, Konfig, 2 Demo-Notizen, git init)
mindomat init-vault C:\GitHub\Mein-Vault
# 2. Gitea-Remote konfigurieren (falls nicht per --remote übergeben)
cd C:\GitHub\Mein-Vault
git remote add origin https://git.orfel.de/Dein-Name/Mein-Vault.git
git push -u origin main
# 3. QMD-Hybridsuche installieren und einrichten (~2 GB Modell-Download beim ersten 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. Initialen Vault-Index erzeugen
mindomat index
Docker-Deployment
Multi-Stage-Image bauen und starten:
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-dein-key \
-e NOTES_API_TOKEN=dein-hmac-secret \
-v /pfad/zum/vault:/vault \
-v mindomat-qmd-cache:/data \
mindomat
Wenn VAULT_SYNC_TOKEN gesetzt ist und /vault/.git noch nicht existiert, klont entrypoint.sh automatisch https://<VAULT_SYNC_TOKEN>@git.orfel.de/Jannik/Mind-o-Mat-Vault.git nach /vault, führt mindomat index aus, startet qmd mcp auf Port 8181 und anschließend node server.mjs auf Port 5173.
Konfiguration
Kopiere .env.example nach .env (Hinweis: Die CLI liest Umgebungsvariablen direkt aus process.env; in PowerShell per $env:VAR = "..." bzw. in Bash per export VAR=... setzen — Details siehe docs/SECRETS.md).
| Variable | Standard / Beispiel | Beschreibung |
|---|---|---|
MINIMAX_API_KEY |
— | MiniMax-API-Key für Live-ingest (oder der in 99_System/Konfig.md unter ki_api_key_env definierte Name) |
MINDOMAT_VAULT_PATH |
/vault (Docker), C:/GitHub/Mind-o-Mat-Vault (Vite Dev) |
Pfad zum Ziel-Markdown-Vault |
PORT |
5173 |
HTTP-Port für server.mjs |
NOTES_API_TOKEN |
(leer = Auth deaktiviert) | Gemeinsames HMAC-SHA256-Secret für Bearer-Auth der API-Endpunkte |
NOTES_API_ALLOWED_ORIGINS |
(leer = alle Origins) | Kommagetrennte CORS-Whitelist (z. B. https://mindomat.orfel.de) |
VAULT_SYNC_TOKEN |
— | Gitea-Zugriffstoken für entrypoint.sh zum Klonen/Pullen des Vault-Repos |
QMD_CACHE_DIR |
/data (Docker) |
Cache-Verzeichnis für QMD im Container |
QMD_CACHE_PATH |
99_System/Cache |
Optionaler QMD-Cache-Pfad im Vault |
GITEA_REMOTE |
— | Optionale Referenz-URL für das Gitea-Vault-Remote |
Token-Generierung & weiterführende Dokumentation
- API-Bearer-Token (
<timestamp>.<hmac-sha256-hex>) generieren:$env:NOTES_API_TOKEN = "dein-hmac-secret" npm run token-gen docs/SECRETS.md: Umgang mit.env, Gitea-CI-Secrets und optionalerage-Verschlüsselung.docs/BACKUP.md,docs/MIGRATION.md,docs/openapi.yamlundwebapp/TWA-BUILD.md: Backup-Strategien, OpenAPI-Spezifikation und Android-TWA-Paketierung.
Nutzung
CLI-Referenz
mindomat --version # Version anzeigen (0.1.0)
mindomat --help # Hilfe anzeigen
mindomat init-vault <pfad> # Neuen Vault initialisieren
# --remote <url> Gitea-Remote-URL setzen
# --no-commit Nur Struktur anlegen, kein Git-Commit
# --no-interactive Ohne Rückfragen ausführen
# --force Existierenden Vault überschreiben
mindomat index --vault <pfad> # Vault deterministisch indizieren -> landkarte.json + Index.md
# (alternativ MINDOMAT_VAULT_PATH setzen)
mindomat ingest --vault <pfad> # 00_Inbox/*.md -> 10_Wiki/Seiten/*.md verarbeiten
# --mock Simulierte LLM-Antwort ohne API-Key
# --note <datei> Nur eine bestimmte Inbox-Notiz verarbeiten
# --dry-run Vorschau ohne Schreiben/Verschieben
# --watch, -w 00_Inbox/ dauerhaft überwachen
mindomat sync --vault <pfad> # Lokale Änderungen committen, git pull --rebase --autostash, git push origin main
# --message, -m Eigene Commit-Nachricht
# --force Bestehendes Sync.lock ignorieren
Beispiel-Workflow
# 1. Notiz in der Inbox anlegen
echo "[[Kaffee]] schmeckt gut." > C:\GitHub\Mein-Vault\00_Inbox\2026-09-05_Notiz.md
# 2. Ingest: Notiz -> Wiki
mindomat ingest --vault C:\GitHub\Mein-Vault
# 3. Deterministischen Graph-Index aktualisieren
mindomat index --vault C:\GitHub\Mein-Vault
# 4. Webapp im Entwicklungsmodus starten
cd C:\GitHub\Mind-o-Mat\webapp
npm run dev
# Öffnet http://localhost:5173
# 5. Vault nach Gitea synchronisieren
mindomat sync --vault C:\GitHub\Mein-Vault
Produktions-HTTP-API-Endpunkte (server.mjs)
| Methode | Endpunkt | Auth | Beschreibung |
|---|---|---|---|
GET |
/api/status |
Nein | Status-/Verbindungstest (ok, name, version, authRequired) |
GET |
/landkarte.json |
Nein | Liefert landkarte.json aus dem Vault (indiziert bei Bedarf on-the-fly) |
GET |
/note?path=<relPath> |
Nein | Liefert den Markdown-Inhalt { content } einer Notiz |
GET |
/api/notes |
Bearer* | Listet Notiz-IDs und Metadaten aus 00_Inbox, 10_Wiki/Seiten, 01_Daily, 20_Projekte |
GET |
/api/notes/:id |
Bearer* | Liefert vollständigen Inhalt und geparstes Frontmatter einer Notiz |
PUT |
/api/notes/:id |
Bearer* | Speichert Notiz-Inhalt und stößt Re-Indizierung im Hintergrund an |
POST |
/api/capture |
Bearer* | Quick-Capture-Endpunkt (text, title, tags, autoIngest, autoSync, targetFolder) für die Android-App |
POST |
/api/sync |
Bearer* | Führt mindomat sync --vault <VAULT_PATH> aus |
*Bearer-Auth wird erzwungen, sobald NOTES_API_TOKEN gesetzt ist (Same-Origin-Browseranfragen von erlaubten Origins werden in server.mjs durchgelassen).
Tests & Qualitätsprüfungen
npm test # Vitest Unit-/Integrationstests ausführen
npm run test:e2e # Playwright E2E-Tests ausführen
npm run lint # ESLint-Prüfung
npm run format:check # Prettier-Formatierungsprüfung
npm run build # TypeScript-CLI/-Core kompilieren
cd webapp && npm run build # Vite-PWA-Bundle bauen
Projektstruktur
Mind-o-Mat/
├── bin/
│ └── mindomat.mjs # Einstiegspunkt für die CLI
├── docs/
│ ├── BACKUP.md # 3-Ebenen-Backup- & Recovery-Anleitung
│ ├── MIGRATION.md # Migrationshinweise
│ ├── SECRETS.md # Geheimnisverwaltung (.env, CI, age)
│ └── openapi.yaml # OpenAPI-3.1-Spezifikation für die Notes-API
├── scripts/
│ ├── build-twa.mjs # Android-TWA-Build-Helfer (Bubblewrap / PWABuilder)
│ └── token-gen.mjs # HMAC-SHA256-Bearer-Token-Generator
├── src/
│ ├── cli/
│ │ ├── index.ts # CLI-Argument-Parser & Befehls-Router
│ │ ├── index-cmd.ts # Implementierung von `mindomat index`
│ │ ├── ingest.ts # Implementierung von `mindomat ingest`
│ │ ├── init-vault.ts # Implementierung von `mindomat init-vault`
│ │ └── sync.ts # Implementierung von `mindomat sync`
│ ├── templates/
│ │ ├── CLAUDE.md # Agenten-Leitfaden-Vorlage für neue Vaults
│ │ └── _Schema.md # Wiki-Schema-Vorlage für 10_Wiki/
│ ├── index.ts # Paket-Exporte
│ ├── ingest.ts # Konflikt-Vorprüfung, Jaccard- & TF-IDF-Cosinus-Ähnlichkeit
│ ├── llm.ts # MiniMax-HTTP-Client & Mock-Generator
│ ├── notes-api-server.ts # NotesApi-Klasse (für Vite-Middleware & Tests)
│ ├── vault-path.ts # Vault-Pfadauflösung & Validierung
│ └── watcher.ts # Chokidar-Inbox-Watcher
├── tests/ # Vitest-Tests & Playwright-E2E-Specs
├── webapp/
│ ├── public/
│ │ ├── .well-known/assetlinks.json
│ │ ├── icon-192.svg
│ │ ├── icon-512.svg
│ │ ├── manifest.webmanifest
│ │ └── service-worker.js
│ ├── src/
│ │ ├── App.tsx # Hauptoberfläche, Cytoscape-Graph, Liste, Sidebar
│ │ ├── ClusterMap.tsx # Cluster-Karten-Ansicht
│ │ ├── RadialView.tsx # Radiale Ego-Graph-Ansicht
│ │ ├── Editor.tsx # Tiptap + Markdown-Split-Vorschau-Editor
│ │ ├── EditorWithLoad.tsx
│ │ ├── NewNoteDialog.tsx
│ │ ├── landkarte.ts
│ │ ├── note-loader.ts
│ │ ├── notes-api.ts
│ │ └── sync-queue.ts
│ ├── TWA-BUILD.md # Play-Store- / TWA-Build-Anleitung
│ ├── twa-manifest.json
│ └── vite.config.ts # Vite-Konfiguration mit NotesApi-Middleware
├── .env.example # Vorlage für Umgebungsvariablen
├── Dockerfile # Multi-Stage-Container (Node 22 + QMD)
├── entrypoint.sh # Container-Startskript (Git-Sync, Index, QMD MCP, server.mjs)
├── package.json
└── server.mjs # Express-Produktionsserver + 5-Minuten-Auto-Sync
Lizenz
Der eigene Quellcode und die Konfiguration dieses Projekts stehen unter CC0 1.0 Universal (Public Domain) — Details in LICENSE.
Externe Abhängigkeiten, die über Paketmanager oder Docker-Images installiert werden, behalten ihre jeweiligen eigenen Open-Source-Lizenzen.