Obsidian MCP + Hybride Retrieval: Referenz für 2026

Obsidian ist keine Notiz-App. Es ist ein lokal-first ausgerichtetes, plaintext-basiertes, graphstrukturiertes Markdown-Korpus, das zu einem KI-Kontextreservoir wird, wenn Sie Retrieval-Infrastruktur hinzufügen. 16.894 Dateien. 49.746 Chunks. Abfragen in 23 ms. Null API-Aufrufe. Eine 83-MB-SQLite-Datei. Dieser Leitfaden behandelt das gesamte System: von der Architektur des Obsidian-Tresors über hybrides Retrieval bis zur MCP-Integration und zu operativen Workflows.

Wichtigste Erkenntnisse

Context Engineering, nicht Notizenmachen. Der Wert eines Obsidian-Vaults für AI liegt nicht in den Notizen selbst, sondern in der Retrieval-Schicht, die sie abfragbar macht. Ein Vault mit 16.000 Dateien ohne Retrieval ist eine Datenbank, in die nur geschrieben wird. Ein Vault mit 200 Dateien, hybrider Suche und MCP-Integration ist eine AI-Wissensdatenbank. Die Retrieval-Infrastruktur ist das Produkt. Die Notizen sind das Rohmaterial.

Hybrides Retrieval schlägt reine Keyword- oder reine semantische Suche. BM25 findet exakte Identifikatoren und Funktionsnamen. Die Vektorsuche findet Synonyme und konzeptuelle Übereinstimmungen über unterschiedliche Terminologie hinweg. Reciprocal Rank Fusion (RRF) führt beide zusammen, ohne eine Score-Kalibrierung zu benötigen. Keine der beiden Methoden deckt allein beide Fehlermodi ab. Forschung zum Passage Ranking in MS MARCO bestätigt dieses Muster: Hybrides Retrieval übertrifft durchgängig jede Methode für sich.³ Der Deep Dive zum hybriden Retriever behandelt die RRF-Mathematik, durchgerechnete Beispiele mit realen Zahlen, die Analyse von Fehlermodi und einen interaktiven Fusion-Rechner.

MCP ermöglicht AI-Tools direkten Vault-Zugriff. Model Context Protocol (MCP)-Server stellen den Retriever als Tool bereit, das Claude Code, Codex CLI, Cursor und andere AI-Tools direkt aufrufen können. Der Agent fragt den Vault ab, erhält nach Rang sortierte Ergebnisse mit Quellenangaben und nutzt den Kontext, ohne ganze Dateien laden zu müssen. Der MCP-Server ist ein schlanker Wrapper um die Retrieval-Engine.

Local-first bedeutet keine API-Kosten und vollständige Privatsphäre. Der gesamte Stack läuft auf einem einzelnen Rechner: SQLite für die Speicherung, Model2Vec für embeddings, FTS5 für die Keyword-Suche und sqlite-vec für Vektor-KNN. Keine Cloud-Dienste, keine API-Aufrufe, keine Netzwerkabhängigkeit. Persönliche Notizen verlassen den Rechner nie. Die vollständige Neueinbettung von 49.746 Chunks würde bei den API-Preisen von OpenAI ungefähr 0,30 $ kosten, doch die eigentlichen Kosten sind Latenz, Datenschutzrisiken und die Netzwerkabhängigkeit eines Systems, das offline funktionieren sollte.⁴

Inkrementelle Indexierung hält das System in unter 10 Sekunden aktuell. Ein Vergleich der Dateiänderungszeiten erkennt Änderungen. Nur geänderte Dateien werden erneut in Chunks aufgeteilt und mit embeddings versehen. Eine vollständige Neuindexierung dauert auf Apple-M-Series-Hardware etwa vier Minuten. Inkrementelle Aktualisierungen für die Bearbeitungen eines typischen Tages dauern weniger als zehn Sekunden. Das System bleibt ohne manuelle Eingriffe aktuell.

Die Architektur skaliert von 200 auf über 20.000 Notizen. Dasselbe dreischichtige Design (Aufnahme, Retrieval, Integration) funktioniert bei jeder Vault-Größe. Beginnen Sie mit einer reinen BM25-Suche für einen kleinen Vault. Ergänzen Sie eine Vektorsuche, wenn Keyword-Kollisionen zum Problem werden. Fügen Sie RRF-Fusion hinzu, wenn Sie sowohl exakte als auch semantische Treffer benötigen. Jede Schicht ist unabhängig nützlich und kann unabhängig entfernt werden.

So verwenden Sie diesen Leitfaden

Dieser Leitfaden behandelt das vollständige System. Wo Sie beginnen, hängt von Ihrer Ausgangslage ab:

Abschnitte mit der Kennzeichnung Contract enthalten Implementierungsdetails, Konfigurationsblöcke und Fehlermodi. Abschnitte mit der Kennzeichnung Narrative konzentrieren sich auf Konzepte, Architekturentscheidungen und die Begründung hinter Designentscheidungen. Abschnitte mit der Kennzeichnung Recipe bieten Schritt-für-Schritt-Workflows.

Warum Obsidian für AI-Infrastruktur

Die These dieses Leitfadens: Obsidian-Vaults sind die beste Grundlage für persönliche AI-Wissensdatenbanken, weil sie local-first, plaintext-basiert, graphstrukturiert sind und Benutzer jede Schicht des Stacks kontrollieren.

Was Obsidian AI bietet, was Alternativen nicht bieten

Plaintext-Markdown-Dateien. Jede Notiz ist eine .md-Datei in Ihrem Dateisystem. Kein proprietäres Format, kein Datenbankexport, kein API zum Lesen der Inhalte erforderlich. Jedes Tool, das Dateien liest, kann Ihren Vault lesen. grep, ripgrep, Python’s pathlib, SQLite FTS5 — sie alle arbeiten direkt mit den Quelldateien. Wenn Sie ein Retrieval-System bauen, indexieren Sie Dateien, keine API-Antworten. Der Index ist stets mit der Quelle konsistent, weil die Quelle das Dateisystem ist.

Local-first-Architektur. Der Vault befindet sich auf Ihrem Rechner. Kein Server, keine Abhängigkeit von Cloud-Synchronisierung, keine API-Rate Limits, keine Nutzungsbedingungen, die regeln, wie Sie Ihre eigenen Inhalte verarbeiten. Sie können Ihre Notizen ohne externen Dienst einbetten, indexieren, in Chunks aufteilen und durchsuchen. Für AI-Infrastruktur ist das wichtig, weil die Retrieval-Pipeline so schnell läuft, wie Ihre Festplatte es zulässt, und nicht so schnell, wie ein API-Endpoint antwortet. Ebenso wichtig ist es für die Privatsphäre: Persönliche Notizen mit Zugangsdaten, Gesundheitsdaten, Finanzinformationen und privaten Reflexionen verlassen Ihren Rechner nie.

Graphstruktur durch wiki-links. Die [[wiki-link]]-Syntax von Obsidian erstellt einen gerichteten Graphen über Notizen hinweg. Eine Notiz über die Implementierung von OAuth verweist auf Notizen über Token-Rotation, Sitzungsverwaltung und API-Sicherheit. Die Graphstruktur kodiert von Menschen kuratierte Beziehungen zwischen Konzepten. Vektor-embeddings erfassen semantische Ähnlichkeit, doch wiki-links erfassen absichtliche Verbindungen, die der Autor beim Nachdenken über das Thema hergestellt hat. Der Graph ist ein Signal, das embeddings nicht nachbilden können.

Plugin-Ökosystem. Obsidian verfügt über 2.500+ Community-Plugins (die Zahl überschritt im März 2026 die Marke von 2.500, nach 1.800+ Mitte 2025). Dataview fragt Ihren Vault wie eine Datenbank ab. Templater erzeugt Notizen aus Vorlagen mit JavaScript-Logik. Die Git-Integration synchronisiert Ihren Vault mit einem Repository. Linter erzwingt einheitliche Formatierung. Das Bases-Core-Plugin (eingeführt in v1.9.10) ergänzt datenbankähnliche Ansichten — Tabellen, Galerien, Kalender und Kanban-Boards — über Vault-Dateien, wobei frontmatter-Eigenschaften als Felder verwendet und als .base-Dateien gespeichert werden.¹⁵ Diese Plugins ergänzen den Vault um Struktur, ohne das zugrunde liegende Plaintext-Format zu verändern. Das Retrieval-System indexiert die Ausgabe dieser Plugins, nicht die Plugins selbst.

Über 5 Millionen Benutzer. Obsidian hat eine große aktive Community, die Vorlagen, Workflows, Plugins und Dokumentation erstellt. Wenn Sie auf ein Problem bei der Vault-Organisation oder Plugin-Konfiguration stoßen, hat wahrscheinlich bereits jemand eine Lösung dokumentiert. Die Community entwickelt auch Obsidian-nahe Tools: MCP-Server, Indexierungsskripte, Publishing-Pipelines und API-Wrapper.

Was ein Dateisystem allein Ihnen nicht bietet

Ein Verzeichnis mit Markdown-Dateien bietet den Plaintext-Vorteil, es fehlen jedoch drei Dinge, die Obsidian ergänzt:

1. Bidirektionale Links. Obsidian verfolgt backlinks automatisch. Wenn Sie von Notiz A auf Notiz B verlinken, zeigt Notiz B an, dass Notiz A auf sie verweist. Das Graph-Panel visualisiert Verbindungscluster. Diese bidirektionale Kenntnis sind Metadaten, die ein reines Dateisystem nicht bereitstellt.

2. Live-Vorschau mit Plugin-Rendering. Dataview-Abfragen, Mermaid-Diagramme und Callout-Blöcke werden in Echtzeit gerendert. Das Schreiberlebnis ist reichhaltiger als in einem Texteditor, während das Speicherformat plaintext bleibt. Sie schreiben und organisieren in einer umfangreichen Umgebung; das Retrieval-System indexiert das rohe Markdown.

3. Community-Infrastruktur. Plugin-Entdeckung, Theme-Marktplatz, Sync-Service (optional), Publish-Service (optional) und ein Dokumentationsökosystem. Sie können jede einzelne Funktion mit eigenständigen Tools nachbilden, aber Obsidian bündelt sie zu einem kohärenten Workflow.

Was Obsidian NICHT macht (und was Sie bauen)

Obsidian enthält keine Retrieval-Infrastruktur. Es bietet eine einfache Suche (Volltext, Dateiname, Tag), jedoch keine Embedding-Pipeline, keine Vektorsuche, kein Fusion-Ranking, keinen MCP-Server, keine Zugangsdatenfilterung, keine Chunking-Strategie und keine Integrations-Hooks für externe AI-Tools. Dieser Leitfaden behandelt die Infrastruktur, die Sie auf Obsidian aufbauen. Der Vault ist die Grundlage. Die Retrieval-Pipeline, der MCP-Server und die Integrations-Hooks sind die Infrastruktur.

Die hier beschriebene Architektur ist markdown-first, nicht Obsidian-exklusiv. Wenn Sie Logseq, Foam, Dendron oder ein einfaches Verzeichnis mit Markdown-Dateien verwenden, funktioniert die Retrieval-Pipeline identisch. Der Chunker liest .md-Dateien. Der Embedder verarbeitet Textzeichenfolgen. Der Indexer schreibt nach SQLite. Keine dieser Komponenten hängt von Obsidian-spezifischen Funktionen ab. Der Beitrag von Obsidian besteht in der Schreib- und Organisationsumgebung, die die Markdown-Dateien erzeugt, welche der Retriever indexiert.

Obsidian MCP einrichten

Model Context Protocol (MCP) ist die Standardschnittstelle, die Claude Code, Codex CLI, Cursor und anderen AI-Tools direkten Zugriff auf einen Obsidian-Vault ermöglicht. In diesem Abschnitt verbinden Sie einen Vault innerhalb von fünf Minuten mit einem AI-Tool. Sie installieren Obsidian, erstellen einen Vault, installieren einen MCP-Server und führen Ihre erste Abfrage aus. Der Schnellstart nutzt einen Community-MCP-Server für sofortige Ergebnisse. In späteren Abschnitten geht es um den Aufbau einer benutzerdefinierten Retrieval-Pipeline für den Produktionseinsatz.

Voraussetzungen

• macOS, Linux oder Windows
• Node.js 18+ (für den MCP-Server)
• Obsidian 1.12+ (für die CLI-Integration; 1.13.7 ist die aktuelle öffentliche Desktop-Version – Stable und Beta wurden zusammengeführt, die 1.13-Reihe verließ Catalyst am 30. Juli 2026; frühere Versionen funktionieren für reine MCP-Setups)
• Claude Code, Codex CLI oder Cursor installiert

Schritt 1: Einen Vault erstellen

Laden Sie Obsidian von obsidian.md herunter und erstellen Sie einen neuen Vault. Wählen Sie einen Speicherort, den Sie nicht vergessen werden — der MCP-Server benötigt den absoluten Pfad.

# Example vault location
~/Documents/knowledge-base/

Fügen Sie einige Notizen hinzu, damit der Retriever etwas zum Verarbeiten hat. Schon 10-20 Notizen reichen aus, um Ergebnisse zu sehen. Jede Notiz sollte eine .md-Datei mit einem aussagekräftigen Titel und mindestens einem Absatz Inhalt sein.

Schritt 2: Einen MCP-Server installieren

Mehrere Community-MCP-Server ermöglichen sofortigen Vault-Zugriff. Das Ökosystem ist im Zeitraum 2025-2026 erheblich gewachsen. Ein bemerkenswerter Server ist MCPVault (npm @bitbonsai/mcpvault, Repository bitbonsai/mcpvault), inzwischen bei v0.15.0 (am 14. August 2026 anhand von npm verifiziert) — ein eigenständiges Projekt gegenüber MarkusPfundstein/mcp-obsidian, nicht dessen Umbenennung. Version v0.11.0 (März 2026) ergänzte list_all_tags zum Durchsuchen von frontmatter und Hashtags mit Anzahl, verbesserte die Behandlung von Ordnern mit Punkten und fügte Unterstützung für .base/.canvas hinzu. Die drei Patches vom 23. Juli 2026 sollten Sie installieren: v0.12.3 ergänzt ein wiki_link-Tool, das die Formen [[Document Name]], [[Name|Display]], in Tabellen maskierte [[Name\|Display]] und #fragment auflöst und Notizinhalte zusammen mit dem aufgelösten Pfad sowie möglichen mehrdeutigen Alternativen zurückgibt — die Retrieval-Grundfunktion, mit der ein Agent dem eigenen Linkgraphen eines Vaults folgen kann, statt erneut danach zu suchen — und schließt .trash/ über den Standardpfadfilter von jedem Tool aus; v0.12.4 erweitert wiki_link um pfadqualifizierte Links wie [[folder/Note]]; v0.12.2 verhindert, dass patch_note Einfügungen mit $-Ersetzungsmustern beschädigt, und normalisiert Pfade, die versehentlich das Vault-Präfix enthalten. Gegen die Denylist eingeschränkter Verzeichnisse des Pfadfilters wurden zwei Hinweise mittlerer Schwere (GHSA-9c83-rr99-vfwj und GHSA-j99q-93c9-h869) veröffentlicht; beide wurden lange vor der 0.12-Reihe in 0.11.4 bzw. 0.11.5 behoben, daher sind alle 0.12.x-Versionen davon nicht betroffen.¹³

Umstellung im April 2026 — Obsidian CLI als bevorzugte Brücke: Obsidian 1.12.0 führte das erstklassige CLI ein, und das öffentliche Installationsprogramm 1.12.7 (23. März 2026) bündelte die eigenständige Binärdatei + TUI + Socket-Datei-Verbesserungen, die Terminal-Workflows leichter installier- und ausführbar machten.¹⁶ Die 1.13-Reihe erreichte den öffentlichen Kanal am 30. Juli 2026 als 1.13.4 — ein Release zu Einstellungen, Bildern und URI-Sicherheit ohne neue AI- oder Automatisierungsfunktionen über die CLI-Oberfläche von 1.12.x hinaus (in der Changelog-Zeile sehen Sie, was sich tatsächlich ändert).²⁵²⁶ Community-Tools migrieren aktiv vom Local-REST-API-Plugin (das mcp-obsidian nutzte) zur CLI-basierten Integration, weil sie schneller und stabiler ist. Das Repository MarkusPfundstein/mcp-obsidian wird weiterhin gepflegt — Commits bis Mai 2026 ergänzten Tools wie search_by_tag und get_frontmatter — veröffentlicht jedoch keine getaggten Releases (installieren Sie von einem angehefteten Commit). Es bleibt Local-REST-API-basiert; für neue Setups ist die CLI-Brücke im Allgemeinen schneller und stabiler, daher sollten Sie sie oder die unten aufgeführten neueren Community-Alternativen bevorzugen.²⁰ Das empfohlene Setup finden Sie später in diesem Leitfaden im Abschnitt „Obsidian CLI für AI-Workflows“.

Für den Schnellstart ist ein dateibasierter Server, der .md-Dateien direkt liest, die einfachste Option. Achten Sie auf die npm-Namenskollision: Der dateibasierte Server heißt bei npm obsidian-mcp (StevenStavrakis); npm obsidian-mcp-server ist cyanheads’ REST-API-gestützter Server, der das Local-REST-API-Plugin und einen API-Schlüssel benötigt — eine häufige Verwechslung, durch die Leser bei einem Server landen, der nicht starten kann:

npm install -g obsidian-mcp

Schritt 3: Ihr AI-Tool konfigurieren

Claude Code — registrieren Sie den Server mit claude mcp add (Claude Code speichert MCP-Server im Benutzerbereich in ~/.claude.json oder in der .mcp.json eines Projekts — nicht in ~/.claude/settings.json, die einen mcpServers-Block stillschweigend ignoriert):

# User scope (all your projects)
claude mcp add obsidian -s user -- npx -y obsidian-mcp@2 serve --vault notes=/absolute/path/to/your/vault

# Or project scope, shared with the repo (writes .mcp.json)
claude mcp add obsidian -s project -- npx -y obsidian-mcp@2 serve --vault notes=/absolute/path/to/your/vault

Codex CLI — fügen Sie Folgendes zu ~/.codex/config.toml hinzu:

[mcp_servers.obsidian]
command = "npx"
args = ["-y", "obsidian-mcp@2", "serve", "--vault", "notes=/absolute/path/to/your/vault"]

Cursor — fügen Sie Folgendes zu .cursor/mcp.json hinzu:

{
  "mcpServers": {
    "obsidian": {
      "command": "npx",
      "args": ["-y", "obsidian-mcp@2", "serve", "--vault", "notes=/absolute/path/to/your/vault"]
    }
  }
}

Schritt 4: Ihre erste Abfrage ausführen

Öffnen Sie Ihr AI-Tool und stellen Sie eine Frage, die Ihre Vault-Notizen beantworten können:

Search my Obsidian vault for notes about [topic you wrote about]

Das AI-Tool ruft den MCP-Server auf, der Ihren Vault durchsucht und passende Inhalte zurückgibt. Sie sollten Ergebnisse mit Dateipfaden und relevanten Auszügen sehen.

Was Claude nach der Verbindung kann

Die genauen Tool-Namen unterscheiden sich je nach Server, aber die zentralen Funktionen sind implementationsübergreifend konsistent:

In der Praxis beantwortet Claude Fragen aus Ihren Notizen mit Quellenangaben, ruft frühere Entscheidungen und Referenzmaterial in Coding-Sitzungen ab und erkundet die Vault-Struktur, ohne ganze Dateien in den Kontext zu laden. Einige Community-Server stellen auch Schreiboperationen bereit (Erstellen, Anhängen sowie Tag- und frontmatter-Verwaltung); der später in diesem Leitfaden entwickelte benutzerdefinierte Server ist bewusst schreibgeschützt, während die Notizerstellung stattdessen über Hooks erfolgt.

Vertiefungen: MCP-Serverarchitektur für Tool- und Berechtigungsdesign, Claude Code-Integration für Hooks und das Brückenmuster, Codex CLI-Integration und Cursor und andere Tools für weitere Agenten.

Was Sie gerade erstellt haben

Sie haben über ein Standardprotokoll eine lokale Wissensbasis mit einem AI-Tool verbunden. Der MCP-Server liest Ihre Vault-Dateien, führt eine grundlegende Suche aus und gibt Ergebnisse zurück. Dies ist die minimal funktionsfähige Version.

Was Ihnen dieser Schnellstart NICHT bietet: - Hybrid Retrieval (BM25 + Vektorsuche + RRF-Fusion) - Embedding-basierte semantische Suche - Credential-Filterung - Inkrementelle Indexierung - Hook-basierte automatische Kontexteinfügung

Der Rest dieses Leitfadens behandelt den Aufbau jeder dieser Funktionen. Der Schnellstart beweist das Konzept. Die vollständige Pipeline liefert Retrieval in Produktionsqualität.

Obsidian CLI für AI-Workflows

Obsidian 1.12 (Februar 2026) führte eine integrierte Command Line Interface ein, die eine neue Integrationsfläche für AI-Workflows eröffnet; sie ist weiterhin bis 1.13.7 aktuell (die 1.13-Reihe erreichte den öffentlichen Kanal am 30. Juli 2026; seitdem kamen keine neuen CLI-Funktionen hinzu).¹⁶²⁵²⁶ Die CLI fungiert als Fernbedienung für die Obsidian-GUI — Obsidian muss ausgeführt werden (oder startet beim ersten Befehl automatisch). Aktivieren Sie sie unter Einstellungen > Allgemein > Command line interface.

Warum die CLI für die AI-Infrastruktur wichtig ist

Die CLI bietet programmatischen Zugriff auf Obsidian-native Vorgänge, die zuvor die GUI oder API-Plugins erforderten. Für AI-Workflows sind diese Funktionen besonders wichtig:

• Suche aus Skripten und Hooks. obsidian search "query" und obsidian search:context "query" führen Vault-Suchen aus jedem Shell-Skript, Hook oder jeder Automatisierungspipeline aus. Die Variante search:context gibt passende Zeilen mit umgebendem Kontext zurück, was sich eignet, um Ergebnisse in AI-Prompts einzuspeisen.
• Automatisierung täglicher Notizen. obsidian daily öffnet oder erstellt die heutige tägliche Notiz. In Kombination mit Shell-Skripting ermöglicht dies automatisierte tägliche Briefing-Workflows — ein Hook kann AI-generierte Zusammenfassungen an die tägliche Notiz anhängen.
• Vorlagenbasierte Notizerstellung. obsidian template list und obsidian template create erzeugen Notizen aus Templater- oder Core-Vorlagen und ermöglichen AI-Agenten, strukturierte Vault-Einträge zu erstellen, ohne Markdown-Dateien direkt zu schreiben.
• Eigenschaftsverwaltung. obsidian property set und obsidian property get lesen und schreiben frontmatter-Eigenschaften und ermöglichen Metadatenaktualisierungen aus Skripten, ohne YAML parsen zu müssen.
• Plugin-Steuerung. obsidian plugin enable/disable/list verwaltet Plugins programmatisch und ist nützlich, um Indexierungs-Plugins während Batch-Vorgängen umzuschalten.
• Aufgabenverwaltung. obsidian task list/add/complete bietet strukturierten Zugriff auf Aufgaben und ist nützlich für AI-Agenten, die Arbeitselemente im Vault verwalten.

CLI gegenüber MCP für den AI-Zugriff

Die CLI und MCP-Server erfüllen unterschiedliche, sich ergänzende statt konkurrierende Rollen:

Empfehlung: Verwenden Sie die CLI für die Intake-Automatisierung (Notizen erstellen, Eigenschaften verwalten, Obsidian-native Suche ausführen) und MCP für Retrieval (hybride Suche mit embeddings). Ein UserPromptSubmit-Hook kann obsidian search:context als schnellen Vorab-Check aufrufen, bevor das aufwendigere hybride Retrieval ausgeführt wird (auf Tools beschränkte Hook-Ereignisse können nichts einschleusen — ihr stdout erreicht das Modell nie).

Beispiel: CLI-gestützter Intake-Hook

#!/bin/bash
# Hook: append today's signals to daily note via CLI
DATE=$(date +%Y-%m-%d)
SUMMARY="$1"
obsidian daily  # ensure daily note exists
obsidian file append "Daily Notes/${DATE}.md" "## AI Summary\n${SUMMARY}"

Obsidian-Agent-Plugins

Eine wachsende Kategorie von Obsidian-Plugins bettet AI-Coding-Agenten direkt in die Vault-UI ein und bietet damit eine Alternative zur Konfiguration externer MCP-Server. Diese Plugins führen den AI-Agenten in der Obsidian-Seitenleiste aus, statt ihn über ein externes Tool zu verbinden.

Claudian

Claudian bettet Claude Code als AI-Kollaborateur in den Vault ein. Das Vault-Verzeichnis wird zum Arbeitsverzeichnis von Claude und verleiht ihm vollständige agentische Fähigkeiten: Dateien lesen und schreiben, suchen, Bash-Befehle ausführen und mehrstufige Workflows.¹⁷

Wichtige Funktionen für die AI-Infrastruktur: - Kontextbezogene Prompts. Hängt die fokussierte Notiz automatisch an, unterstützt @notename-Dateierwähnungen, tag-basierte Ausschlüsse und die Auswahl im Editor als Kontext. - Vision-Unterstützung. Analysieren Sie Bilder per Drag-and-Drop, Einfügen oder Dateipfad — nützlich für die Verarbeitung von Screenshots und Diagrammen, die im Vault erfasst wurden. - Slash-Befehle. Erstellen Sie wiederverwendbare Prompt-Vorlagen, die über /command ausgelöst werden und standardisierte Vault-Vorgänge ermöglichen. - Berechtigungsmodi. YOLO- (automatisch genehmigen), Safe- (jede Aktion genehmigen) und Plan-Modi (nur Planung) mit einer Sicherheitsblockliste und Beschränkung auf den Vault.

Agent Client

Agent Client vereint Claude Code, Codex CLI und Gemini CLI über das Agent Client Protocol (ACP) in einer einheitlichen Obsidian-Seitenleiste.¹⁸

Wichtige Funktionen: - Wechsel zwischen mehreren Agenten. Chatten Sie mit Claude Code, Codex oder Gemini CLI im selben Panel und wechseln Sie bei Bedarf zwischen den Agenten. - Notizerwähnungen. Verwenden Sie @notename, um Notizinhalte in Prompts einzubeziehen — ähnlich wie bei Claudian, aber agentenunabhängig. - Shell-Ausführung. Führen Sie Terminalbefehle direkt im Chat aus — Build-Skripte, git-Befehle oder beliebige Terminalvorgänge, ohne die Unterhaltung verlassen zu müssen. - Aktionsgenehmigung. Granulare Kontrolle über Datei-Lesezugriffe, Bearbeitungen und Befehlsausführungen.

Wann Agent-Plugins statt externer MCP verwendet werden sollten

Empfehlung: Verwenden Sie Agent-Plugins für Vault-zentrierte Workflows (Notizen schreiben, organisieren und zusammenfassen). Verwenden Sie externe MCP-Server für Entwicklungsworkflows, bei denen der AI-Agent die vollständige Retrieval-Pipeline und Zugriff auf Codebasen außerhalb des Vault benötigt. Beide Ansätze können nebeneinander bestehen — führen Sie Claudian innerhalb von Obsidian für Notizarbeit und Claude Code mit MCP extern für die Entwicklung aus.

Entscheidungsrahmen: Obsidian vs. Alternativen

Nicht jeder Anwendungsfall braucht Obsidian. Dieser Abschnitt zeigt, wann Obsidian die richtige Grundlage ist, wann es überdimensioniert ist und wann etwas anderes besser passt.

Entscheidungsbaum

START: What is your primary content type?
│
├─ Structured data (tables, records, schemas)
│  → Use a database. SQLite, PostgreSQL, or a spreadsheet.
│  → Obsidian is for prose, not tabular data.
│
├─ Ephemeral context (current project, temporary notes)
│  → Use CLAUDE.md / AGENTS.md in the project repo.
│  → These travel with the code and reset per project.
│
├─ Team wiki (shared documentation, onboarding)
│  → Evaluate Notion, Confluence, or a shared git repo.
│  → Obsidian vaults are personal-first. Team sync is possible
│    but not native.
│
└─ Growing personal knowledge corpus
   │
   ├─ < 50 notes
   │  → A folder of markdown files + grep is sufficient.
   │  → Obsidian adds value mainly through the link graph,
   │    which needs density to be useful.
   │
   ├─ 50 - 500 notes
   │  → Obsidian adds value. Wiki-links create a navigable graph.
   │  → BM25-only search (FTS5) is sufficient at this scale.
   │  → Skip vector search and RRF until keyword collisions appear.
   │
   ├─ 500 - 5,000 notes
   │  → Full hybrid retrieval becomes valuable. Keyword collisions
   │    increase. Semantic search catches queries that BM25 misses.
   │  → Add vector search + RRF fusion at this scale.
   │
   └─ 5,000+ notes
      → Full pipeline is essential. BM25-only returns too much noise.
      → Credential filtering becomes critical (more notes = more
        accidentally pasted secrets).
      → Incremental indexing matters (full reindex takes minutes).
      → MCP integration pays dividends on every AI interaction.

Vergleichsmatrix

Wann Obsidian überdimensioniert ist

• Kontext für ein einzelnes Projekt. Wenn die AI nur Kontext zur aktuellen Codebasis braucht, legen Sie ihn in CLAUDE.md, AGENTS.md oder in projektbezogener Dokumentation ab. Diese Dateien bleiben beim Repo und werden automatisch geladen.
• Strukturierte Daten. Wenn der Inhalt aus Tabellen, Datensätzen oder Schemata besteht, verwenden Sie eine Datenbank. Obsidian-Notizen sind primär für Fließtext gedacht. Dataview kann frontmatter-Felder abfragen, aber eine echte Datenbank verarbeitet strukturierte Abfragen besser.
• Temporäre Recherche. Wenn die Notizen nach Projektende verworfen werden, ist ein Arbeitsordner mit Markdown-Dateien einfacher. Bauen Sie keine Retrieval-Infrastruktur für kurzlebige Inhalte auf.

Wann Obsidian die richtige Wahl ist

• Wissen, das sich über Monate oder Jahre ansammelt. Der Wert wächst mit dem Korpus. Ein Vault mit 200 Notizen, der sechs Monate lang täglich abgefragt wird, liefert mehr Wert als ein Vault mit 5.000 Notizen, der nur einmal abgefragt wird.
• Mehrere Domänen in einem Korpus. Ein Vault mit Notizen zu Programmierung, Architektur, Sicherheit, Design und persönlichen Projekten profitiert von domänenübergreifendem Retrieval, das ein projektspezifisches CLAUDE.md nicht bieten kann.
• Datenschutzsensible Inhalte. Local-first bedeutet, dass die Retrieval-Pipeline niemals Inhalte an externe Dienste sendet. Der Vault enthält alles, was Sie dort ablegen, einschließlich Inhalten, die Sie nicht in einen Cloud-Dienst hochladen würden.

Mentales Modell: Drei Ebenen

Das System besteht aus drei Ebenen, die unabhängig voneinander funktionieren, sich kombiniert aber gegenseitig verstärken. Jede Ebene hat einen anderen Zuständigkeitsbereich und einen anderen Fehlermodus.

┌─────────────────────────────────────────────────────┐
│                 INTEGRATION LAYER                     │
│  MCP servers, hooks, skills, context injection        │
│  Concern: delivering context to AI tools              │
│  Failure: wrong context, too much context, stale      │
└──────────────────────┬──────────────────────────────┘
                       │ query + ranked results
┌──────────────────────┴──────────────────────────────┐
│                  RETRIEVAL LAYER                      │
│  BM25, vector KNN, RRF fusion, token budget           │
│  Concern: finding the right content for any query     │
│  Failure: wrong ranking, missed results, slow queries │
└──────────────────────┬──────────────────────────────┘
                       │ chunked, embedded, indexed
┌──────────────────────┴──────────────────────────────┐
│                   INTAKE LAYER                        │
│  Note creation, signal triage, vault organization     │
│  Concern: what enters the vault and how it's stored   │
│  Failure: noise, duplicates, missing structure        │
└─────────────────────────────────────────────────────┘

Intake bestimmt, was in den Vault gelangt. Ohne Kuratierung sammelt der Vault Rauschen an: Screenshots von Tweets, kopierte Artikel ohne Annotation, halb fertige Gedanken ohne Kontext. Die Intake-Ebene ist für die Qualitätskontrolle beim Eintrittspunkt verantwortlich. Eine Scoring-Pipeline, Tagging-Konvention oder ein manueller Review-Prozess - jeder Mechanismus, der sicherstellt, dass der Vault Inhalte enthält, deren Retrieval sich lohnt.

Retrieval macht den Vault abfragbar. Das ist die Engine: Chunking von Notizen in Sucheinheiten, Einbetten von Chunks in den Vektorraum, Indexierung für Keyword- und semantische Suche, Zusammenführen von Ergebnissen mit RRF. Die Retrieval-Ebene verwandelt einen Ordner mit Dateien in eine abfragbare Wissensdatenbank. Ohne diese Ebene kann der Vault manuell durchsucht und über einfache Suche navigiert werden, ist für AI-Tools aber nicht programmatisch zugänglich.

Integration verbindet die Retrieval-Ebene mit AI-Tools. Ein MCP-Server stellt Retrieval als aufrufbares Tool bereit. Hooks fügen Kontext automatisch ein. Skills schreiben neues Wissen zurück in den Vault. Die Integrationsebene ist die Schnittstelle zwischen der Wissensdatenbank und den AI-Agenten, die sie nutzen.

Die Ebenen sind bewusst entkoppelt. Die Intake-Scoring-Pipeline weiß nichts über Embeddings. Der Retriever weiß nichts über Signal-Routing-Regeln. Der MCP-Server weiß nichts darüber, wie Notizen erstellt wurden. Diese Entkopplung bedeutet, dass Sie jede Ebene unabhängig verbessern können. Tauschen Sie das Embedding-Modell aus, ohne die Intake-Pipeline zu ändern. Fügen Sie eine neue MCP-Funktion hinzu, ohne den Retriever anzupassen. Ändern Sie die Signal-Scoring-Heuristiken, ohne den Index anzufassen.

Vault-Architektur für AI Consumption

Ein für AI Retrieval optimierter Vault folgt anderen Konventionen als ein Vault, der für persönliches Browsing optimiert ist. Dieser Abschnitt behandelt Ordnerstruktur, Notizschema, frontmatter-Konventionen und die konkreten Muster, die die Retrieval-Qualität verbessern.

Ordnerstruktur

Verwenden Sie nummerierte Präfixe für Ordner auf oberster Ebene, um eine vorhersehbare Organisationshierarchie zu schaffen. Die Zahlen bedeuten keine Priorität — sie gruppieren verwandte Bereiche und machen die Struktur leichter erfassbar.

vault/
├── 00-inbox/              # Unsorted captures, pending triage
├── 01-projects/           # Active project notes
├── 02-areas/              # Ongoing areas of responsibility
├── 03-resources/          # Reference material by topic
│   ├── programming/
│   ├── security/
│   ├── ai-engineering/
│   ├── design/
│   └── devops/
├── 04-archive/            # Completed projects, old references
├── 05-signals/            # Scored signal intake
│   ├── ai-tooling/
│   ├── security/
│   ├── systems/
│   └── ...12 domain folders
├── 06-daily/              # Daily notes (if used)
├── 07-templates/          # Note templates (excluded from index)
├── 08-attachments/        # Images, PDFs (excluded from index)
├── .obsidian/             # Obsidian config (excluded from index)
└── .indexignore            # Paths to exclude from retrieval index

Ordner, die indexiert werden sollten: Alles, was Markdown-Prosa enthält — Projekte, Bereiche, Ressourcen, Signale, tägliche Notizen.

Ordner, die von der Indexierung ausgeschlossen werden sollten: Templates (sie enthalten Platzhaltervariablen, keine Inhalte), Anhänge (Binärdateien), Obsidian-Konfiguration und jeder Ordner mit sensiblen Inhalten, die Sie nicht im Retrieval-Index haben möchten.

Die Datei .indexignore

Erstellen Sie im Vault-Stammverzeichnis eine .indexignore-Datei, um Pfade explizit vom Retrieval-Index auszuschließen. Die Syntax entspricht .gitignore:

# Obsidian internal
.obsidian/

# Templates contain placeholders, not content
07-templates/

# Binary attachments
08-attachments/

# Personal health/medical notes
02-areas/health/

# Financial records
02-areas/finance/personal/

# Career documents (resumes, salary data)
02-areas/career/private/

Der Indexer liest diese Datei vor dem Scannen und überspringt passende Pfade vollständig. Dateien in ausgeschlossenen Pfaden werden nie gechunkt, nie eingebettet und erscheinen nie in Suchergebnissen.

Notizschema

Jede Notiz sollte YAML frontmatter haben. Der Retriever nutzt frontmatter-Felder für Filterung und Kontextanreicherung:

---
title: "OAuth Token Rotation Patterns"
type: note           # note | signal | project | moc | daily
domain: security     # primary domain for routing
tags:
  - authentication
  - oauth
  - token-management
created: 2026-01-15
updated: 2026-02-28
source: ""           # URL if captured from external source
status: active       # active | archived | draft
---

Erforderliche Felder für Retrieval:

• title — Wird in der Anzeige von Suchergebnissen und als Überschriftenkontext für BM25 verwendet
• type — Ermöglicht nach Typ gefilterte Abfragen („Zeigen Sie mir nur MOCs“ oder „nur Signale“)
• tags — Werden im FTS5-Überschriftenkontext mit einer Gewichtung von 0,3 indexiert und liefern Keyword-Treffer, selbst wenn der Haupttext andere Begriffe verwendet

Optionale, aber wertvolle Felder:

• domain — Ermöglicht auf Bereiche beschränkte Abfragen („Durchsuchen Sie nur Sicherheitsnotizen“)
• source — Quellenangabe für erfasste Inhalte; der Retriever kann Quell-URLs in Ergebnissen einschließen
• status — Ermöglicht, archivierte Notizen oder Entwürfe aus der aktiven Suche auszuschließen

Chunking-Konventionen

Der Retriever teilt Inhalte an H2-Überschriftengrenzen (##) in Chunks auf. Dadurch beeinflusst Ihre Notizstruktur direkt die Granularität des Retrievals:

Gut für Retrieval:

## Token Rotation Strategy

The rotation interval depends on the threat model...

## Implementation with refresh_token

The OAuth 2.0 refresh token flow requires...

## Error Handling: Expired Tokens

When a token expires mid-request...

Drei H2-Abschnitte erzeugen drei unabhängig durchsuchbare Chunks. Jeder Chunk hat genug Kontext, damit das Embedding seine Bedeutung erfassen kann. Eine Abfrage zu „expired token handling“ trifft gezielt den dritten Chunk.

Schlecht für Retrieval:

# OAuth Notes

Token rotation depends on threat model. The OAuth 2.0 refresh
token flow requires storing the refresh token securely. When a
token expires mid-request, the client should retry after refresh.
The rotation interval is typically 15-30 minutes for access tokens
and 7-30 days for refresh tokens...

Ein langer Abschnitt ohne H2-Überschriften erzeugt einen großen Chunk. Das Embedding mittelt über alle Themen im Abschnitt hinweg. Eine Abfrage zu einem beliebigen Unterthema trifft die gesamte Notiz gleichermaßen.

Faustregel: Wenn ein Abschnitt mehr als ein Konzept behandelt, teilen Sie ihn in H2-Unterabschnitte auf. Den Rest übernimmt der Chunker.

Was nicht in Notizen gehört

Inhalte, die die Retrieval-Qualität verschlechtern:

• Unkommentierte Rohkopien vollständiger Artikel. Der Retriever indexiert die Keywords des Originalartikels und verwässert Ihren Vault mit Inhalten, die Sie nicht geschrieben haben. Fügen Sie stattdessen eine Zusammenfassung hinzu, extrahieren Sie Kernpunkte oder verlinken Sie auf die Quell-URL.
• Screenshots ohne Textbeschreibung. Der Retriever indexiert Markdown-Text. Ein Bild ohne Alt-Text oder umgebende Beschreibung ist sowohl für BM25 als auch für vector search unsichtbar.
• Credential-Strings. API keys, Tokens, Passwörter, Connection Strings. Selbst mit Credential Filtering ist es am sichersten, Geheimnisse nie in Notizen einzufügen. Verweisen Sie stattdessen namentlich darauf („das Cloudflare API token in ~/.env“).
• Automatisch generierte Inhalte ohne Kuratierung. Wenn ein Tool eine Notiz erzeugt (Meeting-Transkript, Readwise-Highlights, RSS-Import), prüfen und annotieren Sie sie, bevor sie in den permanenten Vault gelangt. Unkuratierte Auto-Importe erhöhen das Volumen, ohne auffindbaren Wert zu schaffen.

Plugin-Ökosystem für AI Workflows

Obsidian-Plugins, die die Vault-Qualität für AI Retrieval verbessern, fallen in drei Kategorien: Struktur (Konsistenz erzwingen), Abfragen (Metadaten zugänglich machen) und Sync (den Vault aktuell halten).

Wesentliche Plugins

Dataview. Fragt Ihren Vault wie eine Datenbank über frontmatter-Felder ab. Erstellen Sie dynamische Indizes: „alle Notizen mit dem Tag security, die in den letzten 30 Tagen aktualisiert wurden“ oder „alle Projektnotizen mit dem Status active“. Dataview hilft dem Retrieval nicht direkt, unterstützt Sie aber dabei, Lücken in der Abdeckung Ihres Vaults zu erkennen und Notizen zu finden, die aktualisiert werden müssen.

TABLE type, domain, updated
FROM "03-resources"
WHERE status = "active"
SORT updated DESC
LIMIT 20

Templater. Erstellt Notizen aus Vorlagen mit dynamischen Feldern. Stellen Sie sicher, dass jede neue Notiz mit korrektem frontmatter beginnt, indem Sie eine Vorlage verwenden, die die Felder created, type und domain vorausfüllt. Konsistentes frontmatter verbessert die Retrieval-Filterung.

<%* /* New Resource Note Template */ %>
---
title: "<% tp.file.cursor() %>"
type: note
domain: <% tp.system.suggester(["programming", "security", "ai-engineering", "design", "devops"], ["programming", "security", "ai-engineering", "design", "devops"]) %>
tags: []
created: <% tp.date.now("YYYY-MM-DD") %>
updated: <% tp.date.now("YYYY-MM-DD") %>
source: ""
status: active
---

## Key Points

## Details

## References

Linter. Erzwingt Formatierungsregeln im gesamten Vault. Eine konsistente Überschriftenhierarchie (H1 für Titel, H2 für Abschnitte, H3 für Unterabschnitte) sorgt dafür, dass der Chunker vorhersehbare Ergebnisse erzeugt. Linter-Regeln, die für Retrieval relevant sind:

• Überschriftenabfolge: sequenzielle Überschriftenebenen erzwingen (kein Sprung von H1 zu H3)
• YAML-Titel: mit dem Dateinamen abgleichen
• Nachgestellte Leerzeichen: entfernen (vermeidet FTS5-Tokenisierungsartefakte)
• Aufeinanderfolgende Leerzeilen: auf 1 begrenzen (sauberere Chunks)

Git-Integration. Versionskontrolle für Ihren Vault. Verfolgen Sie Änderungen im Zeitverlauf, synchronisieren Sie zwischen Maschinen und stellen Sie versehentlich gelöschte Inhalte wieder her. Git liefert außerdem mtime-Daten, die der Indexer für die inkrementelle Änderungserkennung nutzt.

Plugins, die beim Indexing helfen

Smart Connections. Ein Obsidian-Plugin, das AI-gestützte semantische Suche direkt in Obsidian bereitstellt. Smart Connections v4 erstellt standardmäßig lokale Embeddings — sobald Ihr Vault indexiert ist, funktionieren semantische Verbindungen und Nachschlagen vollständig offline ohne API-Aufrufe.¹¹ v4.5.0 (5. Mai 2026) macht Footer-Verbindungen zu einem Bestandteil von Smart Connections Core, sodass jede Installation verwandte Notizverbindungen im Footer anzeigen kann, ohne ein Seitenpanel zu öffnen. Neuere v4-Versionen haben außerdem Graph-Ansichten für Verbindungslisten, konfigurierbare Dock-Positionen, eine verbesserte Wiederherstellung von Block-Embeddings nach unterbrochenen Indexing-Läufen und „Substrate“ hinzugefügt, eine Cross-Plugin-Umgebung, in der Smart Connections, Smart Chat und Smart Composer gemeinsamen Zustand teilen können.²¹ Das Retrieval-System in diesem Guide liegt zwar außerhalb von Obsidian (es läuft als Python-Pipeline), doch Smart Connections ist nützlich, um beim Schreiben semantische Beziehungen zu erkunden. Beide Systeme indexieren dieselben Inhalte, bedienen aber unterschiedliche Anwendungsfälle: Smart Connections für die Entdeckung im Editor, der externe Retriever für die AI Tool-Integration über MCP.

AI-native Plugins, die im April 2026 veröffentlicht wurden. Eine Welle neuer Community-Plugins zielt direkt auf den Claude Code / Codex / Gemini-CLI-Workflow:

Betrachten Sie das als entstehende Oberfläche — mehrere dieser Plugins werden sich in den nächsten Quartalen wahrscheinlich konsolidieren oder in Smart Connections / Obsidian Core aufgehen. Wenn Sie heute eines auswählen, liegen VaultSearch und Hybrid Search MCP der Philosophie des externen Retrievers in diesem Guide am nächsten.

Dataview-Hinweis: Dataview (das langjährige Obsidian-Abfrage-Plugin) hat Version 0.5.70 zuletzt im April 2025 veröffentlicht und ist seitdem faktisch inaktiv. Für neue Arbeit ist Obsidian’s integrierte Funktion Bases (1.9+) der implizite Nachfolger und der empfohlene Weg.

Metadata Menu. Bietet strukturierte frontmatter-Bearbeitung mit Autovervollständigung für Feldwerte. Reduziert Tippfehler in den Feldern type, domain und tags. Konsistente Metadaten verbessern die Genauigkeit der Retrieval-Filterung.

Plugins, die Indexing verschlechtern

Excalidraw. Speichert Zeichnungen als in Markdown-Dateien eingebettetes JSON. Das JSON ist syntaktisch gültiges Markdown, erzeugt beim Chunking und Einbetten jedoch unbrauchbare Ergebnisse. Schließen Sie Excalidraw-Dateien über .indexignore vom Index aus oder filtern Sie nach Dateiendung.

Kanban. Speichert den Board-Zustand als speziell formatiertes Markdown. Das Format ist für Kanban-Rendering ausgelegt, nicht für Prosa-Retrieval. Der Chunker erzeugt Fragmente von Kartentiteln und Metadaten, die sich nicht gut einbetten lassen. Schließen Sie Kanban-Boards vom Index aus.

Calendar. Erstellt tägliche Notizen mit minimalem Inhalt (oft nur eine Datumsüberschrift). Leere oder nahezu leere Notizen erzeugen minderwertige Chunks. Wenn Sie tägliche Notizen verwenden, schreiben Sie dort substanzielle Inhalte hinein oder schließen Sie den Ordner für tägliche Notizen vom Index aus.

Plugin-Konfiguration, die zählt

Dateiwiederherstellung → Aktiviert. Schützt vor versehentlichem Löschen von Notizen. Nicht direkt mit Retrieval verbunden, aber kritisch für eine Wissensdatenbank, auf die Sie angewiesen sind.

Strikte Zeilenumbrüche → Deaktiviert. Markdown-standardkonforme Zeilenumbrüche (doppelte Leerzeile für Absätze) erzeugen sauberere Chunks als Obsidian’s strikter Modus (einzelner Zeilenumbruch für <br>).

Standardspeicherort für neue Dateien → Festgelegter Ordner. Leiten Sie neue Dateien nach 00-inbox/, damit nicht kategorisierte Notizen keine Domain-Ordner verunreinigen. Die Inbox ist ein Staging-Bereich; Dateien wandern nach der Triage in Domain-Ordner.

Wiki-link-Format → Kürzester Pfad, wenn möglich. Kürzere Link-Ziele sind für den Retriever beim Indexieren der Link-Struktur leichter aufzulösen.

Embedding-Modelle: Auswahl und Konfiguration

Das Embedding-Modell wandelt Text-Chunks in numerische Vektoren für die semantische Suche um. Die Modellwahl bestimmt die Retrieval-Qualität, die Indexgröße, die Embedding-Geschwindigkeit und die Laufzeitabhängigkeiten. Dieser Abschnitt erklärt, warum Model2Vecs potion-base-8M die Standardwahl ist und wann Alternativen sinnvoll sind.

Warum Model2Vec potion-base-8M

Modell: minishlab/potion-base-8M Parameter: 7,6 Millionen Dimensionen: 256 Größe: ~30 MB Abhängigkeiten: model2vec (nur numpy, kein PyTorch) Inference: nur CPU, statische Word Embeddings (keine Attention-Layer)

Model2Vec destilliert das Wissen eines Sentence Transformers in statische Token Embeddings. Statt Attention-Layer über die Eingabe laufen zu lassen (wie BERT, MiniLM und andere Transformer-Modelle), erzeugt Model2Vec Vektoren durch gewichtete Mittelung vorberechneter Token Embeddings.⁵ Die praktische Folge: Die Embedding-Geschwindigkeit ist 50- bis 500-mal höher als bei transformerbasierten Modellen, weil keine sequenzielle Berechnung stattfindet.

Auf der aktuellen Model2Vec-Ergebnisseite erreicht potion-base-8M etwa 92 % des All-Task-Scores von all-MiniLM-L6-v2 (51,32 gegenüber 55,80), bleibt dabei aber um Größenordnungen schneller.⁶ Die verbleibende Qualitätslücke ist der Preis für die Geschwindigkeits- und Einfachheitsvorteile. Bei kurzen Markdown-Chunks (durchschnittlich 200-400 Wörter in einem typischen Vault) fällt der Qualitätsunterschied weniger stark aus als bei längeren Dokumenten, weil beide Modelle bei kurzen, fokussierten Texten zu ähnlichen Repräsentationen konvergieren.

Konfiguration

# embedder.py
DEFAULT_MODEL = "minishlab/potion-base-8M"
EMBEDDING_DIM = 256

class Model2VecEmbedder:
    def __init__(self, model_name=DEFAULT_MODEL):
        self._model_name = model_name
        self._model = None

    def _ensure_model(self):
        if self._model is not None:
            return
        _activate_venv()  # Add isolated venv to sys.path
        from model2vec import StaticModel
        self._model = StaticModel.from_pretrained(self._model_name)

    def embed_batch(self, texts):
        self._ensure_model()
        vecs = self._model.encode(texts)
        return [v.tolist() for v in vecs]

Lazy Loading. Das Modell wird erst bei der ersten Nutzung geladen, nicht beim Import. Das Importieren des Embedder-Moduls kostet nichts, wenn der Retriever im reinen BM25-Fallback-Modus arbeitet (z. B. wenn das Embedding-venv nicht installiert ist).

Isolierte virtuelle Umgebung. Das Modell läuft in einem dedizierten venv (z. B. ~/.claude/venvs/memory/), um Abhängigkeitskonflikte mit dem Rest der Toolchain zu vermeiden. Die Funktion _activate_venv() fügt die site-packages des venv zur Laufzeit zu sys.path hinzu.

# Create isolated venv
python3 -m venv ~/.claude/venvs/memory
~/.claude/venvs/memory/bin/pip install model2vec

Batch-Verarbeitung. Der Embedder verarbeitet Texte in Batches von 64, um den Overhead von Model2Vec zu amortisieren. Der Indexer übergibt Chunks an embed_batch(), statt jeweils einen Chunk einzeln einzubetten.

Wann Alternativen sinnvoll sind

Wählen Sie potion-base-32M, wenn Sie eine bessere Qualität als bei potion-base-8M möchten, ohne die Familie statischer Embeddings zu verlassen. Es verwendet ein größeres Vokabular, das aus baai/bge-base-en-v1.5 destilliert wurde, erreicht einen All-Task-Score von 52,83 (etwa 3 % höher als potion-base-8M) und behält dabei dieselbe 256-dimensionale Ausgabe sowie die reine numpy-Abhängigkeit bei.⁸ Die 4-mal größere Modelldatei erhöht den Speicherbedarf, die Embedding-Geschwindigkeit bleibt aber um Größenordnungen höher als bei Transformer-Modellen.

Wählen Sie potion-retrieval-32M, wenn Ihr primärer Anwendungsfall Retrieval ist (was bei der Vault-Suche der Fall ist). Diese Variante ist speziell für Retrieval-Aufgaben aus potion-base-32M feinabgestimmt und erreicht in der Retrieval-Benchmark-Tabelle von Model2Vec einen Wert von 35,06 gegenüber 32,67 für potion-base-32M.⁸ Der Kompromiss besteht darin, dass es für Retrieval statt für allgemeine Embedding-Qualität optimiert ist.

Wählen Sie potion-multilingual-128M, wenn Ihr Vault Notizen in mehreren Sprachen enthält. Dieses im Mai 2025 veröffentlichte Modell für 101 Sprachen ist das leistungsstärkste statische Embedding-Modell für mehrsprachige Aufgaben. Es erzeugt Embeddings für beliebige Texte in beliebigen Sprachen und behält dieselbe reine numpy-Abhängigkeit wie andere potion-Modelle bei.¹² Die größere Modelldatei (~500 MB) ist der Kompromiss für sprachübergreifende Fähigkeiten. Nutzen Sie es, wenn Sie neben englischen Inhalten auch Notizen auf Japanisch, Chinesisch, Deutsch oder in anderen nicht englischen Sprachen haben.

Wählen Sie all-MiniLM-L6-v2, wenn Retrieval-Qualität wichtiger ist als Geschwindigkeit und PyTorch installiert ist. Die 384-dimensionalen Vektoren erhöhen die Größe der SQLite-Datenbank im Vergleich zu 256-dimensionalen Vektoren um ~50 %. Die Embedding-Geschwindigkeit sinkt bei einer vollständigen Neuindizierung von 15.000 Dateien auf M-Series-Hardware von <1 Minute auf ~10 Minuten.

Wählen Sie nomic-embed-text-v1.5, wenn Sie die bestmögliche lokale Retrieval-Qualität benötigen und langsameres Indexing akzeptieren. Die 768-dimensionalen Vektoren verdreifachen die Datenbankgröße ungefähr. Erfordert PyTorch und eine moderne CPU oder GPU.

Wählen Sie text-embedding-3-small, wenn Netzwerklatenz und Datenschutz vertretbare Kompromisse sind. Das API erzeugt Embeddings mit der höchsten Qualität, bringt aber eine Cloud-Abhängigkeit, Kosten pro Token (0,02 $/Million Tokens) und die Übertragung Ihrer Inhalte an OpenAIs Server mit sich.

Bleiben Sie in allen anderen Fällen bei potion-base-8M. Der Geschwindigkeitsvorteil ist entscheidend für iteratives Indexing (Neuindizierung während der Entwicklung), die reine numpy-Abhängigkeit vermeidet die Installationskomplexität von PyTorch, und die 256-dimensionalen Vektoren halten die Datenbank kompakt.

Quantisierung und Dimensionsreduktion

Model2Vec v0.5.0+ unterstützt das Laden von Modellen mit reduzierter Präzision und reduzierten Dimensionen.⁸ Das ist nützlich für Deployments auf eingeschränkter Hardware oder zur Verringerung der Datenbankgröße, ohne das Modell zu wechseln:

from model2vec import StaticModel

# Load with int8 quantization (25% of original size)
model = StaticModel.from_pretrained("minishlab/potion-base-8M", quantize=True)

# Load with reduced dimensions (e.g., 128 instead of 256)
model = StaticModel.from_pretrained("minishlab/potion-base-8M", dimensionality=128)

Quantisierte Modelle behalten nahezu identische Retrieval-Qualität bei einem Bruchteil des Speicherbedarfs. Die Dimensionsreduktion folgt einer Matryoshka-artigen Trunkierung: Die ersten N Dimensionen enthalten die meisten Informationen. Eine Reduktion von 256 auf 128 Dimensionen halbiert den Vektorspeicher mit minimalem Qualitätsverlust beim Retrieval kurzer Texte.

Model2Vec v0.8.x aktualisiert die Interna für Tokenizer und Persistenz, beendet die Unterstützung für Python 3.9 und aktualisiert veröffentlichte Ergebnisse auf die neueren MTEB-Tabellen. Pinnen oder testen Sie model2vec, bevor Sie einen Produktions-Indexer aktualisieren, da Bibliotheksupgrades die Ladepfade für Modelle ändern können, selbst wenn der Name des Embedding-Modells gleich bleibt.¹⁰

Fine-Tuning für Vault-spezifische Embeddings

Model2Vec v0.4.0+ unterstützt das Trainieren benutzerdefinierter Klassifikationsmodelle auf statischen Embeddings, v0.7.0 ergänzt Vokabularquantisierung und konfigurierbares Pooling für die Destillation, und v0.8.x überarbeitet Tokenizer- und Persistenzverhalten.¹⁰ Das ist relevant für Vaults mit spezialisiertem Vokabular (medizinische Notizen, juristische Referenzen, domänenspezifischer Jargon), bei denen die Standard-potion-Modelle semantische Nuancen möglicherweise nicht erfassen:

from model2vec import StaticModel
from model2vec.train import train_model

# Fine-tune on vault-specific data
model = StaticModel.from_pretrained("minishlab/potion-base-8M")
trained_model = train_model(model, train_texts, train_labels)
trained_model.save_pretrained("./vault-embeddings")

Für die meisten Vaults liefert das standardmäßige potion-base-8M eine ausreichende Retrieval-Qualität. Fine-Tuning lohnt sich nur, wenn Retrieval wiederholt domänenspezifische Verbindungen übersieht, die ein Allzweckmodell nicht erfassen kann.

Model Hash Tracking

Der Indexer speichert einen Hash, der aus dem Modellnamen und der Vokabulargröße abgeleitet wird. Wenn Sie das Embedding-Modell ändern, erkennt der Indexer beim nächsten inkrementellen Lauf die Abweichung und löst automatisch eine vollständige Neuindizierung aus.

def _compute_model_hash(self):
    """Hash model name + vocab size for compatibility tracking."""
    key = f"{self._model_name}:{self._model.vocab_size}"
    return hashlib.sha256(key.encode()).hexdigest()[:16]

So wird verhindert, dass Vektoren verschiedener Modelle in derselben Datenbank gemischt werden, was unsinnige cosine similarity Scores erzeugen würde.

Fehlermodi

Fehler beim Modelldownload. Beim ersten Lauf wird das Modell von Hugging Face heruntergeladen. Wenn der Download fehlschlägt (Netzwerkproblem, Unternehmens-Firewall), fällt der Retriever auf den reinen BM25-Modus zurück. Nach dem ersten Download wird das Modell lokal gecacht.

Dimensionskonflikt. Wenn Sie Modelle wechseln, ohne die Datenbank zu löschen, haben die gespeicherten Vektoren eine andere Dimension als neue Embeddings. Der Indexer erkennt dies über den Modell-Hash und löst eine vollständige Neuindizierung aus. Wenn die Hash-Prüfung fehlschlägt (benutzerdefiniertes Modell ohne korrekten Hash), gibt sqlite-vec bei KNN-Abfragen mit nicht übereinstimmenden Dimensionen einen Fehler aus.

Speicherdruck bei großen Vaults. Das Einbetten von mehr als 50.000 Chunks in einem einzigen Batch kann erheblichen Speicher verbrauchen. Der Indexer verarbeitet in Batches von 64, um die maximale Speichernutzung zu begrenzen. Wenn der Speicher weiterhin ein Problem ist, reduzieren Sie die Batch-Größe.

Volltextsuche mit FTS5

Die FTS5-Erweiterung von SQLite bietet Volltextsuche mit BM25-Ranking. FTS5 ist die Keyword-Suchkomponente der hybrid Retrieval Pipeline. Dieser Abschnitt behandelt die FTS5-Konfiguration, wann BM25 besonders stark ist und welche spezifischen Fehlermodi auftreten.

Virtuelle FTS5-Tabelle

CREATE VIRTUAL TABLE chunks_fts USING fts5(
    chunk_text,
    section,
    heading_context,
    content=chunks,
    content_rowid=id
);

Content-Sync-Modus. Der Parameter content=chunks weist FTS5 an, direkt auf die Tabelle chunks zu verweisen, statt eine doppelte Kopie des Textes zu speichern. Das halbiert den Speicherbedarf, bedeutet aber, dass FTS5 manuell synchronisiert werden muss, wenn chunks eingefügt, aktualisiert oder gelöscht werden.

Spalten. Drei Spalten werden indexiert: - chunk_text — Der primäre Inhalt jedes chunks (BM25-Gewicht: 1,0) - section — Der H2-Überschriftentext (BM25-Gewicht: 0,5) - heading_context — Notiztitel, Tags und Metadaten (BM25-Gewicht: 0,3)

BM25-Ranking

BM25 bewertet Dokumente nach Termfrequenz, inverser Dokumentfrequenz und Normalisierung der Dokumentlänge. Die Hilfsfunktion bm25() in FTS5 akzeptiert spaltenspezifische Gewichtungen:

SELECT
    c.id, c.file_path, c.section, c.chunk_text,
    bm25(chunks_fts, 1.0, 0.5, 0.3) AS score
FROM chunks_fts
JOIN chunks c ON chunks_fts.rowid = c.id
WHERE chunks_fts MATCH ?
ORDER BY score
LIMIT 30;

Die Spaltengewichtungen (1,0, 0,5, 0,3) bedeuten: - Ein Keyword-Treffer in chunk_text trägt am stärksten zum Score bei - Ein Treffer in section (Überschrift) trägt halb so viel bei - Ein Treffer in heading_context (Titel, Tags) trägt 30 % so viel bei

Diese Gewichtungen sind anpassbar. Wenn Ihr Obsidian-Tresor aussagekräftige Überschriften hat, die die Inhaltsqualität stark vorhersagen, erhöhen Sie das Gewicht für section. Wenn Ihre Tags umfassend und korrekt sind, erhöhen Sie das Gewicht für heading_context.

Wann BM25 gewinnt

BM25 ist besonders stark bei Abfragen mit exakten Bezeichnern:

• Funktionsnamen: _rrf_fuse, embed_batch, get_stale_files
• CLI-Flags: --incremental, --vault, --model
• Konfigurationsschlüssel: bm25_weight, max_tokens, batch_size
• Fehlermeldungen: SQLITE_LOCKED, ConnectionRefusedError
• Spezifische Fachbegriffe: PostToolUse, PreToolUse, AGENTS.md

Bei diesen Abfragen findet BM25 die exakte Übereinstimmung sofort. Die Vektorsuche würde semantisch verwandte Inhalte zurückgeben, könnte die exakte Übereinstimmung aber niedriger einstufen als eine konzeptionelle Diskussion.

Wann BM25 scheitert

BM25 scheitert bei Abfragen, die andere Begriffe verwenden als die gespeicherten Inhalte:

• Abfrage: “how to handle authentication failures” → Der Obsidian-Tresor enthält Notizen zu “login error recovery” und “session expiration handling.” BM25 findet keine Übereinstimmung, weil sich die Keywords unterscheiden.
• Abfrage: “what is the best way to manage state” → Der Obsidian-Tresor enthält Notizen zu “Redux store patterns” und “context providers.” BM25 verfehlt sie, weil “state management” über konkrete Technologienamen ausgedrückt wird.

BM25 scheitert außerdem bei Keyword-Kollisionen im großen Maßstab. In einem Tresor mit 15.000 Dateien findet eine Suche nach “configuration” Hunderte von Notizen, weil fast jede Projektnotiz Konfiguration erwähnt. Die Ergebnisse sind technisch korrekt, praktisch aber unbrauchbar — das Ranking kann nicht bestimmen, welche “configuration”-Notiz für die aktuelle Abfrage relevant ist.

FTS5-Tokenizer

FTS5 verwendet standardmäßig den unicode61-Tokenizer, der ASCII- und Unicode-Text verarbeitet. Für Tresore mit vielen CJK-Inhalten (Chinesisch, Japanisch, Koreanisch) sollten Sie den trigram-Tokenizer in Betracht ziehen:

-- For CJK-heavy vaults
CREATE VIRTUAL TABLE chunks_fts USING fts5(
    chunk_text, section, heading_context,
    content=chunks, content_rowid=id,
    tokenize='trigram'
);

Der standardmäßige unicode61-Tokenizer trennt an Wortgrenzen, was bei Sprachen ohne Leerzeichen zwischen Wörtern schlecht funktioniert. Der trigram-Tokenizer trennt alle drei Zeichen und ermöglicht dadurch Substring-Matching, allerdings auf Kosten der Indexgröße (ungefähr 3-mal größer).

Wartung

FTS5 erfordert eine explizite Synchronisierung, wenn sich die zugrunde liegende Tabelle chunks ändert:

# After inserting chunks
cursor.execute("""
    INSERT INTO chunks_fts(chunks_fts)
    VALUES('rebuild')
""")

Der Befehl rebuild rekonstruiert den FTS5-Index aus der Inhaltstabelle. Führen Sie ihn nach Masseneinfügungen aus (vollständige Neuindexierung), aber nicht nach einzelnen inkrementellen Aktualisierungen — verwenden Sie dafür INSERT INTO chunks_fts(rowid, chunk_text, section, heading_context), um einzelne Zeilen zu synchronisieren.

Vector Search mit sqlite-vec

Die sqlite-vec-Erweiterung bringt Vector-KNN-Suche (K-Nearest Neighbors) in SQLite. Dieser Abschnitt behandelt die sqlite-vec-Konfiguration, die Embedding-Pipeline von der Notiz bis zum durchsuchbaren Vektor und die konkreten Query-Muster.

sqlite-vec Virtual Table

CREATE VIRTUAL TABLE chunk_vecs USING vec0(
    id INTEGER PRIMARY KEY,
    embedding float[256]
);

Das vec0-Modul speichert 256-dimensionale Float-Vektoren als gepackte Binärdaten. Die Spalte id wird 1:1 der Tabelle chunks zugeordnet und ermöglicht Joins zwischen Vector-Ergebnissen und Chunk-Metadaten.

Embedding-Pipeline

Die Pipeline läuft von der Notiz zum durchsuchbaren Vektor:

Note (.md file)
  → Chunker: split at H2 boundaries
    → Chunks (30-2000 chars each)
      → Credential filter: scrub secrets
        → Embedder: Model2Vec encode
          → Vectors (256-dim float arrays)
            → sqlite-vec: store as packed binary
              → Ready for KNN queries

Vector-Serialisierung

Das struct-Modul von Python serialisiert Float-Vektoren für die sqlite-vec-Speicherung:

import struct

def _serialize_vector(vec):
    """Pack float list into binary for sqlite-vec."""
    return struct.pack(f"{len(vec)}f", *vec)

def _deserialize_vector(blob, dim=256):
    """Unpack binary blob to float list."""
    return list(struct.unpack(f"{dim}f", blob))

KNN Query

Eine Vector-Search-Query bettet die Eingabe-Query ein und findet dann die K nächsten Chunks anhand der Kosinusdistanz:

def _vector_search(self, query_text, limit=30):
    query_vec = self.embedder.embed_batch([query_text])[0]
    packed = _serialize_vector(query_vec)

    results = self.db.execute("""
        SELECT
            cv.id,
            cv.distance,
            c.file_path,
            c.section,
            c.chunk_text
        FROM chunk_vecs cv
        JOIN chunks c ON cv.id = c.id
        WHERE embedding MATCH ?
            AND k = ?
        ORDER BY distance
    """, [packed, limit]).fetchall()

    return results

Der Operator MATCH in sqlite-vec führt eine Approximate-Nearest-Neighbor-Suche aus. Der Parameter k steuert, wie viele Ergebnisse zurückgegeben werden. Die Spalte distance enthält die Kosinusdistanz (0 = identisch, 2 = entgegengesetzt).

KNN-Paginierung mit Distanzbeschränkungen

Seit sqlite-vec v0.1.7 unterstützen KNN-Queries Constraints wie WHERE distance < ?. Damit wird cursorbasierte Paginierung durch große Ergebnismengen möglich, ohne frühere Seiten erneut zu scannen.¹⁴ Die späteren stabilen Releases v0.1.8 und v0.1.9 sind Packaging- und DELETE-Bugfix-Releases, keine Releases mit neuem Query-Modell. Daher bleibt v0.1.7 die Funktionsgrenze für dieses Paginierungsmuster.²³

Am Horizont ist die v0.1.10-alpha-Linie (31. März bis 18. Mai 2026) die erste, die sqlite-vec über Brute-Force-KNN hinausführt: Sie führt Approximate-Nearest-Neighbor-Indextypen ein — rescore, einen experimentellen ivf-Index (Inverted File), der standardmäßig nicht aktiviert ist, sowie einen festplattenbasierten DiskANN-Index für Vaults, die zu groß sind, um Vektoren dauerhaft im Arbeitsspeicher zu halten.²³ Das würde die Skalierungsgeschichte für sehr große Vaults verändern, aber die 0.1.10-Linie ist weiterhin Pre-Release (Alpha) — behandeln Sie ANN-Indexierung als experimentell und bauen Sie für Produktions-Vaults weiter auf dem stabilen Brute-Force-KNN-Pfad von v0.1.9 auf, bis eine stabile 0.1.10 erscheint.

def _paginated_vector_search(self, query_vec, page_size=20, max_distance=None):
    """Paginate through KNN results using distance constraints."""
    packed = _serialize_vector(query_vec)
    constraint = f"AND distance < {max_distance}" if max_distance else ""

    results = self.db.execute(f"""
        SELECT cv.id, cv.distance, c.file_path, c.chunk_text
        FROM chunk_vecs cv
        JOIN chunks c ON cv.id = c.id
        WHERE embedding MATCH ?
            AND k = ?
            {constraint}
        ORDER BY distance
    """, [packed, page_size]).fetchall()

    # Use last result's distance as cursor for next page
    next_cursor = results[-1][1] if results else None
    return results, next_cursor

Dies ersetzt das frühere Muster, ein großes k abzurufen und in Python zu slicen, wodurch der Speicherverbrauch bei explorativen Queries über große Vaults sinkt.

DELETE-Unterstützung in vec0-Tabellen

sqlite-vec v0.1.7 fügte native DELETE-Unterstützung für vec0 Virtual Tables hinzu, und v0.1.9 behob einen DELETE-Fehlerpfad mit Metadaten-Textspalten, die länger als 12 Zeichen sind.¹⁴²³ Zuvor erforderte das Entfernen von Vektoren, die Tabelle zu löschen und neu zu erstellen. Jetzt kann der Datei-Entfernungspfad des Indexers Vektoren direkt löschen:

# Before v0.1.7: required workaround (drop + recreate, or mark as inactive)
# After v0.1.7: direct DELETE works
db.execute("DELETE FROM chunk_vecs WHERE id = ?", [chunk_id])

Das vereinfacht die inkrementelle Neuindexierung, wenn Notizen gelöscht oder verschoben werden. Der Indexer muss keine Schatten-Tabelle mit „active IDs” mehr pflegen und auch keine Batch-Rebuilds durchführen.

Wann Vector Search gewinnt

Vector Search ist besonders stark bei Queries, bei denen das Konzept wichtiger ist als die konkreten Wörter:

• Query: “how to handle authentication failures” → Findet Notizen zu “login error recovery” (derselbe semantische Raum, andere Keywords)
• Query: “what patterns exist for caching” → Findet Notizen zu “memoization,” “Redis TTL strategies,” und “HTTP cache headers” (verwandte Konzepte, unterschiedliche Terminologie)
• Query: “approaches to testing asynchronous code” → Findet Notizen zu “pytest-asyncio fixtures,” “mock event loops,” und “async test patterns” (dasselbe Konzept, ausgedrückt über Implementierungsdetails)

Wann Vector Search scheitert

Vector Search hat Schwierigkeiten mit exakten Bezeichnern:

• Query: _rrf_fuse → Gibt Notizen zu “fusion algorithms” und “rank merging” zurück, kann aber die eigentliche Funktionsdefinition niedriger einstufen als konzeptuelle Diskussionen
• Query: PostToolUse → Gibt eher Notizen zu “tool lifecycle hooks” und “post-execution handlers” zurück als den konkreten Hook-Namen

Vector Search hat außerdem Schwierigkeiten mit strukturierten Daten. JSON-Konfigurationsdateien, YAML-Blöcke und Code-Snippets erzeugen Embeddings, die eher strukturelle Muster als semantische Bedeutung erfassen. Eine JSON-Datei mit "review": true wird anders eingebettet als eine Prosadiskussion über Code Review.

Graceful Degradation

Wenn sqlite-vec nicht geladen werden kann (fehlende Erweiterung, inkompatible Plattform, beschädigte Bibliothek), fällt der Retriever auf reine BM25-Suche zurück:

class VectorIndex:
    def __init__(self, db_path):
        self.db = sqlite3.connect(db_path)
        self._vec_available = False
        try:
            self.db.enable_load_extension(True)
            self.db.load_extension("vec0")
            self._vec_available = True
        except Exception:
            pass  # BM25-only mode

    @property
    def vec_available(self):
        return self._vec_available

Der Retriever prüft vec_available, bevor er Vector-Queries versucht. Wenn die Funktion deaktiviert ist, verwenden alle Suchvorgänge nur BM25, und der RRF-Fusion-Schritt wird übersprungen.

Reciprocal Rank Fusion (RRF)

RRF führt zwei Ranking-Listen zusammen, ohne dass dafür eine Score-Kalibrierung nötig ist. Dieser Abschnitt behandelt den Algorithmus, eine durchgerechnete Query-Spur, das Tuning des Parameters k und warum RRF gegenüber Alternativen gewählt wird. Einen interaktiven Rechner mit bearbeitbaren Rängen, Szenario-Presets und einem visuellen Architektur-Explorer finden Sie im Deep Dive zum hybrid Retriever.

Der Algorithmus

RRF weist jedem Dokument einen Score zu, der ausschließlich auf seiner Rangposition in jeder Liste basiert:

score(d) = Σ (weight_i / (k + rank_i))

Dabei gilt: - k ist eine Glättungskonstante (60, nach Cormack et al.³) - rank_i ist der 1-basierte Rang des Dokuments in der Ergebnisliste i - weight_i ist ein optionaler Multiplikator pro Liste (Standard 1.0)

Dokumente, die in mehreren Listen gut ranken, erhalten höhere fusionierte Scores. Dokumente, die nur in einer Liste vorkommen, erhalten einen Score aus dieser einzelnen Quelle.

Warum RRF statt Alternativen

Gewichtete lineare Kombination erfordert, BM25-Scores gegen cosine distances zu kalibrieren. BM25-Scores sind unbeschränkt und skalieren mit der Korpusgröße. Cosine distances sind auf [0, 2] beschränkt. Um sie zu kombinieren, ist eine Normalisierung nötig, und die Normalisierungsparameter hängen vom Datensatz ab. RRF verwendet nur Rangpositionen, die unabhängig von der Scoring-Methode immer Ganzzahlen ab 1 sind.

Gelernte Fusion-Modelle benötigen gelabelte Trainingsdaten — also Query-Dokument-Relevanzpaare. Für eine persönliche Wissensbasis existieren solche Trainingsdaten nicht. Sie müssten Hunderte Query-Dokument-Paare manuell bewerten, um ein brauchbares Modell zu trainieren. RRF funktioniert ohne Trainingsdaten.

Condorcet-Voting-Methoden (Borda count, Schulze method) sind theoretisch elegant, aber komplexer zu implementieren und abzustimmen. Das ursprüngliche RRF-Paper zeigte, dass RRF Condorcet-Methoden auf TREC-Evaluationsdaten übertrifft.³

Fusion in der Praxis

Query: “how does the review aggregator handle disagreements”

BM25 rankt review-aggregator.py auf Position 3 (exakte Keyword-Treffer bei “review”, “aggregator”, “disagreements”), platziert aber zwei Konfigurationsdateien höher (sie treffen “review” prominenter). Vector search rankt denselben Chunk auf Position 1 (semantischer Treffer zu Konfliktlösung). Nach der RRF-Fusion:

Chunks, die in beiden Listen gut ranken, steigen nach oben. Chunks, die nur in einer Liste auftauchen, erhalten einen Single-Source-Score und fallen unter Ergebnisse, die in beiden Listen ranken. Die tatsächliche Logik zur Auflösung von Meinungsverschiedenheiten gewinnt, weil beide Methoden sie gefunden haben — BM25 über Keywords, vector search über Semantik.

Die vollständige Schritt-für-Schritt-Spur mit RRF-Berechnungen pro Rang finden Sie im interaktiven RRF-Rechner, in dem Sie verschiedene k-Werte ausprobieren können.

Implementierung

RRF_K = 60

def _rrf_fuse(self, bm25_results, vec_results,
              bm25_weight=1.0, vec_weight=1.0):
    """Fuse BM25 and vector results using Reciprocal Rank Fusion."""
    scores = {}

    for rank, r in enumerate(bm25_results, start=1):
        cid = r["id"]
        if cid not in scores:
            scores[cid] = {
                "rrf_score": 0.0,
                "file_path": r["file_path"],
                "section": r["section"],
                "chunk_text": r["chunk_text"],
                "bm25_rank": None,
                "vec_rank": None,
            }
        scores[cid]["rrf_score"] += bm25_weight / (self._rrf_k + rank)
        scores[cid]["bm25_rank"] = rank

    for rank, r in enumerate(vec_results, start=1):
        cid = r["id"]
        if cid not in scores:
            scores[cid] = {
                "rrf_score": 0.0,
                "file_path": r["file_path"],
                "section": r["section"],
                "chunk_text": r["chunk_text"],
                "bm25_rank": None,
                "vec_rank": None,
            }
        scores[cid]["rrf_score"] += vec_weight / (self._rrf_k + rank)
        scores[cid]["vec_rank"] = rank

    fused = sorted(
        scores.values(),
        key=lambda x: x["rrf_score"],
        reverse=True,
    )
    return fused

k abstimmen

Die Konstante k steuert, wie stark top-gerankte Ergebnisse gegenüber niedriger gerankten Ergebnissen gewichtet werden:

• Niedrigeres k (z. B. 10): Top-gerankte Ergebnisse dominieren. Rang 1 erzielt 1/11 = 0.091, Rang 10 erzielt 1/20 = 0.050 (1,8-facher Unterschied). Gut, wenn Sie den einzelnen Rankern zutrauen, das beste Ergebnis korrekt zu bestimmen.
• Standard-k (60): Ausgewogen. Rang 1 erzielt 1/61 = 0.0164, Rang 10 erzielt 1/70 = 0.0143 (1,15-facher Unterschied). Rangunterschiede werden komprimiert, wodurch das Auftauchen in mehreren Listen stärker gewichtet wird.
• Höheres k (z. B. 200): Das Auftauchen in beiden Listen zählt deutlich mehr als die Rangposition. Rang 1 erzielt 1/201, Rang 10 erzielt 1/210 — fast identisch. Verwenden Sie dies, wenn die einzelnen Ranker verrauschte Rankings liefern, die Übereinstimmung zwischen Listen aber zuverlässig ist.

Beginnen Sie mit k=60. Das ursprüngliche RRF-Paper stellte fest, dass dieser Wert über unterschiedliche TREC-Datensätze hinweg robust ist. Stimmen Sie ihn erst ab, nachdem Sie Fehlerfälle in Ihrer eigenen Query-Verteilung gemessen haben.

Tie-Breaking

Wenn zwei Chunks identische RRF-Scores haben (selten, aber möglich bei demselben Rang in einer Liste und keinem Auftauchen in der anderen), lösen Sie Gleichstände so auf:

1. Bevorzugen Sie Chunks, die in beiden Listen auftauchen, gegenüber Chunks, die nur in einer auftauchen
2. Bevorzugen Sie unter Chunks in beiden Listen den Chunk mit dem niedrigeren kombinierten Rang
3. Bevorzugen Sie unter Chunks in nur einer Liste den Chunk mit dem niedrigeren Rang in dieser Liste

Die vollständige Retrieval-Pipeline

Dieser Abschnitt verfolgt eine Abfrage von der Eingabe bis zur Ausgabe durch die gesamte Pipeline: BM25-Suche, Vektorsuche, RRF-Fusion, Kürzung nach Token-Budget und Kontextzusammenstellung.

End-to-End-Ablauf

User query: "PostToolUse hook for context compression"
  │
  ├─ BM25 Search (FTS5)
  │    → MATCH "PostToolUse hook context compression"
  │    → Top 30 results ranked by BM25 score
  │    → 12ms
  │
  ├─ Vector Search (sqlite-vec)
  │    → Embed query with Model2Vec
  │    → KNN k=30 on chunk_vecs
  │    → Top 30 results ranked by cosine distance
  │    → 8ms
  │
  └─ RRF Fusion
       → Merge 60 candidates (may overlap)
       → Score by rank position
       → Top 10 results
       → 3ms
       │
       └─ Token Budget
            → Truncate to max_tokens (default 4000)
            → Estimate at 4 chars per token
            → Return results with metadata
            → <1ms

Gesamtlatenz: ~23ms für eine Datenbank mit 49.746 chunks auf Apple M3 Pro-Hardware.

Die Search API

class HybridRetriever:
    def search(self, query, limit=10, max_tokens=4000,
               bm25_weight=1.0, vec_weight=1.0):
        """
        Search the vault using hybrid BM25 + vector retrieval.

        Args:
            query: Search query text
            limit: Maximum results to return
            max_tokens: Token budget for total result text
            bm25_weight: Weight for BM25 results in RRF
            vec_weight: Weight for vector results in RRF

        Returns:
            List of SearchResult with file_path, section,
            chunk_text, rrf_score, bm25_rank, vec_rank
        """
        # BM25 search
        bm25_results = self._bm25_search(query, limit=30)

        # Vector search (if available)
        if self.index.vec_available:
            vec_results = self._vector_search(query, limit=30)
            fused = self._rrf_fuse(
                bm25_results, vec_results,
                bm25_weight, vec_weight,
            )
        else:
            fused = bm25_results  # BM25-only fallback

        # Token budget truncation
        results = []
        token_count = 0
        for r in fused[:limit]:
            chunk_tokens = len(r["chunk_text"]) // 4
            if token_count + chunk_tokens > max_tokens:
                break
            results.append(r)
            token_count += chunk_tokens

        return results

Kürzung nach Token-Budget

Der Parameter max_tokens verhindert, dass der Retriever mehr Kontext zurückgibt, als das AI-Tool verwenden kann. Die Schätzung verwendet 4 Zeichen pro Token, eine sinnvolle Näherung für englische Prosa. Ergebnisse werden gierig gekürzt: Ergebnisse werden in Rangfolge hinzugefügt, bis das Budget ausgeschöpft ist.

Das ist eine konservative Strategie. Ein ausgefeilterer Ansatz würde Qualitätswerte pro Ergebnis berücksichtigen und kürzere, hochwertigere Ergebnisse längeren, schlechteren Ergebnissen vorziehen. Der gierige Ansatz ist einfacher und funktioniert in der Praxis gut, weil das RRF-Ranking die Ergebnisse bereits nach Relevanz sortiert.

Datenbankschema (vollständig)

-- Chunk content and metadata
CREATE TABLE chunks (
    id INTEGER PRIMARY KEY,
    file_path TEXT NOT NULL,
    section TEXT NOT NULL,
    chunk_text TEXT NOT NULL,
    heading_context TEXT DEFAULT '',
    mtime_ns INTEGER NOT NULL,
    embedded_at REAL NOT NULL
);

CREATE INDEX idx_chunks_file ON chunks(file_path);
CREATE INDEX idx_chunks_mtime ON chunks(mtime_ns);

-- FTS5 for BM25 search (content-synced to chunks table)
CREATE VIRTUAL TABLE chunks_fts USING fts5(
    chunk_text, section, heading_context,
    content=chunks, content_rowid=id
);

-- sqlite-vec for vector KNN search
CREATE VIRTUAL TABLE chunk_vecs USING vec0(
    id INTEGER PRIMARY KEY,
    embedding float[256]
);

-- Model metadata for compatibility tracking
CREATE TABLE model_meta (
    key TEXT PRIMARY KEY,
    value TEXT
);

Graceful-Degradation-Pfad

Full pipeline:     BM25 + Vector + RRF  →  Best results
No sqlite-vec:     BM25 only            →  Good results (no semantic)
No model download:  BM25 only            →  Good results (no semantic)
No FTS5:           Vector only           →  Decent results (no keyword)
No database:       Error                 →  Prompt user to run indexer

Der Retriever prüft seine Fähigkeiten bei der Initialisierung und passt seine Abfragestrategie an. Eine fehlende Komponente senkt die Qualität, verursacht aber keine Fehler. Der einzige harte Fehler ist eine fehlende Datenbankdatei.

Produktionsstatistiken

Gemessen an einem vault mit 16.894 Dateien, 49.746 chunks, einer 83 MB großen SQLite-Datenbank, Apple M3 Pro:

Content Hashing und Änderungserkennung

Der Indexer muss wissen, welche Dateien sich seit dem letzten Indexlauf geändert haben. Dieser Abschnitt behandelt den Mechanismus zur Änderungserkennung und die Hashing-Strategie.

Vergleich der Dateiänderungszeit

Der Indexer speichert mtime_ns (Dateiänderungszeit in Nanosekunden) für jeden chunk in der Tabelle chunks. Bei einem inkrementellen Lauf führt der Indexer Folgendes aus:

1. Scannt den vault nach allen .md-Dateien in erlaubten Ordnern
2. Liest mtime_ns für jede Datei aus dem Dateisystem
3. Vergleicht den Wert mit dem gespeicherten mtime_ns in der Datenbank
4. Erkennt drei Kategorien:
5. Neue Dateien: Pfad existiert im Dateisystem, aber nicht in der Datenbank
6. Geänderte Dateien: Pfad existiert in beiden, aber mtime_ns unterscheidet sich
7. Gelöschte Dateien: Pfad existiert in der Datenbank, aber nicht im Dateisystem

def get_stale_files(self, vault_mtimes):
    """Find files whose mtime changed or are new."""
    stored = dict(self.db.execute(
        "SELECT DISTINCT file_path, mtime_ns FROM chunks"
    ).fetchall())

    stale = []
    for path, mtime in vault_mtimes.items():
        if path not in stored or stored[path] != mtime:
            stale.append(path)
    return stale

def get_deleted_files(self, vault_paths):
    """Find files in database that no longer exist in vault."""
    stored_paths = set(r[0] for r in self.db.execute(
        "SELECT DISTINCT file_path FROM chunks"
    ).fetchall())
    return stored_paths - set(vault_paths)

Warum mtime statt Content Hash

Content Hashing (SHA-256 des Dateiinhalts) wäre zuverlässiger als der mtime-Vergleich, denn es würde Fälle erkennen, in denen eine Datei berührt wurde, ohne sich zu ändern (z. B. wenn git checkout die ursprüngliche mtime wiederherstellt). Hashing erfordert allerdings, bei jedem inkrementellen Lauf jede Datei zu lesen. Bei 16.894 Dateien dauert das Lesen der Dateiinhalte 2-3 Sekunden. Das Lesen der mtimes aus dem Dateisystem dauert <100ms.

Der Kompromiss: Der mtime-Vergleich löst gelegentlich unnötige Neuindexierungen unveränderter Dateien aus (False Positives), übersieht aber keine tatsächlichen Änderungen. False Positives kosten pro Lauf ein paar zusätzliche Embedding-Aufrufe. Der Geschwindigkeitsunterschied (100ms gegenüber 3 Sekunden) macht mtime zur pragmatischen Wahl für ein System, das bei jeder AI-Interaktion läuft.

Umgang mit Löschungen

Wenn eine Datei aus dem vault gelöscht wird, entfernt der Indexer alle zugehörigen chunks aus der Datenbank:

def remove_file(self, file_path):
    """Remove all chunks and vectors for a file."""
    chunk_ids = [r[0] for r in self.db.execute(
        "SELECT id FROM chunks WHERE file_path = ?",
        [file_path],
    ).fetchall()]

    for cid in chunk_ids:
        self.db.execute(
            "DELETE FROM chunk_vecs WHERE id = ?", [cid]
        )
    self.db.execute(
        "DELETE FROM chunks WHERE file_path = ?",
        [file_path],
    )

Die Anweisung DELETE FROM chunk_vecs funktioniert seit sqlite-vec v0.1.7 nativ, mit einem Bugfix in v0.1.9 für DELETE-Operationen auf vec0-Tabellen mit längeren Metadaten-Textspalten.¹⁴²³ Frühere Versionen erforderten Workarounds (Löschen und Neuerstellen der virtuellen Tabelle oder Pflege eines externen Satzes „aktiver IDs“). Wenn Sie eine Version vor 0.1.9 verwenden, sollten Sie ein Upgrade durchführen, bevor Sie sich in metadatenlastigen Schemas auf direkte Löschungen verlassen.

FTS5-Content-Sync-Tabellen erfordern für jede entfernte Zeile eine explizite Löschung über INSERT INTO chunks_fts(chunks_fts, rowid, ...) VALUES('delete', ?, ...). Der Indexer erledigt dies als Teil des Dateientfernungsprozesses.

Inkrementelles vs. vollständiges Reindexing

Der Indexer unterstützt zwei Modi: inkrementell (schnell, für den täglichen Einsatz) und vollständig (langsam, gelegentlich). Dieser Abschnitt erklärt, wann Sie welchen Modus verwenden sollten, welche Idempotenzgarantien gelten und wie Sie Beschädigungen beheben.

Inkrementelles Reindexing

Wann verwenden: Tägliches Indexing nach dem Bearbeiten von Notizen. Dies ist der Standardmodus.

Was dabei passiert: 1. Vault auf Dateiänderungen scannen (mtime-Vergleich) 2. Chunks für gelöschte Dateien löschen 3. Geänderte Dateien erneut in Chunks aufteilen und erneut einbetten 4. Neue Chunks für neue Dateien einfügen 5. FTS5-Index synchronisieren

Typische Dauer: <10 Sekunden für die Änderungen eines Tages in einem Vault mit 16.000 Dateien.

python index_vault.py --incremental

Vollständiges Reindexing

Wann verwenden: - Nach dem Ändern des Embedding-Modells (Abweichung beim Modell-Hash erkannt) - Nach einer Schemamigration (neue Spalten, geänderte Indizes) - Nach einer Datenbankbeschädigung (Integritätsprüfung schlägt fehl) - Wenn inkrementelles Indexing unerwartete Ergebnisse liefert

Was dabei passiert: 1. Alle vorhandenen Daten löschen (Chunks, Vektoren, FTS5-Einträge) 2. Gesamten Vault scannen 3. Alle Dateien in Chunks aufteilen 4. Alle Chunks einbetten 5. FTS5-Index von Grund auf neu erstellen

Typische Dauer: ~4 Minuten für 16.894 Dateien auf Apple M3 Pro.

python index_vault.py --full

Idempotenz

Beide Modi sind idempotent: Wird derselbe Befehl zweimal ausgeführt, entsteht dasselbe Ergebnis. Der Indexer löscht vorhandene Chunks für eine Datei, bevor er neue einfügt. Deshalb führt ein erneuter Durchlauf des inkrementellen Indexings bei einer bereits aktuellen Datenbank zu null Änderungen. Ein erneuter vollständiger Indexing-Durchlauf erzeugt eine identische Datenbank.

Wiederherstellung nach Beschädigung

Wenn die SQLite-Datenbank beschädigt wird (Stromausfall während eines Schreibvorgangs, Datenträgerfehler, beendeter Prozess mitten in einer Transaktion):

# Check integrity
sqlite3 vectors.db "PRAGMA integrity_check;"

# If corruption detected, full reindex rebuilds from source files
python index_vault.py --full

Die Quelle der Wahrheit sind immer die Vault-Dateien, nicht die Datenbank. Die Datenbank ist ein abgeleitetes Artefakt, das jederzeit neu erstellt werden kann. Das ist eine zentrale Designeigenschaft: Sie müssen die Datenbank nie sichern.

Das --incremental-Flag

Wenn der Indexer mit --incremental läuft:

1. Modell-Hash prüfen. Gespeicherten Modell-Hash mit dem aktuellen Modell vergleichen. Bei Abweichung automatisch in den vollständigen Reindexing-Modus wechseln und den Benutzer warnen.
2. Dateiscan. Erlaubte Ordner durchlaufen, Dateipfade und mtimes erfassen.
3. Änderungserkennung. Mit gespeicherten Daten vergleichen.
4. Batch-Verarbeitung. Geänderte Dateien in Batches von 64 erneut in Chunks aufteilen und einbetten.
5. Fortschrittsausgabe. Anzahl der verarbeiteten Dateien und verstrichene Zeit ausgeben.
6. Kontrolliertes Beenden. SIGINT behandeln, indem die aktuelle Datei vor dem Stoppen abgeschlossen wird.

Credential-Filtering und Datengrenzen

Persönliche Notizen enthalten Geheimnisse: API-Schlüssel, Bearer-Tokens, Datenbankverbindungsstrings, private Schlüssel, die während Debugging-Sitzungen eingefügt wurden. Der Credential-Filter verhindert, dass diese in den Retrieval-Index gelangen.

Das Problem

Eine Notiz über das Debugging einer OAuth-Integration könnte Folgendes enthalten:

The token was: eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...
I used this curl command:
  curl -H "Authorization: Bearer sk-ant-api03-abc123..."

Ohne Filterung würden sowohl das JWT als auch der API-Schlüssel in Chunks aufgeteilt, eingebettet und in der Datenbank gespeichert. Eine Suche nach „authentication“ würde den Chunk mit echten Geheimnissen zurückgeben. Schlimmer noch: Wenn der Retriever Ergebnisse über MCP an ein AI-Tool weitergibt, erscheinen die Geheimnisse im Kontextfenster der AI und möglicherweise in den Logs des Tools.

Musterbasierte Filterung

Der Credential-Filter läuft vor der Speicherung auf jedem Chunk und gleicht 25 anbieterspezifische Muster sowie generische Muster ab:

Anbieterspezifische Muster:

Generische Muster:

Filterimplementierung

def clean_content(text):
    """Scrub credentials from text before indexing."""
    result = ScanResult(is_clean=True, match_count=0, patterns=[])

    for pattern in CREDENTIAL_PATTERNS:
        matches = pattern.regex.findall(text)
        if matches:
            text = pattern.regex.sub(
                f"[REDACTED:{pattern.name}]", text
            )
            result.is_clean = False
            result.match_count += len(matches)
            result.patterns.append(pattern.name)

    return text, result

Wichtige Designentscheidungen:

1. Vor dem Embedding filtern. Der bereinigte Text wird eingebettet. Die Vektordarstellung codiert nie Credential-Muster. Eine Abfrage nach „API key“ gibt Notizen zurück, in denen es um die Verwaltung von API-Schlüsseln geht, nicht Notizen, die echte Schlüssel enthalten.

2. Ersetzen, nicht entfernen. Das Token [REDACTED:pattern-name] bewahrt den semantischen Kontext des umgebenden Texts. Das Embedding erfasst, dass „hier etwas Credential-Ähnliches stand“, ohne das Credential selbst zu codieren.

3. Muster loggen, keine Werte. Der Filter protokolliert, welche Muster gefunden wurden (z. B. „Scrubbed 2 credential(s) from oauth-debug.md [jwt, bearer-token]“), aber niemals den Credential-Wert.

Pfadbasierter Ausschluss

Die Datei .indexignore ermöglicht grobkörnige Ausschlüsse nach Pfad. Der Credential-Filter bietet feinkörniges Scrubbing innerhalb indexierter Dateien. Beides ist notwendig:

• .indexignore für ganze Ordner, von denen Sie wissen, dass sie sensible Inhalte enthalten (Gesundheitsnotizen, Finanzunterlagen, Bewerbungsunterlagen)
• Credential-Filter für Geheimnisse, die versehentlich in ansonsten indexierbare Inhalte eingebettet wurden

Datenklassifizierung

Bei Vaults mit unterschiedlichen Inhalten sollten Sie Notizen nach Sensibilität klassifizieren:

MCP-Serverarchitektur

Model Context Protocol (MCP)-Server stellen den Retriever als Tool bereit, das KI-Agenten aufrufen können. Dieser Abschnitt behandelt das Serverdesign, den Funktionsumfang und die Berechtigungsgrenzen.

Protokollauswahl: STDIO vs. HTTP

MCP unterstützt zwei Transportmodi:

STDIO — Das KI-Tool startet den MCP-Server als untergeordneten Prozess und kommuniziert über stdin/stdout. Dies ist der Standardmodus für lokale Tools. Claude Code, Codex CLI und Cursor unterstützen alle STDIO-MCP-Server.

{
  "mcpServers": {
    "obsidian": {
      "command": "python",
      "args": ["/path/to/obsidian_mcp.py"],
      "env": {
        "VAULT_PATH": "/path/to/vault",
        "DB_PATH": "/path/to/vectors.db"
      }
    }
  }
}

HTTP — Der MCP-Server läuft als eigenständiger HTTP-Dienst. Nützlich für Remotezugriff, Mehrclient-Setups oder Teamkonfigurationen, bei denen sich der Vault auf einem gemeinsamen Server befindet.

{
  "mcpServers": {
    "obsidian": {
      "url": "http://localhost:3333/mcp"
    }
  }
}

Empfehlung: Verwenden Sie STDIO für persönliche Vaults. Es ist einfacher, sicherer (keine Netzwerkfreigabe), und der Serverlebenszyklus wird vom KI-Tool verwaltet. Verwenden Sie HTTP nur, wenn mehrere Tools oder mehrere Rechner gleichzeitig auf denselben Vault zugreifen müssen.

Weiterentwicklung der MCP-Spezifikation. Die MCP-Spezifikation vom Juni 2025 ergänzte die Autorisierung nach OAuth 2.1, strukturierte Tool-Ausgaben (typisierte Rückgabeschemas) und Elicitation (vom Server initiierte Benutzeraufforderungen). Die Veröffentlichung vom November 2025 lieferte Streamable HTTP als erstklassigen Transportmodus, .well-known-URL-Erkennung für die automatische Erkundung von Serverfunktionen, strukturierte Tool-Anmerkungen, die deklarieren, ob ein Tool schreibgeschützt oder verändernd ist, sowie ein Standardisierungssystem für SDK-Stufen.⁷⁹ Die nächste Überarbeitung ist nun konkret: Die Spezifikation vom 2026-07-28 erreichte am 21. Mai 2026 den Release-Candidate-Status — die größte MCP-Überarbeitung seit dem Start. Zu ihren wichtigsten Änderungen zählen ein zustandsloser Protokollkern (der initialize-Handshake und der Header Mcp-Session-Id entfallen, sodass Server keinen sitzungsbezogenen Zustand pro Verbindung mehr verwalten), MCP Apps (Server können servergerendertes HTML zurückgeben, das in sandboxed Client-iframes angezeigt wird), Tasks, die vom experimentellen Kern zu einer offiziellen Erweiterung werden (tasks/get, tasks/update, tasks/cancel für lang laufende Vorgänge), gehärtete Autorisierung nach OAuth 2.0 / OIDC sowie eine Richtlinie für einen 12-monatigen Lebenszyklus zur Einstellung von Funktionen. Sie wurde planmäßig als Überarbeitung vom 28. Juli 2026 veröffentlicht — und ist nun die aktuelle Spezifikation (überprüft am 14. August 2026).²⁴ Für persönliche Vault-Server bleibt STDIO der einfachste Weg, und der zustandslose Kern macht Einzelbenutzer-STDIO-Server noch schlanker. Der Streamable-HTTP-Transport, die .well-known-Erkennung und MCP Apps kommen vor allem Enterprise-HTTP-Bereitstellungen mit mandantenfähigem Routing und Lastverteilung zugute. Beobachten Sie die MCP-Roadmap auf Aktualisierungen, die Ihre Transportauswahl beeinflussen.

Funktionsdesign

Der MCP-Server sollte einen minimalen Satz an Tools bereitstellen:

search — Das primäre Tool. Führt eine hybride Suche aus und gibt nach Relevanz sortierte Ergebnisse zurück.

{
  "name": "obsidian_search",
  "description": "Search the Obsidian vault using hybrid BM25 + vector retrieval",
  "parameters": {
    "query": { "type": "string", "description": "Search query" },
    "limit": { "type": "integer", "default": 5 },
    "max_tokens": { "type": "integer", "default": 2000 }
  }
}

read_note — Liest den vollständigen Inhalt einer bestimmten Notiz anhand ihres Pfads. Nützlich, wenn der Agent den vollständigen Kontext eines Suchergebnisses sehen möchte.

{
  "name": "obsidian_read_note",
  "description": "Read the full content of a note by file path",
  "parameters": {
    "file_path": { "type": "string", "description": "Relative path within vault" }
  }
}

list_notes — Listet Notizen auf, die einem Filter entsprechen (nach Ordner, Tag, Typ oder Datumsbereich). Nützlich zur Erkundung, wenn der Agent keine konkrete Abfrage hat.

{
  "name": "obsidian_list_notes",
  "description": "List notes matching filters",
  "parameters": {
    "folder": { "type": "string", "description": "Folder path within vault" },
    "tag": { "type": "string", "description": "Tag to filter by" },
    "limit": { "type": "integer", "default": 20 }
  }
}

get_context — Ein Hilfstool, das eine Suche ausführt und die Ergebnisse als Kontextblock formatiert, der sich zur Einfügung in eine Unterhaltung eignet.

{
  "name": "obsidian_get_context",
  "description": "Get formatted context from vault for a topic",
  "parameters": {
    "topic": { "type": "string", "description": "Topic to get context for" },
    "max_tokens": { "type": "integer", "default": 2000 }
  }
}

Berechtigungsgrenzen

Der MCP-Server sollte strikte Grenzen durchsetzen:

1. Schreibgeschützt. Der Server liest den Vault und die Indexdatenbank. Er erstellt, verändert oder löscht keine Notizen. Schreibvorgänge (das Erfassen neuer Notizen) werden durch separate Hooks oder Skills verarbeitet, nicht durch den MCP-Server.

2. Auf den Vault beschränkt. Der Server liest nur Dateien innerhalb des konfigurierten Vault-Pfads. Versuche der Pfadmanipulation (../../etc/passwd) müssen abgelehnt werden.

3. Ausgabe mit Berechtigungsfilterung. Selbst wenn die Datenbank bereits vorgefilterte Inhalte enthält, sollte bei der Ausgabe eine Filterung von Zugangsdaten als Defense-in-Depth-Maßnahme angewendet werden.

4. Tokenbegrenzte Antworten. Erzwingen Sie max_tokens für alle Tool-Antworten, damit das KI-Tool keine übermäßig großen Kontextblöcke erhält.

Fehlerbehandlung

MCP-Tools sollten strukturierte Fehlermeldungen zurückgeben, die dem KI-Tool bei der Wiederherstellung helfen:

def search(self, query, limit=5, max_tokens=2000):
    if not self.db_path.exists():
        return {
            "error": "Index database not found. Run the indexer first.",
            "suggestion": "python index_vault.py --full"
        }

    results = self.retriever.search(query, limit, max_tokens)

    if not results:
        return {
            "results": [],
            "message": f"No results found for '{query}'. Try broader terms."
        }

    return {
        "results": [
            {
                "file_path": r["file_path"],
                "section": r["section"],
                "text": r["chunk_text"],
                "score": round(r["rrf_score"], 4),
            }
            for r in results
        ],
        "count": len(results),
        "query": query,
    }

Claude Code-Integration

Claude Code ist der primäre Nutzer des Obsidian-Abrufsystems. Dieser Abschnitt behandelt die MCP-Konfiguration, die Hook-Integration und das Muster obsidian_bridge.py.

MCP-Konfiguration

Registrieren Sie den benutzerdefinierten Server mit claude mcp add (der Benutzerbereich schreibt in ~/.claude.json; -s project schreibt in eine teilbare .mcp.json — ~/.claude/settings.json ist keine MCP-Konfigurationsoberfläche):

claude mcp add obsidian -s user \
  -e VAULT_PATH=/absolute/path/to/vault \
  -e DB_PATH=/absolute/path/to/vectors.db \
  -- python /path/to/obsidian_mcp.py

Der entsprechende Eintrag in .mcp.json, falls Sie ihn lieber von Hand schreiben möchten:

{
  "mcpServers": {
    "obsidian": {
      "command": "python",
      "args": ["/path/to/obsidian_mcp.py"],
      "env": {
        "VAULT_PATH": "/absolute/path/to/vault",
        "DB_PATH": "/absolute/path/to/vectors.db"
      }
    }
  }
}

Starten Sie Claude Code nach dem Hinzufügen der Konfiguration neu. Der MCP-Server wird als untergeordneter Prozess gestartet. Prüfen Sie, ob er läuft:

> What tools do you have from the obsidian MCP server?

Claude Code sollte die verfügbaren Tools (obsidian_search, obsidian_read_note usw.) auflisten.

Hook-Integration

Hooks erweitern das Verhalten von Claude Code an festgelegten Punkten im Lebenszyklus. Für die Obsidian-Integration sind zwei Hooks relevant:

Hooks werden in den Einstellungen registriert (~/.claude/settings.json, unter dem Schlüssel hooks, mit Ereignisname und Matcher) und erhalten einen JSON-Payload über stdin — es gibt kein Hooks-Verzeichnis, das Claude Code automatisch erkennt, und Tool-Details werden niemals als Argumente $1/$2 übergeben.

UserPromptSubmit-Hook — durchsucht den Vault beim Absenden eines Prompts und fügt relevanten Kontext ein (stdout dieses Ereignisses wird zur Unterhaltung hinzugefügt):

{
  "hooks": {
    "UserPromptSubmit": [
      {
        "hooks": [{ "type": "command", "command": "/path/to/obsidian-context.sh" }]
      }
    ]
  }
}

#!/bin/bash
# obsidian-context.sh — read the JSON payload from stdin
PROMPT=$(jq -r '.prompt // empty')
[ -z "$PROMPT" ] && exit 0
CONTEXT=$(python /path/to/retriever.py search "$PROMPT" --limit 3 --max-tokens 1500)
if [ -n "$CONTEXT" ]; then
    printf 'Relevant vault context:\n%s\n' "$CONTEXT"   # stdout -> added as context
fi

PostToolUse-Hook — erfasst wichtige Tool-Ausgaben wieder im Vault für den zukünftigen Abruf (mit einem Matcher registriert, sodass er nur für die Tools ausgelöst wird, die Sie interessieren):

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write|Bash",
        "hooks": [{ "type": "command", "command": "/path/to/capture-insight.sh" }]
      }
    ]
  }
}

#!/bin/bash
# capture-insight.sh — tool name and response arrive as stdin JSON
PAYLOAD=$(cat)
TOOL_NAME=$(printf '%s' "$PAYLOAD" | jq -r '.tool_name')
OUTPUT=$(printf '%s' "$PAYLOAD" | jq -r '.tool_response // "" | tostring')
if [ ${#OUTPUT} -gt 500 ]; then
    python /path/to/capture.py --text "$OUTPUT" --source "claude-code-$TOOL_NAME"
fi

Das Muster obsidian_bridge.py

Ein Bridge-Modul stellt eine Python API bereit, die Hooks und Skills aufrufen können:

# obsidian_bridge.py
from retriever import HybridRetriever

_retriever = None

def get_retriever():
    global _retriever
    if _retriever is None:
        _retriever = HybridRetriever(
            db_path="/path/to/vectors.db",
            vault_path="/path/to/vault",
        )
    return _retriever

def search_vault(query, limit=5, max_tokens=2000):
    """Search vault and return formatted context."""
    retriever = get_retriever()
    results = retriever.search(query, limit, max_tokens)

    if not results:
        return ""

    lines = ["## Vault Context\n"]
    for r in results:
        lines.append(f"**{r['file_path']}** — {r['section']}")
        lines.append(f"> {r['chunk_text'][:500]}")
        lines.append("")

    return "\n".join(lines)

Der Skill /capture

Ein Claude Code-Skill, um Erkenntnisse zurück in den Vault zu übernehmen:

/capture "OAuth token rotation requires both access and refresh token invalidation"
  --domain security
  --tags oauth,tokens

Der Skill erstellt eine neue Notiz in 00-inbox/ mit korrektem frontmatter und löst eine inkrementelle Neuindizierung aus, damit die neue Notiz sofort durchsuchbar ist.

Muster für benutzerdefinierte Befehle

Claude Code-Skills können Vault-Operationen in benannte Befehle kapseln. Praktiker haben Bibliotheken mit Obsidian-spezifischen Befehlen entwickelt, die den Vault sowohl als Lesequelle als auch als Schreibziel behandeln.

Signalsuche. Ein Befehl /scan-intel fragt externe Quellen ab, bewertet die Ergebnisse anhand persönlicher Forschungsinteressen und schreibt qualifizierende Signale als Vault-Notizen mit frontmatter:

/scan-intel --topics "agent infrastructure, security" --lookback 7d

Der Befehl ruft Daten aus konfigurierten Quellen ab (arXiv, HN, RSS), wendet ein Bewertungsmodell an (Relevanz, Umsetzbarkeit, Tiefe, Autorität) und schreibt passende Signale in themenspezifische Vault-Ordner. Der Vault wird zum nachgelagerten Nutzer einer automatisierten Intelligence-Pipeline.

Captain’s Log. Ein Befehl /captains-log aggregiert die tägliche Git-Aktivität aus allen Repositorys, schreibt einen strukturierten Journaleintrag in den Vault und enthält getroffene Entscheidungen, Erkenntnisse und offene Themen:

/captains-log

Der Befehl ruft den Commit-Verlauf aus GitHub ab, gruppiert ihn nach Repository und formatiert ihn als erzählerischen Journaleintrag. Mit der Zeit schaffen die täglichen Protokolle eine durchsuchbare Aufzeichnung dessen, was ausgeliefert wurde und warum.

Obsidian-Erfassung. Ein Befehl /obsidian-capture übernimmt eine Erkenntnis aus der aktuellen Claude Code-Sitzung und schreibt sie mit korrekten Metadaten direkt in den Vault:

/obsidian-capture "SAST gates in agent loops increase security degradation"
  --folder AI-Tools --tags security,agents

Das Muster lässt sich auf jede Vault-Operation ausweiten: MOCs erstellen, Projektstatusnotizen aktualisieren, verwandte Signale verknüpfen oder wöchentliche Zusammenfassungen aus gesammelten Tagesprotokollen erstellen.

Community-Beispiele. Praktiker veröffentlichen ihre Befehlsbibliotheken. Ein Entwickler teilte 22 benutzerdefinierte Obsidian- und Claude Code-Befehle für tägliche Reviews, Projektplanung, Forschungserfassung und Content-Workflows.¹ Ein anderer entwickelte einen „Visual Explainer“-Skill, der aus Codeanalysen Diagrammnotizen im Vault erstellt.² Die Befehle unterscheiden sich, doch die Architektur bleibt einheitlich: Claude Code-Skills als Schnittstelle, Vault-Notizen als Speicherschicht und die Abrufinfrastruktur als Abfrage-Engine.

Verwaltung des Kontextfensters

Bei der Integration sollte das Kontextfenster von Claude Code berücksichtigt werden:

• Beschränken Sie den eingefügten Kontext auf 1.500–2.000 Tokens pro Abfrage. Mehr konkurriert mit dem Arbeitsgedächtnis des Agenten.
• Fügen Sie Quellenangaben ein. Geben Sie immer den Dateipfad und die Abschnittsüberschrift an, damit der Agent auf die Quelle verweisen kann.
• Kürzen Sie Chunk-Text. Lange Chunks sollten mit ... gekürzt statt vollständig weggelassen werden. Die ersten 300–500 Zeichen enthalten in der Regel die wichtigsten Informationen.
• Fügen Sie nicht bei jedem Prompt Kontext ein. Das Einfügen erfolgt über UserPromptSubmit (das Ereignis, dessen stdout das Modell erreicht); planen Sie das Budget daher dort ein: Überspringen Sie kurze Konversationsprompts, fügen Sie nur Kontext ein, wenn der Prompt Code, Dateien oder frühere Entscheidungen nennt, und begrenzen Sie den eingefügten Block. Tool-spezifische Ereignisse wie PreToolUse können den Zugriff steuern oder protokollieren, doch ihr stdout erreicht das Modell nie.

Codex-CLI-Integration

Codex CLI verbindet sich über config.toml mit MCP-Servern. Das Integrationsmuster unterscheidet sich von Claude Code bei der Konfigurationssyntax und der Bereitstellung von Anweisungen.

MCP-Konfiguration

Fügen Sie Folgendes zu ~/.codex/config.toml hinzu (Codex liest $CODEX_HOME/config.toml; Anweisungen auf Projektebene gehören in AGENTS.md, nicht in eine Projektkonfigurationsdatei):

[mcp_servers.obsidian]
command = "python"
args = ["/path/to/obsidian_mcp.py"]

[mcp_servers.obsidian.env]
VAULT_PATH = "/absolute/path/to/vault"
DB_PATH = "/absolute/path/to/vectors.db"

AGENTS.md-Muster

Codex CLI liest AGENTS.md für Anweisungen auf Projektebene. Fügen Sie Hinweise zur Vault-Suche ein:

## Available Tools

### Obsidian Vault (MCP: obsidian)
Use the `obsidian_search` tool to find relevant context from the knowledge base.
Search the vault when you need:
- Background on a concept or pattern
- Prior decisions or rationale
- Reference material for implementation

Example queries:
- "authentication patterns in FastAPI"
- "how does the review aggregator work"
- "sqlite-vec configuration"

Unterschiede zu Claude Code

Wichtiger Unterschied: Beide Tools unterstützen inzwischen Hooks und Skills; sie unterscheiden sich jedoch in ihrer Ausgestaltung. Codex kombiniert eine Freigabe-Richtlinie mit einem Sandbox-Modus auf Betriebssystemebene anstelle der Berechtigungsmodi von Claude Code, und seine Hook-Ereignisse unterscheiden sich — übernehmen Sie das Muster (den Vault vor der Arbeit abfragen, danach erfassen), nicht die Konfiguration. AGENTS.md bleibt in Codex der richtige Ort für dauerhafte Anweisungen, zuerst im Vault zu suchen.

Cursor und andere Tools

Cursor und andere AI-Tools, die MCP unterstützen, können sich mit demselben Obsidian-MCP-Server verbinden. Dieser Abschnitt behandelt die Konfiguration gängiger Tools.

Cursor

Fügen Sie Folgendes in .cursor/mcp.json im Stammverzeichnis Ihres Projekts ein:

{
  "mcpServers": {
    "obsidian": {
      "command": "python",
      "args": ["/path/to/obsidian_mcp.py"],
      "env": {
        "VAULT_PATH": "/absolute/path/to/vault",
        "DB_PATH": "/absolute/path/to/vectors.db"
      }
    }
  }
}

Die .cursorrules-Datei von Cursor kann Anweisungen zur Verwendung des Vaults enthalten:

When working on implementation tasks, search the Obsidian vault
for relevant context before writing code. Use the obsidian_search
tool with descriptive queries about the concept you're implementing.

Kompatibilitätsmatrix

Fallback für Tools ohne MCP

Für Tools, die MCP nicht unterstützen, kann der Retriever als CLI verpackt werden:

# Search from command line
python retriever_cli.py search "query text" --limit 5

# Output formatted for copy-paste into any tool
python retriever_cli.py context "query text" --format markdown

Das CLI gibt strukturierten Text aus, der manuell in die Eingabe jedes AI-Tools eingefügt werden kann. Das ist weniger elegant als die MCP-Integration, funktioniert jedoch universell.

Prompt-Caching aus strukturierten Notizen

Strukturierte Notizen im Vault können als wiederverwendbare Kontextblöcke dienen, die den Tokenverbrauch über AI-Interaktionen hinweg reduzieren. Dieser Abschnitt behandelt das Design von Cache-Schlüsseln und die Verwaltung des Tokenbudgets.

Das Muster

Statt bei jeder Interaktion nach Kontext zu suchen, erstellen Sie Kontextblöcke aus gut strukturierten Vault-Notizen vorab und cachen sie:

# cache_keys.py
CONTEXT_BLOCKS = {
    "auth-patterns": {
        "vault_query": "authentication patterns implementation",
        "max_tokens": 1500,
        "ttl_hours": 24,  # Rebuild daily
    },
    "api-conventions": {
        "vault_query": "API design conventions REST patterns",
        "max_tokens": 1000,
        "ttl_hours": 168,  # Rebuild weekly
    },
    "project-architecture": {
        "vault_query": "current project architecture decisions",
        "max_tokens": 2000,
        "ttl_hours": 12,  # Rebuild twice daily
    },
}

Cache-Invalidierung

Die Cache-Invalidierung basiert auf zwei Signalen:

1. TTL-Ablauf. Jeder Kontextblock hat eine Gültigkeitsdauer. Sobald die TTL abläuft, wird der Block durch eine erneute Abfrage des Vaults neu erstellt.
2. Erkennung von Vault-Änderungen. Erkennt der Indexer Änderungen an Dateien, die zu einem gecachten Kontextblock beigetragen haben, wird der Block sofort invalidiert.

Verwaltung des Tokenbudgets

Eine Sitzung beginnt mit einem gesamten Kontextbudget. Gecachte Blöcke verbrauchen einen Teil dieses Budgets:

Total context budget:    8,000 tokens
├─ System prompt:        1,500 tokens
├─ Cached blocks:        3,000 tokens (pre-loaded)
├─ Dynamic search:       2,000 tokens (on-demand)
└─ Conversation:         1,500 tokens (remaining)

Die gecachten Blöcke werden beim Sitzungsstart geladen. Dynamische Suchergebnisse füllen das verbleibende Budget pro Abfrage. Dieser hybride Ansatz gibt dem Agenten eine Grundlage aus häufig benötigtem Kontext und bewahrt gleichzeitig Budget für spezifische Abfragen.

Tokenverbrauch vorher/nachher

Ohne Caching: Jede relevante Abfrage löst eine Vault-Suche aus und liefert 1.500–2.000 Token Kontext zurück. Bei 10 Abfragen in einer Sitzung verbraucht der Agent 15.000–20.000 Token Vault-Kontext.

Mit Caching: Drei vorab erstellte Kontextblöcke verbrauchen insgesamt 4.500 Token. Zusätzliche Suchen fügen pro eindeutiger Abfrage 1.500–2.000 Token hinzu. Bei 10 Abfragen, von denen 6 durch gecachte Blöcke abgedeckt sind, verbraucht der Agent 4.500 + (4 * 1.500) = 10.500 Token — ungefähr die Hälfte des ungecachten Verbrauchs.

Komprimierte Zusammenfassungen ausführlicher Ausgaben erfassen

Tool-Ausgaben können ausführlich sein: Stack Traces, Dateilisten, Testergebnisse. Ein Hook kann nicht verkleinern, was das Modell sieht — bis PostToolUse ausgelöst wird, befindet sich die vollständige Ausgabe bereits im Kontextfenster, und nichts, was ein Hook ausgibt, ersetzt sie. Ein Hook kann jedoch eine komprimierte Zusammenfassung in den Vault schreiben, sodass künftige Sitzungen das Urteil in zwei Zeilen abrufen, statt das Original mit 5.000 Token erneut auszuführen oder zu lesen. Betrachten Sie dies als Erfassungsmuster für sitzungsübergreifenden Speicher, nicht als Kontextsparer innerhalb einer Sitzung (innerhalb einer Sitzung sind /compact, eingegrenzte Prompts und die Bitte um weniger ausführliche Ausgaben die wirkungsvollen Hebel).

Das Problem

Ein Bash-Tool-Aufruf, der Tests ausführt, könnte Folgendes zurückgeben:

PASSED tests/test_auth.py::test_login_success
PASSED tests/test_auth.py::test_login_failure
PASSED tests/test_auth.py::test_token_refresh
PASSED tests/test_auth.py::test_session_expiry
... (200 more lines)
FAILED tests/test_api.py::test_rate_limit_exceeded

Die vollständige Ausgabe umfasst 5.000 Token, aber das Signal steckt in 2 Zeilen: 200 bestanden, 1 fehlgeschlagen.

Hook-Implementierung

Registriert bei PostToolUse mit einem Bash-Matcher (über Einstellungen registriert, stdin JSON — siehe Hook Integration oben):

#!/bin/bash
# summarize-and-capture.sh — write a compressed summary to the vault
PAYLOAD=$(cat)
OUTPUT=$(printf '%s' "$PAYLOAD" | jq -r '.tool_response // "" | tostring')

# Only summarize large outputs
[ ${#OUTPUT} -lt 2000 ] && exit 0

if printf '%s' "$OUTPUT" | grep -q "PASSED\|FAILED"; then
    PASSED=$(printf '%s' "$OUTPUT" | grep -c "PASSED")
    FAILED=$(printf '%s' "$OUTPUT" | grep -c "FAILED")
    SUMMARY="Tests: $PASSED passed, $FAILED failed"
    [ "$FAILED" -gt 0 ] && SUMMARY="$SUMMARY
$(printf '%s' "$OUTPUT" | grep 'FAILED')"
    python /path/to/capture.py --text "$SUMMARY" --source "test-run-summary"
fi
exit 0

Jede Hook-Ausführung ist ein neuer Prozess, daher ist kein Rekursionsschutz erforderlich — die eigenen Schreibvorgänge eines Hooks lösen ihn nicht erneut aus, und exportierte Variablen bleiben nie bis zur nächsten Ausführung erhalten.

Komprimierungsheuristiken

Signalaufnahme- und Triage-Pipeline

Die Aufnahmeschicht bestimmt, was in den Vault gelangt. Ohne Kuratierung sammelt der Vault Rauschen an. Dieser Abschnitt behandelt die Bewertungs-Pipeline, die Signale an Domain-Ordner weiterleitet.

Quellen

Signale stammen aus mehreren Kanälen:

• RSS-Feeds: Technische Blogs, Sicherheitswarnungen, Release Notes
• Lesezeichen über Web Clipper: Die offizielle Obsidian-Web-Clipper-Erweiterung (Chrome, Firefox, Safari) ist der hochwertigste Aufnahmeweg für die Erfassung im Browser. Der Release-Zyklus im April 2026 machte sie für AI-Workflows deutlich nützlicher:²²
  • 1.4.0 (9. Apr.): Interaktive YouTube-Transkriptoberfläche — Video anheften, im Transkript navigieren, automatisches Scrollen und Hervorheben der aktuellen Position. Dazu kommt „Open in Reader“ als Standardoption, die eine Erfassung mit einem Klick direkt an den Reader-Modus sendet.
  • 1.5.0–1.5.1 (15. Apr.): Hervorhebungsansicht — erfasste Hervorhebungen im gesamten Vault durchsuchen und durchsuchen. Einblendübergang zum Reader. Flüssigeres YouTube-Wiedergabe/Pause-Verhalten. 1.5.1 behebt eine Regression bei der webpack-Kompilierung.
  • 1.6.0–1.6.2 (21.–23. Apr.): Umfassende Überarbeitung der Highlighter-Benutzererfahrung mit Mobilunterstützung. Defuddle 0.18 ergänzt quellenspezifische Extraktoren für LinkedIn, Threads, Bluesky, Discourse und Medium. 1.6.2 behebt eine Zwischenablagen-Regression im eingebetteten Safari-Modus. Konfigurieren Sie Vorlagen je Quell-Domain, damit YouTube-Transkripte, GitHub READMEs und Langformartikel jeweils in einer sinnvoll benannten Notiz mit dem passenden Frontmatter für die folgende Bewertungs-Pipeline landen.
• Newsletter: Wichtige Auszüge aus E-Mail-Newslettern
• Manuelle Erfassung: Notizen, die beim Lesen, in Gesprächen oder bei der Recherche entstehen
• Tool-Ausgabe: Bedeutende Ausgaben von AI-Tools, die über Hooks erfasst werden
• iOS Share Extension: Die iOS-App von Obsidian (Anfang 2026 aktualisiert) enthält eine Share Extension, die Inhalte aus Safari, sozialen Netzwerken und anderen Apps direkt im Vault speichert, ohne Obsidian zu öffnen; die 1.13-Reihe ergänzt konfigurierbare Share-Sheet-Ziele mit Vorlagenvariablen — einschließlich url, sodass eine erfasste Seite ihren Quelllink automatisch im Frontmatter vermerkt.¹⁹ Dadurch entsteht ein reibungsarmer mobiler Aufnahmeweg — teilen Sie einen Artikel aus Safari, und er trifft als zur Bewertung bereite Vault-Notiz ein.
• Obsidian CLI: Shell-Skripte und Hooks können über obsidian file create Notizen erstellen oder über obsidian file append bestehenden Notizen Inhalte hinzufügen und ermöglichen damit automatisierte Aufnahme-Pipelines auf dem Desktop.

Bewertungsdimensionen

Jedes Signal wird in vier Dimensionen bewertet (jeweils 0,0 bis 1,0):

Gesamtwert und Weiterleitung

composite = (relevance * 0.35) + (actionability * 0.25) +
            (depth * 0.25) + (authority * 0.15)

Domain-Weiterleitung

Signale mit einem Wert über 0.55 werden anhand von Keyword-Matching und Themenklassifizierung einem von 12 Domain-Ordnern zugeordnet:

05-signals/
├── ai-tooling/        # Claude, LLMs, AI development tools
├── security/          # Vulnerabilities, auth, cryptography
├── systems/           # Architecture, distributed systems
├── programming/       # Languages, patterns, algorithms
├── web/               # Frontend, backends, APIs
├── data/              # Databases, data engineering
├── devops/            # CI/CD, containers, infrastructure
├── design/            # UI/UX, product design
├── mobile/            # iOS, Android, cross-platform
├── career/            # Industry trends, hiring, growth
├── research/          # Academic papers, whitepapers
└── other/             # Signals that don't fit a domain

Produktionsstatistiken

Nach 14 Monaten Betrieb:

Knowledge-Graph-Muster

Der wiki-link-Graph von Obsidian kodiert Beziehungen zwischen Notizen. Dieser Abschnitt behandelt Link-Semantik, Graph-Traversierung zur Kontexterweiterung und Anti-Patterns, die die Graphqualität beeinträchtigen.

Backlink-Semantik

Jeder wiki-link erzeugt eine gerichtete Kante im Graphen. Obsidian verfolgt sowohl Vorwärtslinks als auch Backlinks:

• Vorwärtslink: Notiz A enthält [[Note B]] → A verlinkt auf B
• Backlink: Notiz B zeigt, dass Notiz A darauf verweist

Abhängig vom Kontext kodiert der Graph unterschiedliche Beziehungstypen:

Maps of Content (MOCs)

MOCs sind Indexnotizen, die verwandte Notizen in einer navigierbaren Struktur organisieren:

---
title: "Authentication & Security MOC"
type: moc
domain: security
---

## Core Concepts
- [[OAuth 2.0 Overview]]
- [[JWT Token Anatomy]]
- [[Session Management Patterns]]

## Implementation Patterns
- [[OAuth Token Rotation]]
- [[Refresh Token Security]]
- [[PKCE Flow Implementation]]

## Failure Modes
- [[Token Expiry Handling]]
- [[Session Fixation Prevention]]
- [[CSRF Defense Strategies]]

MOCs verbessern die Suche auf zwei Arten:

1. Direkter Treffer. Eine Suche nach „authentication overview“ trifft auf das MOC selbst und liefert dem Agenten eine kuratierte Liste verwandter Notizen.
2. Kontexterweiterung. Nach dem Finden einer bestimmten Notiz kann der Retriever prüfen, ob die Notiz in MOCs erscheint, und die Struktur des MOC in die Ergebnisse aufnehmen. So erhält der Agent eine Karte des umfassenderen Themas.

Graph-Traversierung zur Kontexterweiterung

Eine zukünftige Erweiterung des Retrievers: Nach dem Finden der Top-Ergebnisse wird der Kontext durch das Verfolgen von Links erweitert:

def expand_context(results, depth=1):
    """Follow wiki-links from top results to find related context."""
    expanded = set()
    for result in results:
        # Parse wiki-links from chunk text
        links = extract_wiki_links(result["chunk_text"])
        for link_target in links:
            # Resolve link to file path
            target_path = resolve_wiki_link(link_target)
            if target_path and target_path not in expanded:
                expanded.add(target_path)
                # Include target's most relevant chunk
                target_chunks = get_chunks_for_file(target_path)
                # ... rank and include best chunk
    return results + list(expanded_results)

Dies ist im aktuellen Retriever nicht implementiert, stellt aber eine natürliche Erweiterung der Graphstruktur dar.

Anti-Patterns

Verwaiste Cluster. Gruppen von Notizen, die miteinander verlinkt sind, aber keine Verbindungen zum Rest des Vault haben. Das Graph-Panel in Obsidian zeigt sie als getrennte Inseln. Verwaiste Cluster weisen auf fehlende MOCs oder fehlende domainübergreifende Links hin.

Tag-Wildwuchs. Tags inkonsistent zu verwenden oder zu viele sehr feingranulare Tags anzulegen. Ein Vault mit 500 eindeutigen Tags über 5.000 Notizen hinweg hat durchschnittlich 1 Notiz pro 10 Tags — die Tags sind zum Filtern nicht nützlich. Konsolidieren Sie auf 20–50 übergeordnete Tags, die Ihren Domain-Ordnern entsprechen.

Linklastige, inhaltsarme Notizen. Notizen, die ausschließlich aus wiki-links ohne Prosa bestehen. Sie werden schlecht indexiert, weil der Chunker keinen Text zum Einbetten hat. Fügen Sie mindestens einen Absatz Kontext hinzu, der erklärt, warum die verlinkten Notizen zusammenhängen.

Bidirektionale Links für alles. Nicht jede Erwähnung benötigt einen wiki-link. Die beiläufige Erwähnung von „OAuth“ erfordert nicht [[OAuth 2.0 Overview]]. Reservieren Sie wiki-links für beabsichtigte, navigierbare Beziehungen, bei denen ein Klick auf den Link nützlichen Kontext liefert.

Developer-Workflow-Rezepte

Praktische Workflows, die Vault-Retrieval mit täglichen Entwicklungsaufgaben verbinden.

Morgenkontext laden

Beginnen Sie den Tag, indem Sie relevanten Kontext laden:

Search my vault for notes about [current project] updated in the last week

Der Retriever gibt aktuelle Notizen zu Ihrem aktiven Projekt zurück und verschafft Ihnen so schnell einen Überblick darüber, wo Sie aufgehört haben. Das ist effektiver, als die Commit-Nachrichten von gestern erneut zu lesen.

Rechercheerfassung beim Coden

Während Sie eine Funktion implementieren, können Sie Erkenntnisse erfassen, ohne den Editor zu verlassen:

/capture "FastAPI dependency injection with async generators requires yield,
not return. The generator is the dependency lifecycle."
  --domain programming
  --tags fastapi,dependency-injection

Die erfasste Erkenntnis wird sofort indexiert und steht künftig für Retrieval zur Verfügung. Über Monate entsteht aus diesen Mikroerfassungen ein Korpus aus implementierungsspezifischem Wissen.

Projektstart

Wenn Sie ein neues Projekt oder eine neue Funktion beginnen:

1. Durchsuchen Sie den Vault: „Was weiß ich über [Technologie/Muster]?”
2. Prüfen Sie die Top-5-Ergebnisse auf frühere Entscheidungen und Stolperfallen
3. Prüfen Sie, ob für die Domäne ein MOC existiert; falls nicht, erstellen Sie eines
4. Suchen Sie nach Fehlermodi: „Probleme mit [Technologie]”

Debugging mit Vault Search

Wenn ein Fehler oder unerwartetes Verhalten auftritt:

Search my vault for [error message or symptom]

Frühere Debugging-Notizen enthalten oft die Ursache und die Lösung. Das ist besonders wertvoll bei wiederkehrenden Problemen über mehrere Projekte hinweg — der Vault merkt sich, was Sie vergessen.

Vorbereitung auf Code Reviews

Bevor Sie einen PR reviewen:

Search my vault for patterns and conventions about [module being changed]

Der Vault gibt frühere Entscheidungen, Architekturvorgaben und Coding-Standards zurück, die für den zu reviewenden Code relevant sind. Der Review stützt sich auf institutionelles Wissen, nicht nur auf das Diff.

Performance-Tuning

Dieser Abschnitt behandelt Optimierungsstrategien für unterschiedliche Vault-Größen und Nutzungsmuster.

Indexgrößenverwaltung

Bei mehr als 50.000 Notizen sollten Sie Folgendes erwägen: - Erhöhen Sie die batch_size von 64 auf 128, um schneller Embeddings zu erzeugen - Verwenden Sie den WAL-Modus (Standard) für gleichzeitigen Zugriff - Führen Sie vollständige Neuindexierungen außerhalb der Hauptarbeitszeiten aus

Abfrageoptimierung

WAL-Modus. Der Write-Ahead-Logging-Modus von SQLite ermöglicht gleichzeitige Lesezugriffe, während der Indexer schreibt:

db.execute("PRAGMA journal_mode=WAL")

Das ist entscheidend, wenn der MCP Server Abfragen verarbeitet, während der Indexer ein inkrementelles Update ausführt.

Connection Pooling. Der MCP Server sollte Datenbankverbindungen wiederverwenden, statt pro Abfrage eine neue Verbindung zu öffnen. Eine einzelne langlebige Verbindung mit WAL-Modus unterstützt gleichzeitige Lesezugriffe.

# MCP server initialization
db = sqlite3.connect(DB_PATH, check_same_thread=False)
db.execute("PRAGMA journal_mode=WAL")
db.execute("PRAGMA mmap_size=268435456")  # 256 MB mmap

Memory-mapped I/O. Das mmap_size-Pragma weist SQLite an, memory-mapped I/O für die Datenbankdatei zu verwenden. Bei einer Datenbank mit 83 MB werden die meisten Festplattenlesevorgänge vermieden, wenn die gesamte Datei in den Speicher gemappt wird.

FTS5-Optimierung. Führen Sie nach einer vollständigen Neuindexierung Folgendes aus:

INSERT INTO chunks_fts(chunks_fts) VALUES('optimize');

Dadurch werden die internen b-tree-Segmente von FTS5 zusammengeführt, was die Abfragelatenz für nachfolgende Suchen reduziert.

Skalierungsbenchmarks

Gemessen auf Apple M3 Pro, 36 GB RAM, NVMe SSD:

Alle Benchmarks umfassen Datenbankzugriff, Abfrageausführung und Ergebnisformatierung. Die Netzwerklatenz für die MCP STDIO-Kommunikation fügt 1-2ms hinzu.

Fehlerbehebung

Index Drift

Symptom: Die Suche gibt veraltete Ergebnisse zurück oder findet kürzlich hinzugefügte Notizen nicht.

Ursache: Der inkrementelle Indexer wurde nach dem Hinzufügen von Notizen nicht ausgeführt, oder die mtime einer Datei wurde nicht aktualisiert (z. B. bei Synchronisierung von einem anderen Rechner mit beibehaltenen Zeitstempeln).

Lösung: Führen Sie eine vollständige Neuindexierung aus: python index_vault.py --full

Wechsel des Embedding-Modells

Symptom: Nach dem Wechsel des Embedding-Modells liefert die Vector Search unsinnige Ergebnisse.

Ursache: Alte Vektoren (aus dem vorherigen Modell) werden mit neuen Abfragevektoren verglichen. Die Dimensionen oder die Semantik des Vektorraums sind inkompatibel.

Lösung: Der Indexer sollte die Abweichung beim Modellhash erkennen und automatisch eine vollständige Neuindexierung auslösen. Falls das nicht geschieht, leeren Sie die Datenbank manuell und indexieren Sie neu:

rm vectors.db
python index_vault.py --full

FTS5-Wartung

Symptom: FTS5-Abfragen liefern nach vielen inkrementellen Updates falsche oder unvollständige Ergebnisse.

Ursache: Interne FTS5-Segmente können nach vielen kleinen Updates fragmentieren.

Lösung: Neu aufbauen und optimieren:

INSERT INTO chunks_fts(chunks_fts) VALUES('rebuild');
INSERT INTO chunks_fts(chunks_fts) VALUES('optimize');

MCP Timeout

Symptom: Das AI Tool meldet, dass der MCP Server einen Timeout hatte.

Ursache: Die erste Abfrage löst das Laden des Modells aus (Lazy Initialization), was 2-5 Sekunden dauert. Der Standard-MCP-Timeout des AI Tools kann kürzer sein.

Lösung: Wärmen Sie das Modell beim Serverstart vor:

# In MCP server initialization
retriever = HybridRetriever(db_path, vault_path)
retriever.search("warmup", limit=1)  # Trigger model load

SQLite-Dateisperren

Symptom: SQLITE_BUSY- oder SQLITE_LOCKED-Fehler.

Ursache: Mehrere Prozesse schreiben gleichzeitig in die Datenbank. Der WAL-Modus erlaubt gleichzeitige Lesezugriffe, aber nur einen Schreiber.

Lösung: Stellen Sie sicher, dass nur ein Prozess (der Indexer) in die Datenbank schreibt. Der MCP Server und Hooks sollten nur lesen. Wenn Sie gleichzeitige Schreibzugriffe benötigen, verwenden Sie den WAL-Modus und setzen Sie einen Busy Timeout:

db.execute("PRAGMA busy_timeout=5000")  # Wait up to 5 seconds

sqlite-vec wird nicht geladen

Symptom: Vector Search ist deaktiviert; der Retriever läuft nur im BM25-Modus.

Ursache: Die sqlite-vec-Erweiterung ist nicht installiert, wird im Library-Pfad nicht gefunden oder ist mit der SQLite-Version inkompatibel.

Lösung:

# Install via pip
pip install sqlite-vec

# Or compile from source
git clone https://github.com/asg017/sqlite-vec
cd sqlite-vec && make

Prüfen Sie, ob die Erweiterung geladen wird:

import sqlite3
db = sqlite3.connect(":memory:")
db.enable_load_extension(True)
db.load_extension("vec0")
print("sqlite-vec loaded successfully")

Speicherprobleme bei großen Vaults

Symptom: Out-of-memory-Fehler während der vollständigen Neuindexierung eines großen Vaults (mehr als 50.000 Notizen).

Ursache: Die Embedding-batch_size ist zu groß, oder alle Dateiinhalte werden gleichzeitig in den Speicher geladen.

Lösung: Reduzieren Sie die batch_size und verarbeiten Sie Dateien inkrementell:

BATCH_SIZE = 32  # Reduce from 64

Stellen Sie außerdem sicher, dass der Indexer Dateien einzeln verarbeitet (jede Datei lesen, chunken und einbetten, bevor er zur nächsten wechselt), statt alle Dateien in den Speicher zu laden.

Migrationsleitfaden

Von Apple Notes

1. Exportieren Sie Apple Notes über die Option „Export All” (macOS) oder verwenden Sie ein Migrationstool wie apple-notes-liberator
2. Konvertieren Sie HTML-Exporte mit markdownify oder pandoc nach markdown
3. Verschieben Sie die konvertierten Dateien in den Ordner 00-inbox/ Ihres Vaults
4. Prüfen Sie jede Notiz und fügen Sie frontmatter hinzu
5. Verschieben Sie Notizen in passende Domänenordner

Von Notion

1. Exportieren Sie aus Notion: Settings → Export → Markdown & CSV
2. Entpacken Sie den Export in den Ordner 00-inbox/ Ihres Vaults
3. Korrigieren Sie Notion-spezifische markdown-Artefakte:
4. Notion verwendet - [ ] für Checklisten — das ist standardmäßiges markdown
5. Notion enthält Property-Tabellen als HTML — konvertieren Sie sie in YAML frontmatter
6. Notion bettet Bilder als relative Pfade ein — kopieren Sie Bilder in Ihren Attachments-Ordner
7. Fügen Sie standardmäßiges frontmatter hinzu (type, domain, tags)
8. Ersetzen Sie Notion-Seitenlinks durch Obsidian wiki-links

Von Google Docs

1. Verwenden Sie Google Takeout, um alle Dokumente zu exportieren
2. Konvertieren Sie .docx-Dateien nach markdown: pandoc -f docx -t markdown input.docx -o output.md
3. Batch-Konvertierung: for f in *.docx; do pandoc -f docx -t markdown "$f" -o "${f%.docx}.md"; done
4. Verschieben Sie alles in den Vault, fügen Sie frontmatter hinzu und organisieren Sie die Dateien in Ordnern

Von Plain Markdown (ohne Obsidian)

Wenn Sie bereits ein Verzeichnis mit markdown-Dateien haben:

1. Öffnen Sie das Verzeichnis als Obsidian Vault (Obsidian → Open Vault → Open folder)
2. Fügen Sie .obsidian/ zu .gitignore hinzu, falls das Verzeichnis versioniert ist
3. Erstellen Sie frontmatter-Templates und wenden Sie sie auf vorhandene Dateien an
4. Beginnen Sie beim Lesen und Organisieren damit, Notizen über [[wiki-links]] zu verlinken
5. Führen Sie den Indexer sofort aus — das Retrieval-System funktioniert ab dem ersten Tag

Von einem anderen Retrieval-System

Wenn Sie von einem anderen Embedding-/Suchsystem migrieren:

1. Versuchen Sie nicht, Vektoren zu migrieren. Unterschiedliche Modelle erzeugen inkompatible Vektorräume. Führen Sie mit dem neuen Modell eine vollständige Neuindexierung aus.
2. Migrieren Sie die Inhalte, nicht den Index. Die Vault-Dateien sind die Source of Truth. Der Index ist ein abgeleitetes Artefakt.
3. Prüfen Sie nach der Migration. Führen Sie 10-20 Abfragen aus, deren Antworten Sie kennen, und prüfen Sie, ob die Ergebnisse Ihren Erwartungen entsprechen.

Änderungsprotokoll

Referenzen