Obsidian MCP + hybride Suche: Referenz 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 Nur-Schreiben-Datenbank. Ein Vault mit 200 Dateien, Hybrid Retrieval 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 Bezeichner und Funktionsnamen. Vektorsuche findet Synonyme und konzeptuelle Übereinstimmungen über unterschiedliche Terminologie hinweg. Reciprocal Rank Fusion (RRF) führt beides zusammen, ohne eine Score-Kalibrierung zu erfordern. Keine der beiden Methoden deckt allein beide Fehlermodi ab. Forschung zum MS MARCO Passage Ranking bestätigt dieses Muster: Hybrides Retrieval übertrifft jede Methode für sich genommen konsistent.³ Der Deep Dive zum hybriden Retriever behandelt die RRF-Mathematik, durchgerechnete Beispiele mit echten Zahlen, eine Analyse der Fehlermodi und einen interaktiven Fusion-Rechner.

MCP gibt AI-Tools direkten Zugriff auf den Vault. 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 gerankte Ergebnisse mit Quellenzuordnung und nutzt den Kontext, ohne ganze Dateien zu laden. Der MCP-Server ist eine dünne Hülle um die Retrieval-Engine.

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

Inkrementelle Indexierung hält das System in unter 10 Sekunden aktuell. Der Vergleich von Dateiänderungszeiten erkennt Änderungen. Nur geänderte Dateien werden neu gechunkt und neu eingebettet. Ein vollständiger Reindex dauert auf Apple-M-Series-Hardware etwa vier Minuten. Inkrementelle Updates für die typischen Änderungen eines Tages laufen in unter zehn Sekunden. Das System bleibt ohne manuelle Eingriffe aktuell.

Die Architektur skaliert von 200 auf über 20.000 Notizen. Dasselbe Drei-Schichten-Design (Intake, Retrieval, Integration) funktioniert bei jeder Vault-Größe. Beginnen Sie mit reiner BM25-Suche über einen kleinen Vault. Ergänzen Sie 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 eigenständig nützlich und lässt sich unabhängig entfernen.

So nutzen Sie diesen Leitfaden

Dieser Leitfaden behandelt das vollständige System. Ihr Ausgangspunkt hängt davon ab, wo Sie gerade stehen:

Abschnitte mit der Markierung Contract enthalten Implementierungsdetails, Konfigurationsblöcke und Fehlermodi. Abschnitte mit der Markierung Narrative konzentrieren sich auf Konzepte, Architekturentscheidungen und die Begründung hinter Designentscheidungen. Abschnitte mit der Markierung 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, plaintextbasiert, graphstrukturiert sind und der Benutzer jede Schicht des Stacks kontrolliert.

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, keine API zum Lesen der Inhalte erforderlich. Jedes Tool, das Dateien lesen kann, kann Ihren Vault lesen. grep, ripgrep, Pythons pathlib, SQLite FTS5 — sie alle arbeiten direkt mit den Quelldateien. Wenn Sie ein Retrieval-System bauen, indexieren Sie Dateien, nicht API-Antworten. Der Index ist immer konsistent mit der Quelle, weil die Quelle das Dateisystem ist.

Local-first-Architektur. Der Vault liegt auf Ihrem Rechner. Kein Server, keine Cloud-Sync-Abhängigkeit, keine API-Rate-Limits, keine Nutzungsbedingungen, die regeln, wie Sie Ihre eigenen Inhalte verarbeiten. Sie können Ihre Notizen ohne externen Dienst einbetten, indexieren, chunken und durchsuchen. Für AI-Infrastruktur ist das wichtig, weil die Retrieval-Pipeline so schnell läuft, wie Ihre Festplatte es erlaubt, nicht so schnell, wie ein API-Endpoint antwortet. Es ist auch für den Datenschutz wichtig: Persönliche Notizen mit Zugangsdaten, Gesundheitsdaten, Finanzinformationen und privaten Gedanken verlassen nie Ihren Rechner.

Graphstruktur durch wiki-links. Obsidian’s [[wiki-link]]-Syntax erzeugt einen gerichteten Graphen zwischen Notizen. Eine Notiz zur OAuth-Implementierung verlinkt auf Notizen zu Token-Rotation, Session Management und API-Sicherheit. Die Graphstruktur codiert menschlich kuratierte Beziehungen zwischen Konzepten. Vector Embeddings erfassen semantische Ähnlichkeit, aber wiki-links erfassen absichtliche Verbindungen, die der Autor beim Nachdenken über das Thema hergestellt hat. Der Graph ist ein Signal, das Embeddings nicht replizieren können.

Plugin-Ökosystem. Obsidian hat mehr als 2.500 Community-Plugins (Stand März 2026, gegenüber mehr als 1.800 Mitte 2025). Dataview fragt Ihren Vault wie eine Datenbank ab. Templater erzeugt Notizen aus Vorlagen mit JavaScript-Logik. Git-Integration synchronisiert Ihren Vault mit einem Repository. Linter erzwingt konsistente 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 hinweg, wobei frontmatter-Eigenschaften als Felder verwendet und als .base-Dateien gespeichert werden.¹⁵ Diese Plugins geben dem Vault Struktur, ohne das zugrunde liegende Plaintext-Format zu ändern. Das Retrieval-System indexiert die Ausgabe dieser Plugins, nicht die Plugins selbst.

Mehr als 5 Millionen Benutzer. Obsidian hat eine große aktive Community, die Vorlagen, Workflows, Plugins und Dokumentation produziert. Wenn Sie auf ein Problem mit Vault-Organisation oder Plugin-Konfiguration stoßen, hat wahrscheinlich schon 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 Ordner mit Markdown-Dateien hat den Plaintext-Vorteil, aber ihm fehlen drei Dinge, die Obsidian ergänzt:

1. Bidirektionale Links. Obsidian verfolgt Backlinks automatisch. Wenn Sie von Notiz A zu Notiz B verlinken, zeigt Notiz B an, dass Notiz A darauf verweist. Das Graph-Panel visualisiert Verbindungscluster. Dieses bidirektionale Bewusstsein ist 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 reichhaltigen Umgebung; das Retrieval-System indexiert das rohe Markdown.

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

Was Obsidian NICHT leistet (und was Sie bauen)

Obsidian enthält keine Retrieval-Infrastruktur. Es hat einfache Suche (Volltext, Dateiname, Tag), aber keine Embedding-Pipeline, keine Vektorsuche, kein Fusion-Ranking, keinen MCP-Server, kein Credential Filtering, 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 einen einfachen Ordner mit Markdown-Dateien verwenden, funktioniert die Retrieval-Pipeline identisch. Der Chunker liest .md-Dateien. Der Embedder verarbeitet Text-Strings. Der Indexer schreibt in SQLite. Keine dieser Komponenten hängt von Obsidian-spezifischen Funktionen ab. Obsidian trägt die Schreib- und Organisationsumgebung bei, die die Markdown-Dateien erzeugt, die der Retriever indexiert.

Schnellstart: Erster KI-verbundener Vault

In diesem Abschnitt verbinden Sie einen Vault in fünf Minuten mit einem KI-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. Spätere Abschnitte behandeln den Aufbau einer eigenen 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; 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 sich merken können — 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 Durchsuchen 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 bieten sofortigen Vault-Zugriff. Das Ökosystem ist 2025-2026 deutlich gewachsen. Zu den wichtigen jüngeren Updates gehört MCPVault v0.11.0 (März 2026), das list_all_tags zum Scannen von frontmatter und Hashtags mit Zählwerten, eine bessere Handhabung von Ordnern mit Punkten sowie Unterstützung für .base- und .canvas-Dateien ergänzt hat.¹³ Das Paket wurde auf npm außerdem in @bitbonsai/mcpvault umbenannt.

Verschiebung im April 2026 — Obsidian CLI als bevorzugte Brücke: Obsidian 1.12.0 führte die erstklassige CLI ein, und der öffentliche Installer 1.12.7 (23. März 2026) bündelte die Standalone-Binärdatei, TUI und Socket-Datei-Verbesserungen, wodurch Terminal-Workflows leichter zu installieren und auszuführen wurden.¹⁶ Community-Tools migrieren aktiv vom Local REST API-Plugin (das mcp-obsidian antrieb) hin zur CLI-basierten Integration, weil sie schneller und stabiler ist. Das Repo MarkusPfundstein/mcp-obsidian hatte seit Juni 2025 keine Commits und nie getaggte Releases — behandeln Sie es als Wartungsmodus und bevorzugen Sie CLI-basierte Server oder die unten aufgeführten neueren Community-Alternativen.²⁰ Die empfohlene Einrichtung finden Sie später in diesem Leitfaden im Abschnitt „Obsidian CLI für KI-Workflows“.

Für den Schnellstart ist ein dateibasierter Server, der .md-Dateien direkt liest, die einfachste Option:

npm install -g obsidian-mcp-server

Schritt 3: Ihr KI-Tool konfigurieren

Claude Code — zu ~/.claude/settings.json hinzufügen:

{
  "mcpServers": {
    "obsidian": {
      "command": "obsidian-mcp-server",
      "args": ["--vault", "/absolute/path/to/your/vault"]
    }
  }
}

Codex CLI — zu .codex/config.toml hinzufügen:

[mcp_servers.obsidian]
command = "obsidian-mcp-server"
args = ["--vault", "/absolute/path/to/your/vault"]

Cursor — zu .cursor/mcp.json hinzufügen:

{
  "mcpServers": {
    "obsidian": {
      "command": "obsidian-mcp-server",
      "args": ["--vault", "/absolute/path/to/your/vault"]
    }
  }
}

Schritt 4: Ihre erste Abfrage ausführen

Öffnen Sie Ihr KI-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 KI-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 Sie gerade gebaut haben

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

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

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

Obsidian CLI für KI-Workflows

Obsidian 1.12 (Februar 2026) führte ein integriertes Command Line Interface ein, das eine neue Integrationsfläche für KI-Workflows eröffnet.¹⁶ Die CLI funktioniert als Fernsteuerung für die Obsidian-GUI — Obsidian muss laufen (oder wird beim ersten Befehl automatisch gestartet). Aktivieren Sie sie unter Settings > General > Command line interface.

Warum die CLI für KI-Infrastruktur wichtig ist

Die CLI bietet programmatischen Zugriff auf Obsidian-native Vorgänge, die zuvor die GUI oder Plugin-APIs erforderten. Für KI-Workflows sind die wichtigsten Fähigkeiten:

• 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 heraus aus. Die Variante search:context gibt Trefferzeilen mit umgebendem Kontext zurück, was nützlich ist, um Ergebnisse in KI-Prompts einzuspeisen.
• Automatisierung täglicher Notizen. obsidian daily öffnet oder erstellt die heutige tägliche Notiz. Kombiniert mit Shell-Skripting ermöglicht das automatisierte tägliche Briefing-Workflows — ein Hook kann KI-generierte Zusammenfassungen an die tägliche Notiz anhängen.
• Template-basierte Notizerstellung. obsidian template list und obsidian template create erzeugen Notizen aus Templater- oder Core-Templates, sodass KI-Agenten strukturierte Vault-Einträge erstellen können, ohne Markdown-Dateien direkt zu schreiben.
• Eigenschaftsverwaltung. obsidian property set und obsidian property get lesen und schreiben frontmatter-Eigenschaften, sodass Metadaten aus Skripten aktualisiert werden können, ohne YAML zu parsen.
• Plugin-Steuerung. obsidian plugin enable/disable/list verwaltet Plugins programmatisch, was beim Umschalten von Indexierungs-Plugins während Batch-Vorgängen hilfreich ist.
• Aufgabenverwaltung. obsidian task list/add/complete bietet strukturierten Zugriff auf Aufgaben, nützlich für KI-Agenten, die Arbeitselemente im Vault verwalten.

CLI vs. MCP für KI-Zugriff

Die CLI und MCP-Server erfüllen unterschiedliche Rollen und ergänzen sich, statt miteinander zu konkurrieren:

Empfehlung: Nutzen Sie die CLI für Intake-Automatisierung (Notizen erstellen, Eigenschaften verwalten, Obsidian-native Suche ausführen) und MCP für Retrieval (hybride Suche mit Embeddings). Ein PreToolUse-Hook kann obsidian search:context als schnelle Vorprüfung aufrufen, bevor er für gerankte Ergebnisse auf den vollständigen MCP-Retriever zurückfällt.

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 KI-Coding-Agenten direkt in die Vault-Oberfläche ein und bietet damit eine Alternative zur externen MCP-Serverkonfiguration. Diese Plugins führen den KI-Agenten in der Obsidian-Seitenleiste aus, statt eine Verbindung aus einem externen Tool herzustellen.

Claudian

Claudian bettet Claude Code als KI-Mitarbeiter in den Vault ein. Das Vault-Verzeichnis wird zum Arbeitsverzeichnis von Claude und gibt ihm vollständige agentische Fähigkeiten: Dateien lesen und schreiben, Suche, Bash-Befehle und mehrstufige Workflows.¹⁷

Wichtige Funktionen für KI-Infrastruktur: - Kontextbewusste Prompts. Hängt die fokussierte Notiz automatisch an, unterstützt @notename-Dateierwähnungen, tagbasierte Ausschlüsse und die Editor-Auswahl 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 Commands. Erstellen Sie wiederverwendbare Prompt-Vorlagen, die durch /command ausgelöst werden und standardisierte Vault-Operationen ermöglichen. - Berechtigungsmodi. YOLO (automatisch genehmigen), Safe (jede Aktion genehmigen) und Plan (nur planen) mit Sicherheits-Blockliste und Vault-Beschränkung.

Agent Client

Agent Client bringt Claude Code, Codex CLI und Gemini CLI über das Agent Client Protocol (ACP) in eine einheitliche 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 einzubinden, ähnlich wie bei Claudian, aber agentenunabhängig. - Shell-Ausführung. Führen Sie Terminalbefehle direkt im Chat aus — Build-Skripte, git-Befehle oder beliebige Terminaloperationen, ohne die Unterhaltung zu verlassen. - Aktionsfreigabe. Feingranulare Kontrolle über Dateilesevorgänge, Bearbeitungen und Befehlsausführungen.

Wann Agent-Plugins und wann externe MCP sinnvoll sind

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

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 KI nur Kontext zur aktuellen Codebase benötigt, legen Sie ihn in CLAUDE.md, AGENTS.md oder in der Projektdokumentation ab. Diese Dateien reisen mit dem Repo mit und werden automatisch geladen.
• Strukturierte Daten. Wenn Inhalte aus Tabellen, Datensätzen oder Schemas bestehen, verwenden Sie eine Datenbank. Obsidian-Notizen sind primär für Prosa 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 flüchtige Inhalte auf.

Wann Obsidian die richtige Wahl ist

• Wissen über Monate oder Jahre sammeln. 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 eine projektspezifische CLAUDE.md nicht liefern kann.
• Datenschutzsensible Inhalte. Local-first bedeutet, dass die Retrieval-Pipeline keine Inhalte an externe Dienste sendet. Der Vault enthält alles, was Sie hineinlegen, auch Inhalte, die Sie nicht in einen Cloud-Dienst hochladen würden.

Mentales Modell: Drei Schichten

Das System hat drei Schichten, die unabhängig voneinander funktionieren, sich kombiniert aber verstärken. Jede Schicht hat einen anderen Schwerpunkt 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, halbfertige Gedanken ohne Kontext. Die Intake-Schicht ist für die Qualitätskontrolle beim Eingang zuständig. 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: Notizen per Chunking in Sucheinheiten aufteilen, Chunks als Embeddings in den Vektorraum einbetten, für Keyword- und semantische Suche indexieren, Ergebnisse mit RRF zusammenführen. Die Retrieval-Schicht verwandelt ein Dateiverzeichnis in eine abfragbare Wissensbasis. Ohne diese Schicht lässt sich der Vault durch manuelles Browsen und einfache Suche navigieren, ist für KI-Tools aber nicht programmatisch zugänglich.

Integration verbindet die Retrieval-Schicht mit KI-Tools. Ein MCP-Server stellt Retrieval als aufrufbares Tool bereit. Hooks injizieren Kontext automatisch. Skills erfassen neues Wissen zurück im Vault. Die Integrationsschicht ist die Schnittstelle zwischen der Wissensbasis und den KI-Agenten, die sie nutzen.

Die Schichten sind bewusst entkoppelt. Die Intake-Scoring-Pipeline weiß nichts über Embeddings. Der Retriever weiß nichts über Regeln für Signal-Routing. Der MCP-Server weiß nichts darüber, wie Notizen erstellt wurden. Durch diese Entkopplung können Sie jede Schicht unabhängig verbessern. Ersetzen Sie das Embedding-Modell, ohne die Intake-Pipeline zu ändern. Fügen Sie eine neue MCP-Funktion hinzu, ohne den Retriever anzupassen. Ändern Sie die Heuristiken für Signal-Scoring, ohne den Index zu berühren.

Vault-Architektur für KI-Nutzung

Ein Vault, der für KI-Retrieval optimiert ist, folgt anderen Konventionen als ein Vault, der für persönliches Durchsuchen 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 nicht im Retrieval-Index landen sollen.

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 Scan und überspringt passende Pfade vollständig. Dateien in ausgeschlossenen Pfaden werden nie in Chunks aufgeteilt, nie eingebettet und erscheinen nie in Suchergebnissen.

Notizschema

Jede Notiz sollte YAML frontmatter haben. Der Retriever verwendet 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 Suchergebnisanzeige und im Überschriftenkontext für BM25 verwendet
• type — Ermöglicht nach Typ gefilterte Abfragen („zeigen Sie mir nur MOCs“ oder „nur Signale“)
• tags — Wird im FTS5-Überschriftenkontext mit Gewichtung 0,3 indexiert und liefert Keyword-Treffer, auch wenn der Textkörper andere Begriffe verwendet

Optionale, aber wertvolle Felder:

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

Chunking-Konventionen

Der Retriever teilt Inhalte an H2-Überschriftengrenzen (##) in Chunks auf. Das bedeutet: Ihre Notizstruktur wirkt sich direkt auf die Retrieval-Granularität aus.

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 ergeben drei unabhängig durchsuchbare Chunks. Jeder Chunk enthält 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 ergibt einen großen Chunk. Das Embedding mittelt über alle Themen im Abschnitt hinweg. Eine Abfrage zu irgendeinem Unterthema trifft die gesamte Notiz gleichermaßen.

Faustregel: Wenn ein Abschnitt mehr als ein Konzept behandelt, teilen Sie ihn in H2-Unterabschnitte auf. Der Chunker erledigt den Rest.

Was nicht in Notizen gehört

Inhalte, die die Retrieval-Qualität verschlechtern:

• Rohe Copy-pastes ganzer Artikel ohne Annotation. Der Retriever indexiert die Keywords des Originalartikels und verwässert Ihren Vault mit Inhalten, die Sie nicht selbst geschrieben haben. Fügen Sie stattdessen eine Zusammenfassung hinzu, extrahieren Sie die 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-Schlüssel, Tokens, Passwörter, Verbindungsstrings. Selbst mit Credential-Filtering ist der sicherste Ansatz, Secrets niemals 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 dauerhaften Vault gelangt. Nicht kuratierte Auto-Imports erhöhen das Volumen, ohne auffindbaren Wert zu schaffen.

Plugin-Ökosystem für KI-Workflows

Obsidian-Plugins, die die Qualität Ihres Tresors für den KI-Abruf verbessern, fallen in 3 Kategorien: Struktur (Konsistenz erzwingen), Abfragen (Metadaten sichtbar machen) und Sync (den Tresor aktuell halten).

Wichtige Plugins

Dataview. Fragt Ihren Tresor mithilfe von frontmatter-Feldern wie eine Datenbank 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 Abruf nicht direkt, aber es hilft Ihnen, Lücken in der Abdeckung Ihres Tresors 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 vorbefüllt. Konsistentes frontmatter verbessert das Abruf-Filtering.

<%* /* 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 Tresor. 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 den Abruf wichtig sind:

• Überschriftenstufen: 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 Tresor. Verfolgen Sie Änderungen im Zeitverlauf, synchronisieren Sie zwischen Geräten und stellen Sie versehentlich gelöschte Inhalte wieder her. Git liefert außerdem mtime-Daten, die der Indexer für die inkrementelle Änderungserkennung verwendet.

Plugins, die bei der Indexierung helfen

Smart Connections. Ein Obsidian-Plugin, das KI-gestützte semantische Suche direkt in Obsidian bereitstellt. Smart Connections v4 erstellt standardmäßig lokale Embeddings — sobald Ihr Tresor indexiert ist, funktionieren semantische Verbindungen und Lookup vollständig offline ohne API-Aufrufe.¹¹ v4.5.0 (5. Mai 2026) macht Footer-Verbindungen zu einem Teil von Smart Connections Core, sodass jede Installation verwandte Notizen im Footer anzeigen kann, ohne ein Seitenpanel zu öffnen. Neuere v4-Versionen haben außerdem Graph-Ansichten für Verbindungslisten, konfigurierbare Dock-Positionen, verbesserte Wiederherstellung von Block-Embeddings nach unterbrochenen Indexierungsläufen und „Substrate“ ergänzt, eine pluginübergreifende Umgebung, in der Smart Connections, Smart Chat und Smart Composer gemeinsamen Zustand teilen können.²¹ Während das Abrufsystem in diesem Guide extern zu Obsidian ist (es läuft als Python-Pipeline), ist Smart Connections nützlich, um beim Schreiben semantische Beziehungen zu erkunden. Beide Systeme indexieren dieselben Inhalte, dienen aber unterschiedlichen Anwendungsfällen: Smart Connections für Entdeckung im Editor, der externe Retriever für die Integration von KI-Tools über MCP.

KI-native Plugins, die im April 2026 erschienen sind. Eine Welle neuer Community-Plugins zielt direkt auf den Claude Code- / Codex- / Gemini-CLI-Workflow:

Behandeln Sie dies als neu entstehende Oberfläche — mehrere dieser Plugins werden sich in den nächsten Quartalen wahrscheinlich konsolidieren oder in Smart Connections / den Obsidian-Kern aufgenommen werden. Wenn Sie heute eines auswählen, liegen VaultSearch und Hybrid Search MCP philosophisch am nächsten am externen Retriever dieses Guides.

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

Metadata Menu. Bietet strukturierte frontmatter-Bearbeitung mit Autocomplete für Feldwerte. Reduziert Tippfehler in den Feldern type, domain und tags. Konsistente Metadaten verbessern die Genauigkeit des Abruf-Filterings.

Plugins, die der Indexierung schaden

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

Kanban. Speichert den Board-Zustand als speziell formatiertes Markdown. Das Format ist für Kanban-Rendering gedacht, nicht für den Abruf von Fließtext. Der Chunker erzeugt Fragmente aus 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 Chunks mit geringer Qualität. Wenn Sie tägliche Notizen verwenden, schreiben Sie substanzielle Inhalte hinein oder schließen Sie den Ordner für tägliche Notizen vom Index aus.

Plugin-Konfiguration, die wichtig ist

Dateiwiederherstellung → Aktiviert. Schützt vor versehentlichem Löschen von Notizen. Nicht direkt mit Abruf verbunden, aber entscheidend für eine Wissensdatenbank, auf die Sie sich verlassen.

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

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

Wiki-link-Format → Kürzester Pfad, wenn möglich. Kürzere Linkziele lassen sich vom Retriever beim Indexieren der Linkstruktur leichter auflösen.

Embedding-Modelle: Auswahl und Konfiguration

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

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 Layers)

Model2Vec destilliert das Wissen eines Sentence Transformers in statische Token Embeddings. Statt Attention Layers über die Eingabe laufen zu lassen (wie BERT, MiniLM und andere Transformer-Modelle), erzeugt Model2Vec Vektoren durch gewichtete Mittelung vorab berechneter 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 Vorteile bei Geschwindigkeit und Einfachheit. Bei kurzen Markdown-Chunks (durchschnittlich 200-400 Wörter in einem typischen Obsidian-Tresor) fällt der Qualitätsunterschied weniger stark aus als bei längeren Dokumenten, weil beide Modelle bei kurzem, fokussiertem Text 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 beim ersten Gebrauch geladen, nicht zur Importzeit. Der Import 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 eigenen venv (z. B. ~/.claude/venvs/memory/), um Abhängigkeitskonflikte mit dem restlichen 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 Sie Alternativen wählen sollten

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

Wählen Sie potion-retrieval-32M, wenn Ihr Hauptanwendungsfall Retrieval ist (was auf die Tresorsuche zutrifft). Diese Variante wurde aus potion-base-32M speziell für Retrieval-Aufgaben feinabgestimmt und erzielt in der Retrieval-Benchmark-Tabelle von Model2Vec 35,06 gegenüber 32,67 für potion-base-32M.⁸ Der Trade-off: Sie ist für Retrieval optimiert, nicht für allgemeine Embedding-Qualität.

Wählen Sie potion-multilingual-128M, wenn Ihr Tresor 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 beliebigen Text in jeder Sprache und behält dabei dieselbe reine numpy-Abhängigkeit wie andere potion-Modelle.¹² Die größere Modelldatei (~500 MB) ist der Trade-off für sprachübergreifende Fähigkeiten. Nutzen Sie dieses Modell, 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 SQLite-Datenbankgröße im Vergleich zu 256-dimensionalen Vektoren um ~50 %. Die Embedding-Geschwindigkeit sinkt bei einem vollständigen Reindex 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 akzeptable Trade-offs sind. Das API erzeugt Embeddings mit der höchsten Qualität, führt aber eine Cloud-Abhängigkeit, Kosten pro Token (0,02 $/Million Tokens) ein und sendet Ihre Inhalte an die Server von OpenAI.

Bleiben Sie in allen anderen Fällen bei potion-base-8M. Der Geschwindigkeitsvorteil ist für iteratives Indexing entscheidend (Reindex 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 tragen die meisten Informationen. Eine Reduktion von 256 auf 128 Dimensionen halbiert den Vektorspeicher mit minimalem Qualitätsverlust beim Kurztext-Retrieval.

Model2Vec v0.8.x aktualisiert Tokenizer- und Persistenz-Interna, deprecatet Python 3.9-Support und aktualisiert die veröffentlichten Ergebnisse auf die neueren MTEB-Tabellen. Pinnen oder testen Sie model2vec, bevor Sie einen Produktions-Indexer aktualisieren, weil Library-Upgrades Modellladepfade ändern können, selbst wenn der Name des Embedding-Modells gleich bleibt.¹⁰

Fine-Tuning für tresorspezifische Embeddings

Model2Vec v0.4.0+ unterstützt das Training benutzerdefinierter Klassifikationsmodelle auf statischen Embeddings, v0.7.0 ergänzt Vokabularquantisierung und konfigurierbares Pooling für die Destillation, und v0.8.x refaktoriert Tokenizer- und Persistenzverhalten.¹⁰ Das ist relevant für Tresore 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 Tresore liefert das Standardmodell potion-base-8M ausreichende Retrieval-Qualität. Fine-Tuning lohnt sich nur, wenn das Retrieval regelmäßig domänenspezifische Verbindungen verfehlt, die ein Allzweckmodell nicht erfassen kann.

Modell-Hash-Tracking

Der Indexer speichert einen Hash, der aus Modellname und Vokabulargröße abgeleitet wird. Wenn Sie das Embedding-Modell ändern, erkennt der Indexer die Abweichung beim nächsten inkrementellen Lauf und stößt automatisch einen vollständigen Reindex an.

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 aus unterschiedlichen Modellen 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, Unternehmensfirewall), 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 leeren, haben die gespeicherten Vektoren eine andere Dimension als neue Embeddings. Der Indexer erkennt das über den Modell-Hash und stößt einen vollständigen Reindex an. Wenn die Hash-Prüfung fehlschlägt (benutzerdefiniertes Modell ohne korrekten Hash), gibt sqlite-vec bei KNN-Abfragen mit abweichenden Dimensionen einen Fehler aus.

Speicherdruck bei großen Tresoren. Das Einbetten von mehr als 50.000 Chunks in einem einzigen Batch kann erheblichen Speicher verbrauchen. Der Indexer verarbeitet Batches von 64, um den Spitzenspeicherbedarf 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 konkreten 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. Dadurch halbiert sich der Speicherbedarf, allerdings muss FTS5 manuell synchronisiert werden, wenn Chunks eingefügt, aktualisiert oder gelöscht werden.

Spalten. Drei Spalten werden indexiert: - chunk_text — Der Hauptinhalt jedes Chunks (BM25-Gewichtung: 1,0) - section — Der H2-Überschriftstext (BM25-Gewichtung: 0,5) - heading_context — Notiztitel, Tags und Metadaten (BM25-Gewichtung: 0,3)

BM25-Ranking

BM25 bewertet Dokumente nach Begriffshäufigkeit, inverser Dokumenthäufigkeit und Normalisierung der Dokumentlänge. Die Hilfsfunktion bm25() in FTS5 akzeptiert Gewichtungen pro Spalte:

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: - Eine Keyword-Übereinstimmung in chunk_text trägt am meisten zum Score bei - Eine Übereinstimmung in section (Überschrift) trägt halb so viel bei - Eine Übereinstimmung in heading_context (Titel, Tags) trägt 30 % so viel bei

Diese Gewichtungen sind anpassbar. Wenn Ihr Vault aussagekräftige Überschriften hat, die die Inhaltsqualität stark vorhersagen, erhöhen Sie die Gewichtung von section. Wenn Ihre Tags umfassend und präzise sind, erhöhen Sie die Gewichtung von 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 solchen 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 konzeptuelle Diskussion.

Wann BM25 scheitert

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

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

Bei großer Skalierung scheitert BM25 außerdem an Keyword-Kollisionen. In einem Vault mit 15.000 Dateien findet eine Suche nach “configuration” Hunderte von Notizen, weil nahezu 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 Vaults mit erheblichem CJK-Inhalt (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 Erweiterung sqlite-vec bringt Vector-KNN-Suche (K-Nearest Neighbors) in SQLite. Dieser Abschnitt behandelt die sqlite-vec-Konfiguration, die Embedding-Pipeline von der Notiz zum durchsuchbaren Vektor und die konkreten Query-Muster.

Virtuelle sqlite-vec-Tabelle

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

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

Embedding-Pipeline

Die Pipeline führt 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

Vektorserialisierung

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

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 anschließend die K nächstgelegenen 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 approximative 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-Pagination mit Distanzbeschränkungen

Seit sqlite-vec v0.1.7 unterstützen KNN-Queries WHERE distance < ?-Beschränkungen. Dadurch wird cursorbasierte Pagination 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 statt neuer Query-Modell-Releases; daher bleibt v0.1.7 die Funktionsgrenze für dieses Pagination-Muster.²³

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

Das ersetzt das frühere Muster, ein großes k abzurufen und in Python zu slicen, wodurch bei explorativen Queries über große Vaults weniger Speicher benötigt wird.

DELETE-Unterstützung in vec0-Tabellen

sqlite-vec v0.1.7 hat native DELETE-Unterstützung für virtuelle vec0-Tabellen hinzugefügt, und v0.1.9 hat einen DELETE-Fehlerpfad behoben, der Metadaten-Textspalten mit mehr als 12 Zeichen betraf.¹⁴²³ Zuvor mussten zum Entfernen von Vektoren Tabellen gelöscht und neu erstellt werden. 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 Neuindizierung, wenn Notizen gelöscht oder verschoben werden. Der Indexer muss keine Shadow-Tabelle für „aktive IDs“ und keine Batch-Rebuilds mehr verwalten.

Wann Vector Search gewinnt

Vector Search eignet sich besonders für Queries, bei denen das Konzept wichtiger ist als die konkreten Wörter:

• Query: “how to handle authentication failures” → Findet Notizen zu “login error recovery” (gleicher semantischer 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 die eigentliche Funktionsdefinition aber niedriger einstufen als konzeptuelle Diskussionen
• Query: PostToolUse → Gibt eher Notizen zu “tool lifecycle hooks” und “post-execution handlers” zurück als zum 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 ausführt. Ist die Funktion deaktiviert, verwenden alle Suchen ausschließlich BM25, und der RRF-Fusion-Schritt wird übersprungen.

Reciprocal Rank Fusion (RRF)

RRF führt zwei Ranglisten zusammen, ohne dass dafür eine Score-Kalibrierung nötig ist. Dieser Abschnitt behandelt den Algorithmus, eine durchgearbeitete Query-Ablaufverfolgung, 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 Ergebnisliste i - weight_i ist ein optionaler Multiplikator pro Liste (Standardwert 1.0)

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

Warum RRF statt Alternativen

Gewichtete lineare Kombination erfordert, BM25-Scores gegen Kosinusdistanzen zu kalibrieren. BM25-Scores sind unbegrenzt und skalieren mit der Korpusgröße. Kosinusdistanzen sind auf [0, 2] begrenzt. Ihre Kombination erfordert Normalisierung, und die Normalisierungsparameter hängen vom jeweiligen Datensatz ab. RRF verwendet nur Rangpositionen, die unabhängig von der Scoring-Methode immer ganze Zahlen ab 1 sind.

Gelernte Fusionsmodelle benötigen gelabelte Trainingsdaten — also Relevanzpaare aus Query und Dokument. Für eine persönliche Wissensdatenbank 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-Methode) sind theoretisch elegant, aber komplexer zu implementieren und abzustimmen. Das ursprüngliche RRF-Paper zeigte, dass RRF Condorcet-Methoden auf TREC-Evaluierungsdaten ü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 (dort kommt “review” prominenter vor). Die Vektorsuche 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 erscheinen, erhalten einen Single-Source-Score und fallen unter Ergebnisse, die in beiden Listen gerankt sind. Die eigentliche Logik zur Konfliktlösung gewinnt, weil beide Methoden sie gefunden haben — BM25 über Keywords, die Vektorsuche über Semantik.

Die vollständige Schritt-für-Schritt-Ablaufverfolgung mit RRF-Berechnung 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

Tuning von k

Die Konstante k steuert, wie viel Gewicht Top-Ergebnissen im Vergleich zu Ergebnissen auf niedrigeren Rängen gegeben wird:

• Niedrigeres k (z. B. 10): Top-Ergebnisse dominieren. Rang 1 erzielt 1/11 = 0.091, Rang 10 erzielt 1/20 = 0.050 (1,8-facher Unterschied). Gut geeignet, wenn Sie den einzelnen Rankern zutrauen, das beste Ergebnis richtig 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, sodass 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 — nahezu identisch. Verwenden Sie dies, wenn die einzelnen Ranker verrauschte Rankings erzeugen, die Übereinstimmung zwischen Listen aber zuverlässig ist.

Beginnen Sie mit k=60. Das ursprüngliche RRF-Paper stellte fest, dass dieser Wert über verschiedene 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 gleichem 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 erscheinen, gegenüber Chunks, die nur in einer Liste erscheinen
2. Bevorzugen Sie unter Chunks in beiden Listen denjenigen mit dem niedrigeren kombinierten Rang
3. Bevorzugen Sie unter Chunks in nur einer Liste denjenigen 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, Token-Budget-Kürzung 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 Such-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

Token-Budget-Kürzung

Der Parameter max_tokens verhindert, dass der Retriever mehr Kontext zurückgibt, als das AI-Tool nutzen kann. Die Schätzung verwendet 4 Zeichen pro Token (eine vernünftige Annäherung für englische Prosa). Ergebnisse werden gierig gekürzt: Ergebnisse werden in Rangfolge hinzugefügt, bis das Budget erschö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, schwächeren Ergebnissen vorziehen. Der gierige Ansatz ist einfacher und funktioniert in der Praxis gut, weil das RRF-Ranking die Ergebnisse bereits nach Relevanz ordnet.

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 die Fähigkeiten bei der Initialisierung und passt seine Abfragestrategie an. Eine fehlende Komponente mindert 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. Er scannt den Vault nach allen .md-Dateien in erlaubten Ordnern
2. Er liest mtime_ns für jede Datei aus dem Dateisystem
3. Er vergleicht den Wert mit dem gespeicherten mtime_ns in der Datenbank
4. Er identifiziert 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, kein Content Hash

Content Hashing (SHA-256 des Dateiinhalts) wäre zuverlässiger als der mtime-Vergleich — 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). Allerdings erfordert Hashing, 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 Neuindizierungen unveränderter Dateien aus (False Positives), übersieht aber nie tatsächliche Ä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 gegen vec0-Tabellen mit längeren Metadaten-Textspalten.¹⁴²³ Frühere Versionen erforderten Workarounds (das Löschen und Neuerstellen der virtuellen Tabelle oder die Pflege eines externen Sets „aktiver IDs”). Wenn eine Version vor 0.1.9 läuft, führen Sie vor dem Verlassen auf direkte Deletes in metadatenlastigen Schemas ein Upgrade durch.

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.

Inkrementeller vs. vollständiger Reindex

Der Indexer unterstützt zwei Modi: inkrementell (schnell, tägliche Nutzung) und vollständig (langsam, gelegentlich). Dieser Abschnitt erklärt, wann Sie welchen Modus verwenden sollten, welche Idempotenzgarantien gelten und wie Sie beschädigte Datenbanken wiederherstellen.

Inkrementeller Reindex

Wann verwenden: Für die tägliche Indizierung nach dem Bearbeiten von Notizen. Dies ist der Standardmodus.

Was passiert: 1. Vault auf Dateiänderungen scannen (mtime-Vergleich) 2. Chunks für gelöschte Dateien löschen 3. Geänderte Dateien erneut chunken und 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ändiger Reindex

Wann verwenden: - Nach dem Wechsel des Embedding-Modells (Modell-Hash-Abweichung erkannt) - Nach einer Schema-Migration (neue Spalten, geänderte Indizes) - Nach einer Datenbankbeschädigung (Integritätsprüfung schlägt fehl) - Wenn die inkrementelle Indizierung unerwartete Ergebnisse liefert

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

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

python index_vault.py --full

Idempotenz

Beide Modi sind idempotent: Wenn Sie denselben Befehl zweimal ausführen, entsteht dasselbe Ergebnis. Der Indexer löscht vorhandene Chunks für eine Datei, bevor neue eingefügt werden. Eine erneute inkrementelle Indizierung auf einer bereits aktuellen Datenbank erzeugt daher keine Änderungen. Eine erneute vollständige Indizierung erzeugt eine identische Datenbank.

Wiederherstellung nach Beschädigung

Wenn die SQLite-Datenbank beschädigt wird (Stromausfall während des Schreibens, Festplattenfehler, 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 aufgebaut 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. Falls er abweicht, automatisch in den vollständigen Reindex-Modus wechseln und den Benutzer warnen.
2. Dateiscan. Zulässige Ordner durchlaufen, Dateipfade und mtimes erfassen.
3. Änderungserkennung. Mit gespeicherten Daten vergleichen.
4. Batch-Verarbeitung. Geänderte Dateien in Batches von 64 erneut chunken und einbetten.
5. Fortschritt melden. Anzahl der verarbeiteten Dateien und verstrichene Zeit ausgeben.
6. Geordnetes Herunterfahren. SIGINT behandeln, indem die aktuelle Datei vor dem Stoppen fertig verarbeitet wird.

Credential Filtering und Datengrenzen

Persönliche Notizen enthalten Geheimnisse: API-Schlüssel, Bearer-Tokens, Datenbankverbindungszeichenfolgen, 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 gechunkt, 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.

Pattern-basierte Filterung

Der Credential-Filter läuft vor der Speicherung über jeden Chunk und gleicht ihn mit 25 anbieterspezifischen Patterns plus generischen Patterns ab:

Anbieterspezifische Patterns:

Generische Patterns:

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 Einbetten filtern. Der bereinigte Text wird eingebettet. Die Vektorrepräsentation codiert niemals Credential-Patterns. Eine Abfrage nach “API key” gibt Notizen zurück, die API-Schlüsselverwaltung besprechen, nicht Notizen, die echte Schlüssel enthalten.

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

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

Pfadbasierter Ausschluss

Die Datei .indexignore bietet einen groben Ausschluss nach Pfad. Der Credential-Filter sorgt für feingranulares Scrubbing innerhalb indizierter Dateien. Beides ist notwendig:

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

Datenklassifizierung

Für Vaults mit vielfältigen 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.

Protokollwahl: 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. Das ist nützlich für Remote-Zugriff, Multi-Client-Setups oder Teamkonfigurationen, bei denen der Vault auf einem gemeinsam genutzten Server liegt.

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

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

MCP-Spezifikationsentwicklung. Die MCP-Spezifikation vom Juni 2025 ergänzte OAuth 2.1-Autorisierung, strukturierte Tool-Ausgaben (typisierte Rückgabeschemata) und Elicitation (serverinitiierte Benutzeraufforderungen). Die Veröffentlichung vom November 2025 brachte Streamable HTTP als vollwertigen Transportmodus, .well-known-URL-Discovery zum automatischen Durchsuchen von Serverfunktionen, strukturierte Tool-Annotationen, die deklarieren, ob ein Tool schreibgeschützt ist oder Änderungen vornimmt, sowie ein SDK-Standardisierungssystem mit Stufen.⁷⁹ Die nächste Spezifikationsveröffentlichung (vorläufig Mitte 2026) schlägt asynchrone Operationen für lang laufende Aufgaben, domänenspezifische Protokollerweiterungen für Branchen wie Gesundheitswesen und Finanzwesen sowie Standards für Agent-to-Agent-Kommunikation in Multi-Agent-Workflows vor.⁹ Für persönliche Vault-Server bleibt STDIO der einfachste Weg. Der Streamable HTTP-Transport und die .well-known-Discovery nützen vor allem HTTP-Bereitstellungen in Unternehmen mit Multi-Tenant-Routing und Lastverteilung. Beobachten Sie die MCP-Roadmap, um Aktualisierungen zu verfolgen, die Ihre Transportwahl beeinflussen.

Funktionsdesign

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

search — Das primäre Tool. Führt hybrid Retrieval aus und gibt gerankte 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 des 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 für die Exploration, wenn der Agent keine konkrete Suchanfrage 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 Komfort-Tool, das eine Suche ausführt und die Ergebnisse als Kontextblock formatiert, der sich in eine Konversation einfügen lässt.

{
  "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, ändert oder löscht keine Notizen. Schreiboperationen (das Erfassen neuer Notizen) werden von separaten Hooks oder Skills verarbeitet, nicht vom MCP-Server.

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

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

4. Token-begrenzte 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 Verbraucher des Obsidian-Retrieval-Systems. Dieser Abschnitt behandelt die MCP-Konfiguration, die Hook-Integration und das obsidian_bridge.py-Muster.

MCP-Konfiguration

Fügen Sie den Obsidian-MCP-Server zu ~/.claude/settings.json hinzu:

{
  "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 neu, nachdem Sie die Konfiguration hinzugefügt haben. Der MCP-Server startet als Child-Prozess. 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 definierten Punkten im Lebenszyklus. Für die Obsidian-Integration sind 2 Hooks relevant:

PreToolUse-Hook — Fragt den Vault ab, bevor der Agent einen Tool-Aufruf verarbeitet. Relevanter Kontext wird automatisch eingefügt.

#!/bin/bash
# ~/.claude/hooks/pre-tool-use/obsidian-context.sh
# Automatically inject vault context before tool execution

TOOL_NAME="$1"
PROMPT="$2"

# Only inject context for code-related tools
case "$TOOL_NAME" in
    Edit|Write|Bash)
        # Query the vault
        CONTEXT=$(python /path/to/retriever.py search "$PROMPT" --limit 3 --max-tokens 1500)
        if [ -n "$CONTEXT" ]; then
            echo "---"
            echo "Relevant vault context:"
            echo "$CONTEXT"
            echo "---"
        fi
        ;;
esac

PostToolUse-Hook — Erfasst wichtige Tool-Ausgaben zurück im Vault, damit sie später wieder abgerufen werden können.

#!/bin/bash
# ~/.claude/hooks/post-tool-use/capture-insight.sh
# Capture significant outputs to vault (selective)

TOOL_NAME="$1"
OUTPUT="$2"

# Only capture substantial outputs
if [ ${#OUTPUT} -gt 500 ]; then
    python /path/to/capture.py --text "$OUTPUT" --source "claude-code-$TOOL_NAME"
fi

Das obsidian_bridge.py-Muster

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 /capture-Skill

Ein Claude Code-Skill, um Erkenntnisse zurück im Vault zu erfassen:

/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 Neuindexierung 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 aufgebaut, die den Vault sowohl als Lesequelle als auch als Schreibziel behandeln.

Signal-Scanning. Ein /scan-intel-Befehl fragt externe Quellen ab, bewertet Funde anhand persönlicher Forschungsinteressen und schreibt passende 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, Handlungsrelevanz, Tiefe, Autorität) und schreibt Signale, die den Schwellenwert erreichen, in themenspezifische Vault-Ordner. Der Vault wird damit zum nachgelagerten Verbraucher einer automatisierten Intelligence-Pipeline.

Captain’s log. Ein /captains-log-Befehl aggregiert die tägliche git-Aktivität über alle Repositorys hinweg, schreibt einen strukturierten Journaleintrag in den Vault und enthält getroffene Entscheidungen, Erkenntnisse und offene Themen:

/captains-log

Der Befehl zieht die Commit-Historie aus GitHub, gruppiert sie nach Repository und formatiert sie als narrativen Journaleintrag. Mit der Zeit entsteht durch die täglichen Logs ein durchsuchbarer Verlauf dessen, was ausgeliefert wurde und warum.

Obsidian-Erfassung. Ein /obsidian-capture-Befehl nimmt 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 angesammelten Tageslogs erzeugen.

Community-Beispiele. Praktiker veröffentlichen ihre Befehlsbibliotheken. Ein Entwickler teilte 22 benutzerdefinierte Obsidian- + Claude Code-Befehle für Tagesrückblicke, Projektplanung, Forschungserfassung und Content-Workflows.¹ Ein anderer baute einen „Visual Explainer“-Skill, der aus Code-Analysen Diagrammnotizen im Vault erzeugt.² Die Befehle unterscheiden sich, aber die Architektur bleibt gleich: Claude Code-Skills als Schnittstelle, Vault-Notizen als Speicherschicht und Retrieval-Infrastruktur als Abfrage-Engine.

Kontextfenster-Management

Die Integration sollte das Kontextfenster von Claude Code berücksichtigen:

• Begrenzen Sie eingefügten Kontext auf 1.500-2.000 Tokens pro Abfrage. Mehr konkurriert mit dem Arbeitsspeicher des Agenten.
• Fügen Sie Quellenangaben hinzu. Geben Sie immer den Dateipfad und die Abschnittsüberschrift an, damit der Agent die Quelle referenzieren kann.
• Kürzen Sie Chunk-Text. Lange Chunks sollten mit ... gekürzt werden, statt sie vollständig auszulassen. Die ersten 300-500 Zeichen enthalten meist die wichtigsten Informationen.
• Nicht bei jedem Tool-Aufruf einfügen. Der PreToolUse-Hook sollte Kontext selektiv einfügen, abhängig davon, welches Tool aufgerufen wird. Leseoperationen benötigen keinen Vault-Kontext. Write- und Edit-Operationen profitieren davon.

Codex-CLI-Integration

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

MCP-Konfiguration

Fügen Sie Folgendes zu .codex/config.toml oder ~/.codex/config.toml hinzu:

[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. Nehmen Sie Hinweise zur Vault-Suche auf:

## 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

Wichtigster Unterschied: Codex CLI unterstützt keine Hooks. Das Muster zur automatischen Kontexteinfügung (PreToolUse-Hook) ist nicht verfügbar. Nehmen Sie stattdessen explizite Anweisungen in AGENTS.md auf, die den Agenten anweisen, den Vault vor Arbeitsbeginn zu durchsuchen.

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 für gängige Tools.

Cursor

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

{
  "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 Nutzung 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

Der CLI gibt strukturierten Text aus, den Sie manuell in die Eingabe eines beliebigen AI-Tools einfügen können. Das ist weniger elegant als eine MCP-Integration, funktioniert aber 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

Anstatt bei jeder Interaktion nach Kontext zu suchen, bauen Sie Kontextblöcke aus gut strukturierten Vault-Notizen vorab auf 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 Time-to-Live. Wenn die TTL abläuft, wird der Block durch erneute Abfrage des Vaults neu erstellt.
2. Erkennung von Vault-Änderungen. Wenn der Indexer Änderungen an Dateien erkennt, 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 auf. Dieser hybride Ansatz gibt dem Agent eine Grundlage aus häufig benötigtem Kontext und bewahrt zugleich Budget für spezifische Abfragen.

Tokenverbrauch vorher/nachher

Ohne Caching: Jede relevante Abfrage löst eine Vault-Suche aus, die 1.500-2.000 Tokens Kontext zurückgibt. Über 10 Abfragen in einer Sitzung verbraucht der Agent 15.000-20.000 Tokens an Vault-Kontext.

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

PostToolUse-Hooks für Kontextkomprimierung

Tool-Ausgaben können ausführlich sein: Stacktraces, Dateiauflistungen, Testergebnisse. Ein PostToolUse-Hook kann diese Ausgaben komprimieren, bevor sie Platz im Kontextfenster verbrauchen.

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 Tokens, aber das Signal steckt in 2 Zeilen: 200 bestanden, 1 fehlgeschlagen.

Hook-Implementierung

#!/bin/bash
# ~/.claude/hooks/post-tool-use/compress-output.sh
# Compress verbose tool outputs to preserve context window

TOOL_NAME="$1"
OUTPUT="$2"
OUTPUT_LEN=${#OUTPUT}

# Only compress large outputs
if [ "$OUTPUT_LEN" -lt 2000 ]; then
    exit 0  # Pass through unchanged
fi

case "$TOOL_NAME" in
    Bash)
        # Compress test output
        if echo "$OUTPUT" | grep -q "PASSED\|FAILED"; then
            PASSED=$(echo "$OUTPUT" | grep -c "PASSED")
            FAILED=$(echo "$OUTPUT" | grep -c "FAILED")
            FAILURES=$(echo "$OUTPUT" | grep "FAILED")
            echo "Tests: $PASSED passed, $FAILED failed"
            if [ "$FAILED" -gt 0 ]; then
                echo "Failures:"
                echo "$FAILURES"
            fi
        fi
        ;;
esac

Vermeidung rekursiver Trigger

Ein Komprimierungs-Hook, der Ausgabe erzeugt, könnte sich selbst auslösen, wenn er nicht abgesichert ist:

# Guard against recursive invocation
if [ -n "$COMPRESS_HOOK_ACTIVE" ]; then
    exit 0
fi
export COMPRESS_HOOK_ACTIVE=1

Komprimierungsheuristiken

Pipeline für Signalaufnahme und Triage

Die Aufnahmeschicht entscheidet, was in den Vault gelangt. Ohne Kuratierung sammelt der Vault Rauschen an. Dieser Abschnitt behandelt die Scoring-Pipeline, die Signale in Domänenordner weiterleitet.

Quellen

Signale kommen aus mehreren Kanälen:

• RSS-Feeds: Technische Blogs, Sicherheitshinweise, Release Notes
• Lesezeichen über Web Clipper: Die offizielle Obsidian Web Clipper-Erweiterung (Chrome, Firefox, Safari) ist der hochwertigste Aufnahmepfad für browserseitige Erfassung. Der Release-Zyklus im April 2026 machte sie für AI-Workflows deutlich nützlicher:²²
  • 1.4.0 (9. Apr.): Interaktive YouTube-Transkript-UI — Video anheften, durch das Transkript scrubben, automatisch scrollen und die aktuelle Position hervorheben. Dazu eine Standardoption „Open in Reader“, die eine Ein-Klick-Erfassung direkt in den Reader-Modus sendet.
  • 1.5.0–1.5.1 (15. Apr.): Highlights-Viewer — erfasste Highlights im gesamten Vault durchsuchen und ansehen. Fade-in-Übergang in den Reader. Flüssigere YouTube-Wiedergabe/Pause. 1.5.1 behob eine Regression bei der webpack-Kompilierung.
  • 1.6.0–1.6.2 (21.–23. Apr.): Überarbeitete Highlighter-UX mit Mobile-Support. Defuddle 0.18 ergänzt quellenspezifische Extractors für LinkedIn, Threads, Bluesky, Discourse und Medium. 1.6.2 behebt eine Clipboard-Regression im eingebetteten Modus von Safari. Konfigurieren Sie Templates pro Quelldomäne, damit YouTube-Transkripte, GitHub READMEs und Longform-Artikel jeweils in einer sinnvoll benannten Notiz mit dem passenden frontmatter für die folgende Scoring-Pipeline landen.
• Newsletter: Wichtige Auszüge aus E-Mail-Newslettern
• Manuelle Erfassung: Notizen, die beim Lesen, in Gesprächen oder während der Recherche entstehen
• Tool-Ausgabe: Bedeutende Ausgaben von AI-Tools, die über Hooks erfasst werden
• iOS Share Extension: Obsidian’s iOS-App (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.¹⁹ Dadurch entsteht ein reibungsarmer mobiler Aufnahmepfad — teilen Sie einen Artikel aus Safari, und er erscheint als Vault-Notiz, bereit für das Scoring.
• Obsidian CLI: Shell-Skripte und Hooks können über obsidian file create Notizen erstellen oder über obsidian file append bestehende Notizen erweitern, wodurch automatisierte Aufnahmepipelines auf dem Desktop möglich werden.

Scoring-Dimensionen

Jedes Signal wird anhand von 4 Dimensionen bewertet (jeweils 0,0 bis 1,0):

Gesamt-Score und Routing

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

Domänen-Routing

Signale mit einem Score über 0,55 werden anhand von Keyword-Matching und Themenklassifizierung in einen von 12 Domänenordnern geroutet:

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

Über 14 Monate Betrieb:

Knowledge-Graph-Muster

Obsidian’s wiki-link-Graph codiert Beziehungen zwischen Notizen. Dieser Abschnitt behandelt Link-Semantik, Graph-Traversal zur Kontexterweiterung und Anti-Patterns, die die Graph-Qualität verschlechtern.

Backlink-Semantik

Jeder wiki-link erzeugt eine gerichtete Kante im Graph. Obsidian verfolgt sowohl Forward Links als auch backlinks:

• Forward Link: Notiz A enthält [[Note B]] → A verlinkt auf B
• Backlink: Notiz B zeigt an, dass Notiz A auf sie verweist

Der Graph codiert je nach Kontext unterschiedliche Arten von Beziehungen:

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 Retrieval auf 2 Arten:

1. Direkter Treffer. Eine Suche nach „authentication overview“ trifft auf den MOC selbst und liefert dem Agenten eine kuratierte Liste verwandter Notizen.
2. Kontexterweiterung. Nachdem eine konkrete Notiz gefunden wurde, kann der Retriever prüfen, ob die Notiz in MOCs auftaucht, und die Struktur des MOC in die Ergebnisse aufnehmen. So erhält der Agent eine Karte des größeren Themenbereichs.

Graph-Traversal zur Kontexterweiterung

Eine zukünftige Erweiterung des Retrievers: Nach dem Finden der Top-Ergebnisse wird der Kontext erweitert, indem Links gefolgt wird:

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 Graph-Struktur dar.

Anti-Patterns

Verwaiste Cluster. Gruppen von Notizen, die untereinander verlinkt sind, aber keine Verbindungen zum restlichen Vault haben. Das Graph-Panel in Obsidian macht sie als getrennte Inseln sichtbar. Verwaiste Cluster weisen auf fehlende MOCs oder fehlende domänenübergreifende Links hin.

Tag-Wildwuchs. Tags werden inkonsistent verwendet oder es entstehen zu viele feingranulare Tags. Ein Vault mit 500 eindeutigen Tags über 5.000 Notizen hinweg kommt im Durchschnitt auf 1 Notiz pro 10 Tags — die Tags sind zum Filtern nicht nützlich. Konsolidieren Sie sie auf 20-50 übergeordnete Tags, die Ihren Domänenordnern entsprechen.

Link-lastige, inhaltsarme Notizen. Notizen, die vollständig aus wiki-links bestehen und keine Prosa enthalten. Diese Notizen lassen sich schlecht indexieren, weil der Chunker keinen Text zum Einbetten hat. Ergänzen Sie mindestens einen Absatz Kontext, der erklärt, warum die verlinkten Notizen zusammenhängen.

Bidirektionale Links für alles. Nicht jeder Verweis braucht einen wiki-link. Eine beiläufige Erwähnung von „OAuth“ erfordert nicht [[OAuth 2.0 Overview]]. Reservieren Sie wiki-links für absichtliche, navigierbare Beziehungen, bei denen ein Klick auf den Link nützlichen Kontext liefern würde.

Rezepte für Developer Workflows

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

Morgenlicher Kontextabruf

Starten Sie den Tag, indem Sie relevanten Kontext laden:

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

Der Retriever liefert aktuelle Notizen zu Ihrem aktiven Projekt und gibt Ihnen so eine schnelle Auffrischung dazu, wo Sie aufgehört haben. Das ist effektiver, als die Commit-Nachrichten von gestern erneut zu lesen.

Recherche während des Codings erfassen

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 für zukünftiges Retrieval bereit. Über Monate hinweg entsteht aus diesen Mikroerfassungen ein Korpus von implementierungsspezifischem Wissen.

Projektstart

Wenn Sie ein neues Projekt oder eine neue Funktion starten:

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

Debugging mit Vault-Suche

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. Besonders wertvoll ist das bei wiederkehrenden Problemen über mehrere Projekte hinweg — der Vault erinnert sich an das, was Sie vergessen.

Vorbereitung auf Code Review

Bevor Sie einen PR reviewen:

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

Der Vault liefert frühere Entscheidungen, architektonische Einschränkungen und Coding-Standards, die für den zu prüfenden Code relevant sind. Die Review stützt sich damit auf institutionelles Wissen, nicht nur auf den Diff.

Performance-Tuning

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

Verwaltung der Indexgröße

Ab 50.000+ Notizen sollten Sie Folgendes erwägen: - Die batch size von 64 auf 128 erhöhen, damit Embedding schneller läuft - WAL mode (Standard) für gleichzeitigen Zugriff verwenden - Vollständige Neuindexierung außerhalb der Hauptarbeitszeiten ausführen

Query-Optimierung

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

db.execute("PRAGMA journal_mode=WAL")

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

Connection pooling. Der MCP server sollte Datenbankverbindungen wiederverwenden, statt pro Query eine neue Verbindung zu öffnen. Eine einzelne langlebige Verbindung mit WAL mode unterstützt gleichzeitige Lesevorgänge.

# 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 83-MB-Datenbank eliminiert das Mapping der gesamten Datei in den Speicher die meisten Festplattenzugriffe.

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

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

Das führt die internen b-tree-Segmente von FTS5 zusammen und reduziert die Query-Latenz bei nachfolgenden Suchen.

Skalierungsbenchmarks

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

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

Fehlerbehebung

Index Drift

Symptom: Die Suche liefert veraltete Ergebnisse 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. nach der 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 Query-Vektoren verglichen. Die Dimensionen oder die Semantik des Vektorraums sind inkompatibel.

Lösung: Der Indexer sollte die Abweichung im Modell-Hash 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-Queries 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 Query 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. WAL mode erlaubt gleichzeitige Lesevorgänge, aber nur einen Schreibprozess.

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 Schreibvorgänge benötigen, verwenden Sie WAL mode und setzen Sie einen busy timeout:

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

sqlite-vec lädt nicht

Symptom: Vector search ist deaktiviert; der Retriever läuft im reinen 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 einer vollständigen Neuindexierung eines großen Vaults (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 (also jede Datei liest, chunkt und einbettet, 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 in Markdown
3. Verschieben Sie die konvertierten Dateien in den Ordner 00-inbox/ Ihres Vaults
4. Prüfen Sie jede Notiz und ergänzen Sie frontmatter
5. Verschieben Sie Notizen in passende Domain-Ordner

Von Notion

1. Exportieren Sie aus Notion: Einstellungen → Export → Markdown & CSV
2. Entpacken Sie den Export in den Ordner 00-inbox/ Ihres Vaults
3. Beheben Sie Notion-spezifische Markdown-Artefakte:
4. Notion verwendet - [ ] für Checklisten — das ist Standard-Markdown
5. Notion fügt Eigenschaftstabellen als HTML ein — 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 standardisiertes 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 in 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 die Dateien in den Vault, ergänzen Sie frontmatter und organisieren Sie sie in Ordnern

Von einfachem 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, wenn das Verzeichnis versioniert wird
3. Erstellen Sie frontmatter-Vorlagen und wenden Sie sie auf vorhandene Dateien an
4. Beginnen Sie beim Lesen und Organisieren damit, Notizen mit [[wiki-links]] zu verknüpfen
5. Führen Sie den Indexer sofort aus — das Retrieval-System funktioniert ab Tag 1

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 Queries aus, deren Antworten Sie kennen, und prüfen Sie, ob die Ergebnisse Ihren Erwartungen entsprechen.

Änderungsprotokoll

Quellen