Files
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

19 KiB

Mind-o-Mat Logo

Mind-o-Mat

Lokales Second-Brain-System für Obsidian-kompatible Markdown-Vaults mit deterministischer Indizierung, KI-Wiki-Ingest, QMD-Hybridsuche und PWA-Webapp.

🇬🇧 English · 🇩🇪 Deutsch


Ü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 Branch main inklusive optionalem Gitea-Remote.
  • Deterministischer Vault-Indexer (index):
    • Parst YAML-Frontmatter (gray-matter) und klassifiziert Notizen in inbox, daily, wiki, project oder unknown.
    • Extrahiert [[Wikilinks]] und erkennt verwaiste/tote Links.
    • Erkennt veraltete Notizen (veraltet) anhand von aktualisiert/created gegen veraltet_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.15 im System-Index).
    • Schreibt deterministische Ausgaben: landkarte.json, 99_System/Index.md und 10_Wiki/Index.md.
  • KI-Wiki-Ingest (ingest):
    • Verarbeitet Notizen aus 00_Inbox/ in kuratierte Seiten unter 10_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 (preCheckConflict auf deutsche Verneinungswörter + gemeinsame Begriffe) durch.
    • Unterstützt --mock (offline ohne API-Key), --note <Dateiname>, --dry-run sowie --watch / -w (Chokidar-Inbox-Watcher).
    • Verschiebt verarbeitete Notizen nach 00_Inbox/Verarbeitet/<Datum>/ bzw. fehlerhafte Notizen nach 00_Inbox/Problemfaelle/ inklusive Log-Eintrag in 99_System/Logs/.
  • 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 --autostash aus und pusht nach origin main.
  • 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 Port 8181 gestartet und anschließend server.mjs auf Port 5173 ausgeführt.
  • Interaktive PWA-Oberfläche (webapp/):
    • 5 Ansichten: Force-Directed-Graph (cytoscape cose-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).

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.0 und 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 optionaler age-Verschlüsselung.
  • docs/BACKUP.md, docs/MIGRATION.md, docs/openapi.yaml und webapp/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.