Vault Cortex

Vault Cortex ist ein eigenständiger MCP-Server, der jedem KI-Agenten Hybrid-Suche, Aufgabenverwaltung, strukturiertes Gedächtnis und Lese-/Schreibzugriff auf deinen Obsidian-Vault bietet. Keine Plugins, kein laufendes Obsidian, keine separate Brücke. Ein Docker-Container, dein Vault-Ordner, eine vollständige Tool-Suite plus geführte Prompts. Bereitstellung auf einem VPS mit Obsidian Sync – derselbe Vault ist dann von deinem Telefon, von claude.ai oder jedem entfernten MCP-Client aus erreichbar, gesichert mit OAuth 2.1.

Inhalt — Was du bekommst · Schnellstart · So funktioniert es · Hybrid-Suche · Gedächtnis · Aufgaben · Dateien · Tools · Prompts · Eigenschaften · Konfiguration · Tägliche Notizen · Datenintegrität · Authentifizierung · Bereitstellung · Community-Bereitstellungen

Was du bekommst

• Entfernter Zugriff — funktioniert von deinem Telefon, einem entfernten Server oder jedem MCP-Client über OAuth 2.1. Bereitstellung auf einem VPS mit Obsidian Sync für Zugriff von überall.

• Ohne Plugins — Obsidian muss nicht laufen. Der Server arbeitet direkt mit den .md-Dateien auf der Festplatte. Headless-Sync hält den Vault aktuell.

• Hybrid-Suche — FTS5-Keyword-Abgleich + vektorielle semantische Ähnlichkeit über RRF-Fusion, verfeinert durch Cross-Encoder-Reranking für absichtsintensive Abfragen. Keywords bleiben präzise bei exakten Begriffen und Fachjargon; Vektoren finden Notizen, selbst wenn deine Worte von denen im Vault abweichen.

• Strukturiertes Gedächtnis — datierte, nur-anhängbare Einträge wachsen zu einer persönlichen Wissensebene heran, automatisch initialisiert für KI-Personalisierung. Themenabruf beantwortet „Was denke ich über X?“ mit der aktuellen Einschätzung und der datierten Historie dahinter — inklusive Entwicklung.

• Aufgaben — Kanban-bewusste Aufgabenabfragen und -aktualisierungen: Sortierung nach Status, Datum oder Priorität, dann Abschließen, Neupriorisieren oder Verschieben von Aufgaben zwischen Spalten in einem einzigen Aufruf. Parst sowohl Tasks-Plugin-Emoji als auch Dataview-Inline-Feld-Formate.

• Link-Graph — Backlinks, ausgehende Links und Erkennung verwaister Notizen im gesamten Vault

• Dateien — liest auch die Nicht-Markdown-Dateien des Vaults: Bilder kommen als echte Bilder an (bei Bedarf verkleinert), PDFs als strukturierter Text oder gerenderte Seiten, Canvases als lesbare Gliederungen, Datendateien als Text

• Obsidian-nativ — versteht Frontmatter, Wikilinks, Tags, Überschriften und tägliche Notizen

• Geführte Workflows — eingebaute Prompts für Vault-Gesundheit, Gedächtnis-Review und tägliche Abgleichung — jedes Mal aus Live-Vault-Daten zusammengestellt

Getestet während einer 15-tägigen Reise durch Europa. 30+ Sitzungen vom Telefon, 216 Tool-Aufrufe, kein Laptop-Zugriff nötig. Schreibvorgänge in einer Sitzung waren sofort in der nächsten verfügbar, über Städte und Tage hinweg.

Related MCP server: Vault MCP Server (mschuchard)

Schnellstart

Lokal (2 Minuten — Docker + dein Vault-Ordner)

Voraussetzungen: Docker (oder eine Docker-kompatible Laufzeit, z. B. OrbStack, Colima, Podman), Node.js >= 20.12 (nur für die CLI — der Server selbst läuft in Docker) und ein Obsidian-Vault (oder ein beliebiger Ordner mit .md-Dateien).

npx vault-cortex@latest init

Das war's — die CLI fragt nach deinem Vault-Pfad, generiert das Auth-Token und die Konfigurationsdateien, startet den Server und gibt die Verbindungsdetails für deinen MCP-Client aus (CLI-Referenz →).

Mit der CLI eingerichtet? Sie verwaltet den Server von nun an — configure, upgrade, start, restart, logs, down (CLI-Referenz →).

Mit Compose eingerichtet? Bleib auch für Updates bei Compose (docker compose pull && docker compose up -d) — CLI und Compose verwalten den Container unabhängig voneinander.

# 1. Get the quickstart files
curl -O https://raw.githubusercontent.com/aliasunder/vault-cortex/main/deploy/local/docker-compose.yml
curl -O https://raw.githubusercontent.com/aliasunder/vault-cortex/main/deploy/local/.env.example

# 2. Configure
cp .env.example .env
# Edit .env — set MCP_AUTH_TOKEN (openssl rand -hex 32) and VAULT_PATH

# 3. Start
docker compose up

Vollständige lokale Anleitung → (enthält Windows-Einrichtung)

Remote (Zugriff von überall — Docker + Obsidian Sync)

Voraussetzungen: ein VPS mit Docker (oder einer Docker-kompatiblen Laufzeit), ein Obsidian-Sync-Abonnement und Node.js >= 20.12 (nur für die CLI — der Server selbst läuft in Docker).

# On your VPS:
npx vault-cortex@latest init --mode remote

Das war's — die CLI führt durch die öffentliche URL, das Obsidian-Sync-Token (sie kann get-sync-token für dich ausführen) und die Auth-Konfiguration und startet dann den Server (CLI-Referenz →).

Mit der CLI eingerichtet? Sie verwaltet den Server von nun an — configure, upgrade, start, restart, logs, down (CLI-Referenz →).

Mit Compose eingerichtet? Bleib auch für Updates bei Compose (docker compose pull && docker compose up -d) — CLI und Compose verwalten den Container unabhängig voneinander.

# On your VPS:
mkdir -p /opt/vault-cortex && cd /opt/vault-cortex
curl -O https://raw.githubusercontent.com/aliasunder/vault-cortex/main/deploy/remote/docker-compose.yml
curl -O https://raw.githubusercontent.com/aliasunder/vault-cortex/main/deploy/remote/.env.example
cp .env.example .env
# Edit .env — set MCP_AUTH_TOKEN, PUBLIC_URL, OBSIDIAN_AUTH_TOKEN, VAULT_NAME
docker compose up -d

Vollständige Remote-Anleitung →

Verbinde deinen MCP-Client

Füge die Server-URL in einem beliebigen MCP-Client hinzu — Claude Code, Claude Desktop, Cursor, OpenCode oder einem anderen. OAuth-Clients öffnen eine Zustimmungsseite in deinem Browser — genehmige mit deinem Token, und der Client übernimmt die Token-Erneuerung von da an. Clients ohne OAuth (MCP Inspector, Skripte) senden das Token direkt als Authorization: Bearer-Header.

Claude Code:

claude mcp add --scope user --transport http vault-cortex http://localhost:8000/mcp   # local (or <PUBLIC_URL>/mcp)

--scope user registriert den Server für jedes Projekt; lasse es weg, um es nur auf das aktuelle Verzeichnis zu beschränken.

Der Dialog „Benutzerdefinierten Connector hinzufügen“ akzeptiert nur https-URLs. Mit einer https-PUBLIC_URL fügst du sie direkt im Connector-Dialog hinzu; für einen localhost-Server registrierst du sie stattdessen in claude_desktop_config.json über die mcp-remote-stdio-Brücke:

{
  "mcpServers": {
    "vault-cortex": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "http://localhost:8000/mcp",
        "--header",
        "Authorization: Bearer <your MCP_AUTH_TOKEN>"
      ]
    }
  }
}

claude.ai (Web und Mobil) verbindet sich nur mit dem Remote-Setup — seine Connectors werden serverseitig abgerufen und können localhost nie erreichen.

„Remote-MCP-Server“ bezieht sich auf den Verbindungstyp (HTTP) — im lokalen Setup läuft der Server weiterhin vollständig auf deinem Rechner.

Siehe Authentifizierung für beide Methoden und Token-Laufzeiten.

So funktioniert es

Alles läuft in einem einzigen Docker-Container und arbeitet direkt mit den .md-Dateien auf der Festplatte:

• Dein Vault bleibt die Quelle der Wahrheit — der Server liest und schreibt dieselben einfachen Markdown-Dateien wie deine Obsidian-Apps.

• Suche ist abgeleitete Daten — ein Datei-Watcher hält den Index (Keywords + Vektoren) aktuell, während sich Notizen ändern, und er kann jederzeit aus deinen Notizen neu aufgebaut werden.

• Das Remote-Image fügt eine Sync-Schleife hinzu — ein gebündelter Obsidian-Sync-Dienst hält den Vault des Containers mit jedem Gerät aktuell: Bearbeite eine Notiz auf deinem Telefon und sie ist wenige Augenblicke später durchsuchbar; ein Agent schreibt eine Notiz und sie erscheint in Obsidian.

graph LR
    subgraph container ["One Docker container"]
        Sync["sync service<br/>(remote image)"]
        Vault[("/vault<br/>.md files — source of truth")]
        Index[("search index<br/>keywords + vectors")]
        Server["MCP server"]
        Sync <-->|read/write| Vault
        Vault -->|file watcher| Index
        Server <-->|read/write| Vault
        Server -->|query| Index
    end
    Obsidian["Your Obsidian apps<br/>(phone, laptop)"] <-->|Obsidian Sync| Sync
    Client["Any MCP client<br/>(Claude, Cursor, claude.ai)"] -->|OAuth 2.1 / Bearer| Server

Siehe ARCHITECTURE.md für das vollständige Design, Auth-Flussdiagramme und die Komponentenaufschlüsselung.

Hybrid-Suche

Nur-Keyword-Suche versagt, wenn dein Wortschatz nicht mit dem des Vaults übereinstimmt — „Ziele“ findet keine Notiz über „Targets“, „Kollegen“ bringt deine „Referenzen“-Datei nicht zum Vorschein. In Tests mit einem echten Vault lieferten 30 % der natürlichsprachlichen Abfragen mit reinen Keywords null oder tangentiale Ergebnisse. Die Hybrid-Suche eliminierte diese Fehltreffer — Vektoren überbrücken die Vokabellücke, und der Reranker rettet absichtsintensive Abfragen, bei denen keines der beiden Signale für sich allein stark ist.

Die Hybrid-Suche kombiniert drei Ranking-Signale über Reciprocal Rank Fusion:

• Keywords (FTS5) bleiben präzise bei exakten Begriffen, Fachjargon und Eigenschaftswerten

• Vektoren (sqlite-vec) überbrücken die Vokabellücke, indem sie nach Bedeutung abgleichen

• Reranker (Cross-Encoder) verfeinert die Reihenfolge, indem er jedes Abfrage-Dokument-Paar gemeinsam bewertet — rettet absichtsintensive Abfragen, bei denen Keywords und Vektoren beide danebenliegen

Alle Modelle laufen lokal (~45 MB gesamt, keine externe API). Setze EMBEDDING_ENABLED=false für reine Keyword-Suche oder RERANK_MODE=none, um das Reranking für geringere Latenz zu überspringen.

Siehe ARCHITECTURE.md → Hybrid-Suche für Modelldetails, Mischungsgewichte und die vollständige Pipeline-Aufschlüsselung.

Gedächtnis

Eine Gedächtnisebene, die nur wächst, ist nur dann nützlich, wenn Agenten die richtigen Einträge abrufen können, ohne alles in den Kontext zu kippen. Sobald du Hunderte von datierten Einträgen über mehrere Dateien verteilt hast — Präferenzen, Prinzipien, Kommunikationsstil, laufende Verpflichtungen — verschwendet das Lesen ganzer Dateien Kontext für irrelevantes Material und begräbt das Signal. Das Gedächtnissystem ist auf gezielten Abruf ausgelegt: Agenten sammeln im Laufe der Zeit Wissen an und rufen genau das ab, was für die jeweilige Aufgabe relevant ist.

Die Ebene ist ein Ordner mit einfachen Markdown-Dateien (Standard: About Me/), die datierte Einträge unter Themenüberschriften enthalten — beim ersten Start automatisch mit Starter-Templates erstellt, von Agenten über vault_update_memory erweitert. Drei Eigenschaften machen es funktionsfähig:

• Append-only — Einträge werden nie überschrieben; Korrekturen kommen als neue datierte Einträge hinzu. Die Ebene wird zu einer persönlichen Wissensbasis, die deinen aktuellen Stand und die Entwicklung dahinter festhält

• Themenabruf — vault_memory_recall ruft alle relevanten Einträge über alle Speicherdateien hinweg auf einmal ab, sowohl nach Stichworten als auch semantisch abgeglichen, älteste zuerst. Frag „Was denke ich über X?" und erhalte die aktuelle Einschätzung plus die datierte Historie, wie sie sich entwickelt hat — ohne ganze Dateien lesen oder raten zu müssen, welche Datei was enthält

• Wächst ohne Qualitätsverlust — Die Begrenzung der Ergebnisse (max_results) verwirft die am wenigsten relevanten Einträge, nie einen Ausschnitt der Zeitleiste. Eine Speicherebene mit 500 Einträgen bedient eine gezielte Abfrage genauso gut wie eine mit 50

Dateien, die beschreiben, was aktuell ist, und nicht, was wahr war (Routinen, aktive Verpflichtungen), können in den Frontmatter entry-policy: living deklarieren — ihre abgelaufenen Einträge sind dann entfernbar statt dauerhaft, sodass das Bild des aktuellen Stands präzise bleibt.

Die gesamte Ebene ist optional — setze MEMORY_ENABLED=false, um die Speicher-Tools auszublenden und die automatische Ordnererstellung ganz zu überspringen.

Siehe ARCHITECTURE.md → Memory für die Abruf-Pipeline, das Indexierungsmodell, die automatische Initialisierung und das Opt-out-Verhalten, sowie templates/memory für das Dateiformat, die entry-policy-Konvention und Startvorlagen.

Tasks

Aufgabenmetadaten liegen in einfachem Markdown vor — verstreut über Dateien, kodiert in Emoji-Kennzeichnungen oder Inline-Feldern, organisiert unter Kanban-Überschriften. Ein Agent, der „Was ist überfällig?" beantworten soll, müsste jede Datei parsen und dein gewähltes Format verstehen; eine Aufgabe auf einem Kanban-Board abzuschließen bedeutet, die Spaltenstruktur des Boards, die Datumssyntax und zu wissen, welche Überschrift die Erledigt-Spalte ist.

Die Aufgabenebene übernimmt das, damit Agenten es nicht tun müssen:

• Finden — filtern nach Status, sechs Datumsfeldern (fällig, geplant, Start, erstellt, erledigt, abgebrochen), Priorität, Ordner oder Kanban-Spalte. Jedes Ergebnis trägt seine Spalte, den Notizpfad, die Überschrift und die Zeilennummer — keine Folgeabfragen nötig, um eine Aufgabe zu lokalisieren

• Aktualisieren — erledigen, neu priorisieren und Aufgaben zwischen Kanban-Spalten verschieben in einem einzigen Aufruf. Das Markieren einer Aufgabe als erledigt erkennt die Erledigt-Spalte automatisch und stempelt das Abschlussdatum; das Rückgängigmachen entfernt das Datum. Alle drei Änderungen können gleichzeitig passieren

• Beide Formate — egal welches Format du verwendest, Tasks plugin Emoji-Kennzeichnungen oder Dataview Inline-Felder, der Server liest beide und schreibt in dem Format, für das dein Tasks-Plugin konfiguriert ist

Siehe ARCHITECTURE.md → Tasks für das Indexierungsmodell, die Datums-Kaskadensortierung und die Kanban-Spaltenerkennung.

Dateien

Deine Notizen betten Screenshots ein, referenzieren Architekturdiagramme und verlinken auf Canvases und Datendateien — aber für einen Agenten, der Markdown liest, ist ![[diagram.png]] nur Text. vault-cortex behandelt Dateien als Teil des Vaults und nicht als Beiwerk darum herum — verlinkt, dimensioniert und lesbar, jede in der Form, die ein Agent tatsächlich nutzen kann:

• Bilder — das Bild selbst, nicht der Dateiname. Screenshots und Diagramme werden serverseitig verkleinert und neu komprimiert, wenn sie die Grenzen der MCP-Clients überschreiten, sodass auch eine Handy-Sitzung ein 5-MB-Architekturdiagramm ansehen kann

• Canvases — ein Canvas-Board kommt als lesbare Gliederung an: seine Gruppen, der Inhalt jeder Karte in Lesereihenfolge und die Verbindungen zwischen ihnen. Canvas-Inhalte sind volltextdurchsuchbar, und Dateireferenzen auf dem Board erscheinen im Link-Graphen — Backlinks und ausgehende Links funktionieren genau wie Notiz-zu-Notiz-Links. Das exakte JSON-Quellformat ist nur ein Flag entfernt, wenn volle Wiedergabetreue zählt

• PDFs — Text wird mit Überschriftenhierarchie, Codeblöcken und Hyperlinks extrahiert; PDF-Inhalte sind volltextdurchsuchbar neben deinen Notizen. Setze raw: true, um Seiten stattdessen als Bilder zu rendern, die Layout, Diagramme und Tabellen zeigen, die Textextraktion nicht bewahren kann — gescannte und reine Bild-PDFs funktionieren in diesem Modus

• Text- und Datendateien — TXT, SVG, JSON, XML, CSV, YAML, Logs und Bases-Dateien werden exakt so zurückgegeben, wie sie sind; die ersten 100 KB Inhalt sind volltextdurchsuchbar. Große Datendateien und Logs können zeilenweise gelesen werden, wobei jede Seite angibt, wo du dich befindest und wie viel von der Datei noch übrig ist

• Durchsuchen — liste die Dateien jedes sichtbaren Ordners mit Zählungen pro Erweiterung und Dateigrößen auf; Dateien, auf die eine Notiz verlinkt, melden ihre Größe ebenfalls im Link-Graphen

Setze FILE_TOOLS_ENABLED=false, um die Datei-Tools auszublenden — nützlich, wenn dein Remote-Vault ohne Anhänge synchronisiert.

Siehe ARCHITECTURE.md → Files für die Bild-Pipeline und das Dispatch-Modell.

Tools

Prompts

Tools sind modellgesteuert — der Assistent ruft sie auf. Prompts sind Workflows, die du auslöst. Jeder fragt den Suchindex, den Link-Graphen und die Speicherebene zum Aufrufzeitpunkt ab und setzt die Ergebnisse dann mit geführten Anweisungen zusammen — so startet die Sitzung im tatsächlichen Zustand deines Vaults verankert, nicht in Annahmen.

Prompts passen sich deiner Konfiguration an (MEMORY_DIR, Einstellungen für tägliche Notizen) und funktionieren für jeden Vault sofort. Übergib max_chars, um eingebettete Inhalte zu begrenzen, wenn dein Client Nutzlastgrenzen hat.

Client-Unterstützung: Prompts funktionieren in Claude Desktop (Chat und Cowork — über das +-Menü unter Ihrem Connector), Claude Code (Slash-Befehle) und OpenCode. Die Unterstützung in anderen Clients (Cursor, Windsurf) variiert — siehe die MCP-Clients-Matrix für den aktuellen Stand.

Eigenschaften

Vault Cortex indexiert jede Eigenschaft in Ihren Notizen, aber fünf erhalten eine hervorgehobene Behandlung — dedizierte Spalten für schnelles Filtern und Top-Level-Felder in jedem Such- und Erkundungsergebnis:

Alle anderen Eigenschaften bleiben vollständig abfragbar — verwenden Sie vault_search mit filters.properties für kombinierte Text- und Metadaten-Abfragen oder vault_search_by_property für reine Metadaten-Suchen. Mit vault_list_property_keys und vault_list_property_values können Sie ermitteln, welche Eigenschaften in Ihrem Vault vorhanden sind.

Dies sind Konventionen, keine Anforderungen — Vault Cortex funktioniert mit jedem Eigenschafts-Schema. Hervorgehobene Eigenschaften bieten Ihnen lediglich umfangreichere Filterung und sauberere Ergebnisse von Haus aus.

Führende Callouts erhalten dieselbe Behandlung. Wenn der erste Inhalt einer Notiz ein Obsidian-Callout ist (> [!type]) — entweder direkt nach dem Frontmatter oder direkt nach der Titelüberschrift — wird er indexiert und neben jedem Erkundungsergebnis angezeigt (bei vault_search fragen Sie mit include_leading_callout danach). Das macht Notizen selbstbeschreibend: Ein Agent, der Ergebnisse durchsucht, kann sehen, wofür jede Notiz gedacht ist, bevor er entscheidet, welche er lesen möchte. Die Speichervorlagen verwenden > [!info] Scope of this file-Callouts für diesen Zweck, und jede Notiz in Ihrem Vault kann dasselbe Muster verwenden.

Konfiguration

Alle Einstellungen sind Umgebungsvariablen mit sinnvollen Standardwerten. Remote-Bereitstellungen haben zusätzliche Einstellungen, die unten nicht aufgeführt sind (SYNC_CONFIGS, SYNC_MODE, …) — siehe die Konfigurationstabelle des Remote-Leitfadens.

• Intelligente Standardwerte — das Setzen von MEMORY_DIR oder DAILY_NOTES_FOLDER aktualisiert automatisch die Standardwerte für PROTECTED_PATHS und ORPHAN_EXCLUDE_FOLDERS; wenn DAILY_NOTES_FOLDER nicht gesetzt ist, übernimmt Daily Notes diesen Platz. Ein Ordner für tägliche Notizen, der nur in daily-notes.json konfiguriert ist, wird nicht übernommen — fügen Sie ihn selbst zu PROTECTED_PATHS hinzu. Sie setzen diese nur explizit, wenn Sie eine vollständig benutzerdefinierte Liste wünschen.

• MEMORY_ENABLED=false deaktiviert die Memory-Ebene vollständig — Memory-Tools werden ausgeblendet und der Memory-Ordner wird nicht automatisch erstellt.

• FILE_TOOLS_ENABLED=false blendet Datei-Tools vollständig aus — nützlich, wenn Obsidian Sync die Synchronisierung von Anhängen deaktiviert hat und keine Dateien auf der Festplatte vorhanden sind.

• READONLY_MODE=true blendet jedes Tool aus, das in den Vault schreibt, und überspringt die automatische Erstellung des Memory-Ordners — verbundene Clients können lesen und suchen, aber nie bearbeiten.

• DISABLED_TOOLS blendet genau die Tools aus, die Sie benennen — für eine feinere Kontrolle als die obigen Schalter, z. B. Schreiben aktiviert lassen, aber vault_delete_note und vault_move_note entfernen. Verfügbarkeitsbasierte Querverweise in Tool-Beschreibungen und Prompts passen sich automatisch an.

Siehe templates/memory/ für Beispiele von Memory-Dateien und die Design-Philosophie datierter Einträge.

Tägliche Notizen

vault_get_daily_note und der Daily-Review-Prompt finden Ihre täglichen Notizen anhand des Ordners und des Datumsformats für Dateinamen, die in Obsidian konfiguriert sind und aus .obsidian/daily-notes.json Ihres Vaults gelesen werden:

• Lokaler Modus liest die Datei direkt aus Ihrem per Bind-Mount eingebundenen Vault — nichts einzurichten.

• Remote-Modus erhält sie über die Vault-Konfigurationssynchronisierung von Obsidian Sync. Der Server zieht sie standardmäßig (die Einstellung SYNC_CONFIGS in .env), aber Sie müssen wahrscheinlich die Push-Seite aktivieren: Obsidian-Einstellungen → Sync → Vault-Konfigurationssynchronisierung, pro Gerät. Details: der Abschnitt „Daily notes“ im Remote-Leitfaden.

Wenn die Datei nicht verfügbar ist — oder Sie das Periodic-Notes-Plugin verwenden, dessen Einstellungen sie nicht widerspiegelt — setzen Sie DAILY_NOTES_FOLDER (einen beliebigen Vault-relativen Pfad: Journal, Planner/Daily) und DAILY_NOTES_FORMAT (gleiche Tokens wie die Datumsformat-Einstellung von Obsidian: YYYY-MM-DD-dddd, YYYY/MM/DD, MMM D, YYYY, …). Sie können eines oder beide setzen — ein gesetzter Wert hat immer Vorrang vor der Konfigurationsdatei. Ohne eine der beiden Quellen fällt der Server auf Daily Notes und YYYY-MM-DD zurück.

Hinweis: Einige Datumsformat-Tokens werden nicht unterstützt — Ordinalzahlen (Do, Mo, DDDo, wo), dd (2-Buchstaben-Wochentag), d (Wochentagsnummer), e, k/kk und die lokalisierten Formate (L–LLLL, LT, LTS). Der Server kann die Dateinamen, die Obsidian mit diesen Tokens erzeugt, nicht nachbilden, sodass er die Notizen niemals finden könnte. Wenn Ihr Format eines davon verwendet, gibt vault_get_daily_note eine klare Fehlermeldung zurück — ändern Sie das Format in Obsidian oder setzen Sie DAILY_NOTES_FORMAT auf eine unterstützte Alternative.

Datenintegrität

Vault Cortex schreibt in persönliche Notizen — die Dateisicherheitsschicht ist darauf ausgelegt, Beschädigungen zu verhindern, nicht nur Fehler.

• Atomare Schreibvorgänge — jeder Dateischreibvorgang wird zuerst in eine temporäre Datei geschrieben und dann umbenannt. Leser sehen niemals eine unvollständige oder 0-Byte-Notiz. Exklusive Erstellungen verwenden link() (POSIX-No-Clobber), um das TOCTOU-Fenster bei Notizverschiebungen zu schließen.

• Pro-Datei-Mutex — gleichzeitige MCP-Toolaufrufe werden pro Datei serialisiert oder schlagen schnell fehl. Verschiebungen sperren Quelle, Ziel und jede Backlink-Quelle als eine Einheit.

• Pfad-Traversal blockiert — resolveSafePath() löst jeden Pfad auf und prüft ihn anschließend per Präfix. Das Löschen geschützter Pfade wird nach der Normalisierung verweigert. Memory-Dateinamen lehnen Trennzeichen an der Grenze ab.

• Versteckte Pfade sind tabu — Dateien und Ordner, die mit einem Punkt beginnen (.obsidian/, .trash/), erscheinen nie in Auflistungen oder der Suche, und jeder Toolaufruf, der direkt auf einen solchen zielt, wird abgelehnt — konsistent mit Obsidian. Plugin-Konfigurationen und deren API-Schlüssel bleiben unerreichbar.

• Injektionsschutz — Suchanfragen werden parametrisiert und FTS5-saniert; Prompt-Inhalte werden in XML-Datenmarker mit Escaping von schließenden Tags eingebettet, um Tag-Breakout-Injektion zu verhindern.

• Container-Härtung — Nicht-Root-Benutzer, Init als PID 1, keine Paketmanager im Laufzeit-Image, per Digest gepinntes Basis-Image, kontrolliertes Herunterfahren.

Siehe ARCHITECTURE.md → Datenintegrität für Details zu den Mechanismen und SECURITY.md → Laufzeit-Härtung für das vollständige Inventar der Angriffsfläche.

Authentifizierung

Für einen Server mit Lese-/Schreibzugriff auf persönliche Notizen ist Authentifizierung keine Option. Vault Cortex implementiert die vollständige OAuth 2.1-Spezifikation, einschließlich PKCE und Refresh-Token-Rotation. Die AWS- (SST-) Bereitstellung bietet Defense-in-Depth: Anfragen werden auf zwei unabhängigen Ebenen validiert (API-Gateway-Lambda-Authorizer + Express-Middleware). Laut BlueRocks MCP-Sicherheitsanalyse aus 2026 implementieren nur 8,5 % der MCP-Server OAuth; 41 % haben überhaupt keine Authentifizierung.

Zwei Methoden:

OAuth verwendet dynamische Client-Registrierung — keine Client-ID/kein Client-Secret erforderlich. In Ihrem Browser öffnet sich eine Zustimmungsseite; geben Sie Ihren MCP_AUTH_TOKEN ein, um zu genehmigen. Refresh-Tokens haben eine gleitende Ablaufzeit von 60 Tagen (tägliche Nutzer müssen sich nie erneut authentifizieren).

Siehe ARCHITECTURE.md → Authentifizierung für das vollständige Ablaufdiagramm.

Bereitstellungsoptionen

Lokale Ausführung auf Ihrem Rechner. Remote-Bereitstellungen laufen auf einem VPS — Ihr Vault ist auch bei geschlossenem Laptop erreichbar.

Der AWS-Pfad enthält CI/CD-Workflows, die für dieses Repository erstellt wurden — Fork-Betreiber müssen vor der Bereitstellung ihre eigenen Anmeldeinformationen und ihre eigene Stage konfigurieren.

Alle drei Pfade verwenden dasselbe Image, ghcr.io/aliasunder/vault-cortex — :latest ist der MCP-Server allein (lokal), :remote bündelt Obsidian Sync im selben Container unter s6-overlay-Aufsicht (remote und AWS). Ein Container bedeutet, dass jede OCI-Laufzeitumgebung funktioniert: docker run, Podman, nerdctl — Docker Compose ist optional.

Auch auf Docker Hub: Dieselben Images werden nach aliasunder/vault-cortex gespiegelt. GHCR ist die primäre Quelle; die Hub-Tags sind identisch.

Kosten: Ein Remote-Setup benötigt einen VPS und 4 $ USD/Monat für Obsidian Sync. Eine Instanz mit 2 GiB bewältigt die semantische Suche für einen typischen Vault problemlos; 4 GiB bieten mehr Reserven für gleichzeitige Suche und größere Vaults. Wenn Sie die semantische Suche ganz weglassen, können Sie noch kleiner gehen. Nur lokal ist kostenlos. Die Referenz-AWS-Bereitstellung kostet insgesamt etwa 17–29 $/Monat.

Community-Bereitstellungen

Von der Community erstellte und gepflegte Bereitstellungsvorlagen — hier nicht getestet, und sie können hinter den Releases zurückbleiben.

• vault-cortex-aca — Bicep-Vorlage für Azure Container Apps von @flytzen. Führt das :remote-Image hinter dem Ingress von Container Apps mit kostenlosem verwaltetem HTTPS aus; der Speicher ist bewusst ephemer, wobei Obsidian Sync als Single Source of Truth dient.

Haben Sie eine Bereitstellung für eine andere Plattform erstellt? Öffnen Sie einen PR, um sie hier hinzuzufügen.

Entwicklung

# Run locally with hot reload
PUBLIC_URL=http://localhost:8000 MCP_AUTH_TOKEN=local-dev-token VAULT_PATH=~/Vault npm run dev:mcp

# Tests
npm test

# Full check suite
npm run prettier:check && npm run lint && npm test && npm run build

npm test umfasst Integrationstests, die einen echten Server starten und jedes Tool und jeden Prompt über HTTP aufrufen — sie prüfen die Durchsetzung der Authentifizierung, konfigurationsgesteuerte Tool-Oberflächen, die Integrität von Schreibvorgängen (jeder Schreibvorgang wird zurückgelesen) und die Ablehnung des Starts bei Fehlkonfiguration. Siehe SECURITY.md für die sicherheitsrelevante Abdeckung.

MCP Inspector — interaktive Browser-Oberfläche zum Testen von Tools:

# Start server (terminal 1), then:
npx @modelcontextprotocol/inspector
# Enter http://localhost:8000/mcp as URL, local-dev-token as Bearer token

Siehe CONTRIBUTING.md für die vollständige Entwicklungsumgebung.

Ergänzung: obsidian-vault-Skill

Der MCP-Server funktioniert eigenständig mit jedem Client. Für Agenten, die Skills unterstützen (Claude Code, Cursor, Windsurf, Cline und über 70 weitere), erweitert der obsidian-vault-Skill das Wissen um Obsidian-spezifisches Markdown — Frontmatter-Konventionen, Callout-Syntax und plugin-spezifische Formate wie Dataview, Tasks und Kanban.

npx skills add aliasunder/agent-skills --skill obsidian-vault

Skill-Quellcode →

Roadmap

Danksagungen

Obsidian Sync wird von obsidian-headless unterstützt — der Containerisierungsansatz ist inspiriert von @Belphemur und dessen obsidian-headless-sync-docker. Das s6-overlay-Supervision-Gerüst des :remote-Images wurde aus dem gepflegten Fork dieses Projekts übernommen und befindet sich nun in diesem Repository.

Die Pipeline für hybride Suche greift auf Muster aus @tobis qmd zurück — RRF-Fusion mit Rang-Boni, positionsbewusste Score-Überblendung für Cross-Encoder-Reranking, Content-Hash-Gating und überschriftenbewusstes Chunking.

Mitwirken

Siehe CONTRIBUTING.md für die Entwicklungsumgebung, Code-Konventionen und PR-Richtlinien.

Lizenz

MIT

Das :remote-Image bündelt obsidian-headless (die ob-CLI), das proprietär ist — seine package.json deklariert "license": "UNLICENSED" (© Dynalist Inc. / Obsidian). Es wird zur Build-Zeit aus dem öffentlichen npm installiert; die MIT-Lizenz hier deckt es nicht ab, und für die Nutzung ist ein aktives Obsidian-Sync-Abonnement erforderlich. Das :latest-Image (lokal) enthält keine proprietären Komponenten.

Sicherheit

Melden Sie Schwachstellen vertraulich — siehe SECURITY.md.