SeekLink

SeekLink

English · 中文

ステータス：休止中。 SeekLink は積極的なメンテナンスを終了しました。同じ用途で現在も積極的に開発されているローカル Markdown 検索エンジンをお探しの場合は、ローカルでのハイブリッドなキーワード検索とベクトル検索、行を基準にした結果、CLI と MCP、多言語対応を備えた qmd をおすすめします。

SeekLink は、Markdown の保管庫向けのローカルセマンティック検索 CLI で、オプションで読み取り専用の MCP stdio サーバーとしても利用できます。.md ファイルのフォルダーをインデックス化し、キーワード検索とベクトル検索を組み合わせて検索します。人間やエージェントが簡単なシェルコマンドで読める、行を基準にした結果を返します。

個人用ナレッジベース、Obsidian 互換の保管庫、英語と中国語のバイリンガルノート、ローカルのエージェントワークフロー向けに構築されています。Claude Code、Cursor、VS Code などの MCP クライアントは、seeklink[mcp] を通じて、同じ読み取り専用の search/get/status/doctor 機能を呼び出せます。また、Andrej Karpathy の llm-wiki のような Markdown Wiki のパターンでも、便利な検索レイヤーとして利用できます。エージェントは既存のページを検索し、指定した行の範囲を読み取ってから、保管庫をホスト型サービスに送信することなく Wiki を更新できます。

すべてローカルで動作します。API キーは不要です。クラウド検索サービスも不要です。Obsidian プラグインも必要ありません。

インストール

uv tool install seeklink
# or
pip install seeklink

Apple Silicon での再ランキングに対応するには、オプションの MLX エクストラをインストールしてください。

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

Claude Code、Cursor、VS Code などの Model Context Protocol（MCP）クライアントを利用するには、オプションの MCP エクストラをインストールしてください。

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

SeekLink では、Python の sqlite3 モジュールが FTS5 を有効にした SQLite 3.45 以降とリンクされている必要があります。seeklink status --vault PATH でこれを確認でき、実行環境の SQLite が古い場合は明確なエラーメッセージが表示されます。

クイックスタート

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

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

デフォルトの保管庫を設定すると、日常的な使用がより簡単になります。

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 と単一ファイルを対象とする seeklink index path/to/file.md は、--vault を指定しない場合、常駐デーモンを使用します。デーモンは埋め込みモデルと、オプションの再ランキングモデルをメモリ上に常駐させます。macOS では、ローカルの Python プロセスとして表示されます。ローカル環境のみで動作し、Unix ソケットを使用します。ネットワークポートを開いたり、クラウドサービスを呼び出したりすることはありません。デフォルトでは、15 分間操作がないと終了します。保管庫全体を対象とする seeklink index はプロセス内で実行されるため、進捗は標準エラー出力に、最終的な Done: の概要は標準出力に表示されます。seeklink status と seeklink get は常にコールドスタートで実行されます。status は SQLite のメタデータのみを読み取り、get はファイルをディスクから直接読み取ります。スクリプトで一度だけコールドスタートで実行する必要がある場合は、--no-daemon、SEEKLINK_NO_DAEMON=1、または明示的な --vault PATH を使用してください。

MCP を使用する場合も、最初の手順は同じです。MCP サーバーを登録する前に、seeklink index --vault PATH でインデックスを作成してください。

出力

テキスト検索の出力は一定です。

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

• PATH は保管庫のルートからの相対パスです。
• LINE は 1 から始まり、現在のファイル内で最も一致度の高いチャンクを指します。
• 終了コードは、結果がない場合も含め成功時は 0、SeekLink が検出した実行時の保管庫／設定／ファイルエラー時は 1、引数の解析によるコマンドラインの使用方法エラー時は 2 です。
• スコアは、1 回のクエリ内での並べ替えに役立ちます。再ランキングを有効にした実行と無効にした実行の間で、スコアを比較しないでください。

エージェントで構造化された出力が必要な場合は、JSON を使用してください。

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

よく使うコマンド

検索

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

オプション：

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

取得

データベースやデーモンを使わずに、ファイルの指定した範囲を読み取ります。

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 は LINE から始まる行を出力します。-C/--context は grep 形式で、LINE の前後の行を出力します。../.. のようなパス指定によるディレクトリの遡りは拒否されます。

ステータス

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

ステータスでは、インデックスの件数、モデル名、インデックス設定の互換性、SQLite の WAL ステータス、鮮度に関する警告を報告します。埋め込みモデルや再ランキングモデルは読み込みません。

Doctor

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

Doctor は、Python、SQLite、ローカルデータベース、インデックスの互換性、デーモンの状態、オプションの MLX の利用可否を確認します。モデルのダウンロードや読み込みは行いませんが、ローカル SeekLink データベース／スキーマが存在しない場合は初期化することがあります。

MCP

オプションの Model Context Protocol（MCP）アダプターを使うと、エージェントクライアントが SeekLink の読み取り専用ツールを検出して直接呼び出せます。CLI は引き続き単独で動作します。MCP は同じ検索経路を提供する別のインターフェースであり、置き換えるものではありません。

seeklink mcp --vault PATH

seeklink[mcp] でインストールします。まず CLI でインデックスを構築してください：seeklink index --vault PATH。MCP アダプターは読み取り専用で、search、get、status、doctor の 4 つのツールを公開します。index の公開、ノートの書き込み、HTTP／OAuth の使用、Unix ソケットデーモン経由のルーティングは行いません。ボルトごとに MCP サーバーを 1 つ実行してください。search のテキスト要約は、パスと行アンカーを含む簡潔な形式で、結果のプレビューは必要とするエージェント向けに構造化コンテンツに保持されます。既存の .seeklink/seeklink.db で必要な場合、status と doctor はローカル SeekLink スキーマを初期化または移行することがありますが、インデックスの作成や Markdown ノートの変更は行いません。MCP クライアントがシェルの PATH を引き継がない場合は、以下の例で which seeklink が返す絶対パスを使用してください。

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"]
    }
  }
}

インデックス

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

ボルト全体のインデックス作成では、保存済みインデックスが異なる埋め込みモデル、ベクトル次元、またはチャンク分割設定で構築されている場合を除き、内容ハッシュに基づいて変更されていないファイルをスキップします。その場合、SeekLink は派生インデックスの内容を再構築します。単一ファイルのインデックス作成では、既存のインデックス設定に互換性がある場合に限り、1 つの Markdown ファイルを更新します。

デーモン

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

通常、デーモンを手動で起動する必要はありません。search と単一ファイルの index は、適切な場合にデーモンを自動起動・自動再起動し、SEEKLINK_DAEMON_IDLE_TIMEOUT 秒間操作がないと終了します。デフォルトは 900 秒（15 分）です。0、off、false、または no を設定すると、停止するまでデーモンが起動した状態を保ちます。

ボルト全体の index は、進捗を表示するため、引き続きプロセス内で実行されます。search または単一ファイルの index に --vault を渡すと、起動時にデーモンが 1 つのボルトにバインドされるため、毎回コールドスタートする経路が強制されます。--no-daemon と SEEKLINK_NO_DAEMON=1 も同じコールドスタート経路を強制します。起動中のプロセスを確認するには seeklink daemon status を、メモリをすぐに解放するには seeklink daemon stop を使用してください。

検索の仕組み

SeekLink は、Reciprocal Rank Fusion を使用して 4 つのチャネルを統合します。

チャネル	目的
BM25 / FTS5	完全一致する語、コード用語、頭字語、CJK の語彙マッチ
ベクトル検索	表現が異なる語句間の意味的なマッチ
タイトル／エイリアス／見出し	ノートやセクションの完全一致検索
Wikilink の入次数	既存の [[links]] に基づく、グラフ品質の小さな事前評価

デフォルトの埋め込みモデルは、fastembed 経由の jinaai/jina-embeddings-v2-base-zh です。CJK の全文検索では、ローカルの Python／SQLite ビルドで安全に登録できる場合、jieba FTS5 トークナイザーを使用します。それ以外の場合、クラッシュする代わりに SeekLink は SQLite 組み込みのトライグラムトークナイザーにフォールバックします。

デフォルトのベクトル次元は 768 です。高度なカスタム埋め込みモデルの実験では SEEKLINK_EMBEDDING_DIM を設定できますが、埋め込みモデルの出力と一致させる必要があり、seeklink index によるインデックス全体の再構築が必要です。

Apple Silicon では、seeklink[mlx] をインストールすると、SeekLink は mlx-community/Qwen3-Reranker-0.6B-mxfp8 で候補を再ランキングできます。再ランキングはローカルで実行され、オプションです。MLX が利用できない場合、SeekLink は初段のハイブリッド RRF ランキングにフォールバックします。1 回のクエリで再ランキングを無効にするには --no-rerank を使用するか、全体で無効にするには SEEKLINK_RERANKER_MODEL="" を設定してください。

Frontmatter

Markdown のフロントマターは省略可能です。記述されている場合、SeekLink はタグと エイリアスに使用します。

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

• tags は絞り込み検索に対応しています：seeklink search "memory" --tags ai
• aliases は検索用にインデックス化され、ウィキリンクの解決時にも使用されます

ストレージ

SeekLink はボルト内に SQLite データベースを 1 つ作成します。

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

データベースには、ソースのメタデータ、チャンク、FTS5 テーブル、sqlite-vec のベクトル、 ウィキリンクのグラフが含まれます。.seeklink/ を削除して seeklink index を実行すると再構築できます。

対応状況

領域	状況
Python	3.11、3.12、3.13、3.14
SQLite	FTS5 を備えた SQLite 3.45+ にリンクされた Python sqlite3
OS	macOS および Linux
Windows	第一級の対応対象ではありません
ファイル形式	Markdown .md
ボルト形式	通常のフォルダー、または Obsidian 互換のボルト
CJK	jieba を使用したネイティブパス。静的 SQLite ビルドではトライグラムにフォールバック
リランカー	Apple Silicon ではオプションの seeklink[mlx] エクストラ。それ以外では無効
デーモン	マシンごとに単一のボルト
MCP	オプションの seeklink[mcp] stdio アダプター。ボルトごとに 1 つのサーバー

対象外

• ホスト型または同期型のマルチユーザー検索。
• 変換を行わない Markdown 以外のソース。
• GUI または Obsidian プラグイン。
• 数百万件のノートを対象とするサブミリ秒の検索。
• クラウドの埋め込みまたはリランキング API。

エージェント向けの注意事項

エージェントは通常のサブプロセス呼び出しを通じて SeekLink を使用できます。

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

MCP クライアントは、オプションの読み取り専用アダプターを使用できます。

seeklink mcp --vault PATH

エージェントに Markdown ボルトで SeekLink を選択させるには、プロジェクトの AGENTS.md、CLAUDE.md、またはエディタールールに次の内容を追加します。

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.

ホットループ向けに、デーモンは ~/.rhizome/seeklink.sock の Unix ソケット上で、長さ付き JSON プロトコルを公開します。ソケットレベルのレイテンシが特に必要な場合を除き、 ほとんどのエージェントは CLI の JSON インターフェイスを使用してください。

簡潔なエージェント向け仕様については、llms.txt を参照してください。

評価

検索品質のテストは tests/blind/ にあり、手法は docs/blind-test.md に記載されています。リリースに関する主張は、 同梱のフィクスチャクエリ、またはプライベートボルトでの測定結果で裏付けてください。その場合は、プライベートボルトでの測定であることを明記してください。

コントリビューション

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

実行時の依存関係は少なく保ち、公開ドキュメントはユーザー向けにし、ユーザーに見える変更については CHANGELOG.md にエントリーを追加してください。

ライセンス

MIT