SeekLink

English · 中文

SeekLinkは、Markdown保管庫（vault）のためのローカルセマンティック検索CLIであり、オプションで読み取り専用のMCP stdioサーバーとしても機能します。.mdファイルのフォルダをインデックス化し、キーワードとベクトルを組み合わせたハイブリッド検索を行い、人間やエージェントが単純なシェルコマンドで読み取れる行単位の検索結果を返します。

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

すべてがローカルで実行されます。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は、FTS5が有効なSQLite 3.45以降にリンクされたPythonのsqlite3モジュールを必要とします。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はプロセス内で実行されるため、進捗状況はstderrに表示され、最終的なDone:サマリーはstdoutに残ります。seeklink statusとseeklink getは常にコールドスタートします。ステータスはSQLiteメタデータのみを読み取り、取得はディスクから直接ファイルを読み取ります。スクリプトで一度限りのコールドスタートパスが必要な場合は、--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ステータス、および鮮度に関する警告を報告します。埋め込みモデルやリランキングモデルは読み込みません。

診断

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ソケットデーモン経由のルーティングは行いません。保管庫ごとに1つのMCPサーバーを実行してください。searchは、パスと行アンカーを使用してテキストサマリーをコンパクトに保ちます。結果のプレビューは、それを必要とするエージェントのために構造化されたコンテンツ内に保持されます。statusとdoctorは、既存の.seeklink/seeklink.dbが必要な場合にローカルの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（RRF）を使用して4つのチャネルを融合します：

デフォルトのエンベッダーは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=""を設定してください。

フロントマター

Markdownのフロントマターはオプションです。存在する場合、SeekLinkはそれをタグとエイリアスに使用します：

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

• tagsはフィルタリングされた検索をサポートします：seeklink search "memory" --tags ai

• aliasesは検索用にインデックス化され、ウィキリンクを解決する際に使用されます

ストレージ

SeekLinkは保管庫内に1つのSQLiteデータベースを書き込みます：

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

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

サポート状況

対象外

• ホスト型または同期されたマルチユーザー検索。

• 変換なしの非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