SeekLink

Englisch · Chinesisch

SeekLink ist ein lokales CLI für semantische Suche und ein optionaler Read-only MCP-stdio-Server für Markdown-Vaults. Es indiziert einen Ordner mit .md-Dateien, durchsucht diesen mit einer hybriden Keyword- und Vektor-Suche und liefert zeilenbasierte Ergebnisse, die sowohl von Menschen als auch von Agenten über einfache Shell-Befehle gelesen werden können.

Es wurde für persönliche Wissensdatenbanken, Obsidian-kompatible Vaults, zweisprachige englisch/chinesische Notizen und lokale Agenten-Workflows entwickelt. MCP-Clients wie Claude Code, Cursor und VS Code können dieselbe Read-only-Schnittstelle für Suche/Abruf/Status/Doctor über seeklink[mcp] aufrufen. Es ist auch eine nützliche Suchschicht für Markdown-Wiki-Muster wie Andrej Karpathys llm-wiki: Ein Agent kann existierende Seiten durchsuchen, präzise Zeilenfenster lesen und dann das Wiki aktualisieren, ohne den Vault an einen gehosteten Dienst zu senden.

Alles läuft lokal. Kein API-Key. Kein Cloud-Suchdienst. Kein Obsidian-Plugin erforderlich.

Installation

uv tool install seeklink
# or
pip install seeklink

Für die Unterstützung von Reranking auf Apple Silicon installieren Sie das optionale MLX-Extra:

uv tool install "seeklink[mlx]"
# or
pip install "seeklink[mlx]"

Für Model Context Protocol (MCP)-Clients wie Claude Code, Cursor oder VS Code installieren Sie das optionale MCP-Extra:

uv tool install "seeklink[mcp]"
# or
pip install "seeklink[mcp]"

SeekLink erfordert, dass das sqlite3-Modul von Python gegen SQLite 3.45 oder neuer mit aktiviertem FTS5 gelinkt ist. seeklink status --vault PATH überprüft dies und gibt eine klare Fehlermeldung aus, falls die Laufzeit-SQLite-Version zu alt ist.

Schnellstart

# 1. Build the index first.
seeklink index --vault /path/to/vault

# 2. Search it.
seeklink search "machine learning" --vault /path/to/vault

Der tägliche Gebrauch ist einfacher, wenn Sie einen Standard-Vault festlegen:

export SEEKLINK_VAULT=/path/to/vault
seeklink index
seeklink search "agent memory systems"
seeklink get notes/agent-memory-patterns.md:1 -C 20

seeklink search und die Einzeldatei-Indizierung seeklink index path/to/file.md verwenden einen residenten Daemon, wenn --vault nicht übergeben wird. Der Daemon hält den Embedder und den optionalen Reranker im Arbeitsspeicher bereit; unter macOS erscheint dies als lokaler Python-Prozess. Er ist rein lokal, verwendet einen Unix-Socket und öffnet weder einen Netzwerkport noch ruft er einen Cloud-Dienst auf. Standardmäßig beendet er sich nach 15 Minuten Inaktivität. Die vollständige Vault-Indizierung seeklink index läuft im Prozess, sodass der Fortschritt auf stderr und die abschließende Done:-Zusammenfassung auf stdout ausgegeben werden. seeklink status und seeklink get starten immer kalt: Status liest nur SQLite-Metadaten, und get liest die Datei direkt von der Festplatte. Verwenden Sie --no-daemon, SEEKLINK_NO_DAEMON=1 oder ein explizites --vault PATH, wenn ein Skript einen einmaligen Kaltstart-Pfad benötigt.

MCP-Benutzer folgen dem gleichen ersten Schritt: Erstellen Sie den Index mit seeklink index --vault PATH, bevor Sie den MCP-Server registrieren.

Ausgabe

Die Textsuchausgabe ist stabil:

  SCORE  PATH[:LINE]  TITLE
           <content preview, one line, up to 120 chars>

• PATH ist relativ zum Vault-Wurzelverzeichnis.

• LINE ist 1-basiert und zeigt auf den am besten passenden Abschnitt in der aktuellen Datei.

• Der Exit-Code ist 0 für Erfolg, einschließlich „keine Ergebnisse“; 1 für Laufzeitfehler bei Vault/Konfiguration/Datei, die von SeekLink erkannt wurden; und 2 für Fehler bei der Befehlszeilennutzung durch Argument-Parsing.

• Scores sind nützlich für die Sortierung innerhalb einer Abfrage. Vergleichen Sie keine Scores zwischen Durchläufen mit und ohne Reranker.

Verwenden Sie JSON, wenn ein Agent eine strukturierte Ausgabe benötigt:

seeklink search "agent memory systems" --vault PATH --json
seeklink status --vault PATH --json
seeklink doctor --vault PATH --json
seeklink daemon status --json

Häufige Befehle

Suche

seeklink search "query" --vault PATH [options]

Optionen:

--top-k N          Number of results. Default: 10.
--json             Emit one machine-readable JSON object.
--tags TAG [TAG]   Filter by tags. AND semantics.
--folder PREFIX    Filter by vault-relative folder prefix.
--rerank-k N|auto  Rerank candidate budget. Default: auto.
--no-rerank        Skip cross-encoder reranking for this query.
--no-daemon        Force an in-process search instead of using the daemon.
--title-weight F   Override title/alias/heading channel weight. Default: 1.5.

Abruf (Get)

Lesen Sie ein präzises Dateifenster, ohne die Datenbank oder den Daemon zu verwenden:

seeklink get notes/spaced-repetition.md
seeklink get notes/spaced-repetition.md:12
seeklink get notes/spaced-repetition.md:12 -l 40
seeklink get notes/spaced-repetition.md:12 -C 20

-l/--lines gibt Zeilen ab LINE aus. -C/--context gibt Zeilen vor und nach LINE im Grep-Stil aus. Pfad-Escapes wie ../.. werden abgelehnt.

Status

seeklink status --vault PATH
seeklink status --vault PATH --json

Der Status berichtet über Index-Anzahlen, Modellnamen, Kompatibilität der Index-Konfiguration, SQLite-WAL-Status und Aktualitätswarnungen. Er lädt weder die Embedding- noch die Reranking-Modelle.

Doctor

seeklink doctor --vault PATH
seeklink doctor --vault PATH --json

Doctor überprüft Python, SQLite, die lokale Datenbank, Index-Kompatibilität, Daemon-Status und die optionale MLX-Verfügbarkeit. Er lädt keine Modelle herunter oder initialisiert sie, kann aber die lokale SeekLink-Datenbank/das Schema initialisieren, falls es fehlt.

MCP

Der optionale Model Context Protocol (MCP)-Adapter ermöglicht es Agenten-Clients, die Read-only-Tools von SeekLink direkt zu entdecken und aufzurufen. Das CLI funktioniert weiterhin unabhängig; MCP ist eine weitere Schnittstelle für denselben Abrufpfad, kein Ersatz.

seeklink mcp --vault PATH

Installieren Sie es mit seeklink[mcp]. Erstellen Sie den Index zuerst mit dem CLI: seeklink index --vault PATH. Der MCP-Adapter ist Read-only und stellt vier Tools bereit: search, get, status und doctor. Er stellt index nicht bereit, schreibt keine Notizen, verwendet kein HTTP/OAuth und leitet nicht über den Unix-Socket-Daemon. Führen Sie einen MCP-Server pro Vault aus. search hält seine Textzusammenfassung kompakt mit Pfaden und Zeilenankern; Ergebnisvorschauen bleiben in strukturiertem Inhalt für Agenten, die diese benötigen. status und doctor können das lokale SeekLink-Schema initialisieren oder migrieren, wenn ein existierendes .seeklink/seeklink.db dies erfordert, aber sie indizieren oder modifizieren keine Markdown-Notizen. Wenn Ihr MCP-Client Ihren Shell-PATH nicht erbt, verwenden Sie den absoluten Pfad von which seeklink in den Beispielen unten.

Claude Code:

claude mcp add --transport stdio --scope project seeklink \
  -- seeklink mcp --vault /ABS/PATH/TO/VAULT

Cursor .cursor/mcp.json:

{
  "mcpServers": {
    "seeklink": {
      "type": "stdio",
      "command": "seeklink",
      "args": ["mcp", "--vault", "/ABS/PATH/TO/VAULT"]
    }
  }
}

VS Code .vscode/mcp.json:

{
  "servers": {
    "seeklink": {
      "type": "stdio",
      "command": "seeklink",
      "args": ["mcp", "--vault", "/ABS/PATH/TO/VAULT"]
    }
  }
}

Index

seeklink index --vault PATH
seeklink index path/to/file.md --vault PATH

Die vollständige Vault-Indizierung überspringt unveränderte Dateien anhand des Inhalts-Hashs, es sei denn, der gespeicherte Index wurde mit einem anderen Embedder, einer anderen Vektordimension oder einer anderen Chunker-Konfiguration erstellt. In diesem Fall baut SeekLink die abgeleiteten Indexinhalte neu auf. Die Einzeldatei-Indizierung aktualisiert eine Markdown-Datei nur, wenn die existierende Index-Konfiguration kompatibel ist.

Daemon

seeklink daemon status
seeklink daemon stop
seeklink daemon restart
seeklink daemon pid
seeklink daemon run --vault PATH

Normalerweise müssen Sie den Daemon nicht manuell starten. search und die Einzeldatei-index starten ihn bei Bedarf automatisch und starten ihn neu; er beendet sich nach SEEKLINK_DAEMON_IDLE_TIMEOUT Sekunden Inaktivität. Der Standardwert ist 900 Sekunden (15 Minuten); setzen Sie ihn auf 0, off, false oder no, um den Daemon bis zum Stoppen warm zu halten.

Die vollständige Vault-index läuft weiterhin im Prozess für die Fortschrittsausgabe. Die Übergabe von --vault an search oder die Einzeldatei-index erzwingt einen einmaligen Kaltstart-Pfad, da der Daemon beim Start an einen Vault gebunden ist. --no-daemon und SEEKLINK_NO_DAEMON=1 erzwingen ebenfalls denselben Kaltstart-Pfad. Verwenden Sie seeklink daemon status, um den warmen Prozess zu überprüfen, und seeklink daemon stop, um dessen Speicher sofort freizugeben.

Funktionsweise der Suche

SeekLink führt vier Kanäle mit Reciprocal Rank Fusion (RRF) zusammen:

Der Standard-Embedder ist jinaai/jina-embeddings-v2-base-zh über fastembed. Die CJK-Volltextsuche verwendet einen jieba FTS5-Tokenizer, wenn der lokale Python/SQLite-Build ihn sicher registrieren kann; andernfalls greift SeekLink auf den eingebauten Trigram-Tokenizer von SQLite zurück, anstatt abzustürzen.

Die Standard-Vektordimension ist 768. Fortgeschrittene Experimente mit benutzerdefinierten Embeddern können SEEKLINK_EMBEDDING_DIM setzen, dies muss jedoch mit der Embedder-Ausgabe übereinstimmen und erfordert einen vollständigen seeklink index-Neuaufbau.

Auf Apple Silicon kann SeekLink Kandidaten mit mlx-community/Qwen3-Reranker-0.6B-mxfp8 neu bewerten, wenn es mit seeklink[mlx] installiert wurde. Reranking ist lokal und optional; wenn MLX nicht verfügbar ist, greift SeekLink auf das hybride RRF-Ranking der ersten Stufe zurück. Verwenden Sie --no-rerank für eine Abfrage oder setzen Sie SEEKLINK_RERANKER_MODEL="", um es global zu deaktivieren.

Frontmatter

Markdown-Frontmatter ist optional. Wenn vorhanden, verwendet SeekLink es für Tags und Aliase:

---
tags: [ai, memory]
aliases: [LLM memory, agent memory]
---

• tags unterstützen gefilterte Suche: seeklink search "memory" --tags ai

• aliases werden für die Suche indiziert und beim Auflösen von Wikilinks verwendet

Speicherung

SeekLink schreibt eine SQLite-Datenbank innerhalb des Vaults:

/path/to/vault/.seeklink/seeklink.db

Die Datenbank enthält Quellmetadaten, Chunks, FTS5-Tabellen, sqlite-vec-Vektoren und einen Wikilink-Graphen. Löschen Sie .seeklink/ und führen Sie seeklink index aus, um alles neu aufzubauen.

Unterstützt

Nicht geeignet für

• Gehostete oder synchronisierte Multi-User-Suche.

• Nicht-Markdown-Quellen ohne Konvertierung.

• Ein GUI oder Obsidian-Plugin.

• Sub-Millisekunden-Suche über Millionen von Notizen.

• Cloud-Embedding- oder Reranking-APIs.

Agenten-Hinweise

Agenten können SeekLink über gewöhnliche Subprozess-Aufrufe verwenden:

seeklink status --vault PATH
seeklink index --vault PATH
seeklink search "query" --vault PATH --json
seeklink get PATH:LINE -C 20 --vault PATH

MCP-Clients können den optionalen Read-only-Adapter verwenden:

seeklink mcp --vault PATH

Damit ein Agent SeekLink für einen Markdown-Vault auswählt, fügen Sie dies zu den AGENTS.md, CLAUDE.md oder Editor-Regeln des Projekts hinzu:

When you need to search or inspect this Markdown vault, use SeekLink for
semantic retrieval:

1. Run `seeklink status --vault PATH --json`.
2. If no index exists or files changed, run `seeklink index --vault PATH`.
3. Run `seeklink search "QUERY" --vault PATH --json`.
4. Read exact context with `seeklink get PATH:LINE -C 20 --vault PATH`.

If SeekLink is registered as an MCP server in this client, prefer the
`search`, `get`, `status`, and `doctor` MCP tools over shelling out to the CLI.

Prefer SeekLink for conceptual, cross-language, tag/folder-filtered, or
Obsidian-style note searches. Use rg for exact literal searches.

Für Hot-Loops stellt der Daemon ein längenpräfixiertes JSON-Protokoll über den Unix-Socket unter ~/.rhizome/seeklink.sock bereit. Die meisten Agenten sollten die CLI-JSON-Schnittstelle bevorzugen, es sei denn, sie benötigen spezifisch Latenz auf Socket-Ebene.

Siehe llms.txt für den kompakten Agenten-Vertrag.

Evaluierung

Suchqualitätstests befinden sich in tests/blind/; die Methode ist in docs/blind-test.md dokumentiert. Release-Behauptungen sollten durch die gebündelten Fixture-Abfragen oder durch klar gekennzeichnete Messungen in privaten Vaults belegt werden.

Mitwirken

git clone https://github.com/simonsysun/seeklink
cd seeklink
uv sync --dev
uv run python -m pytest tests/ -q

Halten Sie Laufzeitabhängigkeiten klein, halten Sie öffentliche Dokumentationen benutzerorientiert und fügen Sie einen CHANGELOG.md-Eintrag für benutzerrelevante Änderungen hinzu.

Lizenz

MIT