Sverklo

🇬🇧 英語 · 🇨🇳 中国語

コーディングエージェントにリポジトリの記憶を。

Sverklo はコーディングエージェントに、シンボル、呼び出し元、差分、影響範囲、編集前に確認できる Git に紐づいた決定事項など、リポジトリの記憶を提供します。Claude Code、Cursor、Windsurf、Codex CLI、および MCP に対応するあらゆるコーディングエージェント向けの、オープンソースでローカルファーストな MCP サーバーです。

ローカルファースト ◦ MIT ◦ デフォルトではローカル埋め込みモデルを同梱 ◦ リモート埋め込みは明示的に設定した場合のみ ◦ テレメトリーはオプトイン方式で、デフォルトでは無効

エージェントが編集前に関係性を把握する必要がある場合、Sverklo を使いましょう。呼び出し元、依存関係、テスト、差分のリスク、過去のリポジトリの決定事項などを確認できます。

正確な文字列が分かっている場合、リポジトリが小さい場合、または変更対象が1ファイルの場合は、grep/ripgrep を使いましょう。

MCP 設定をインストールする前に、書き込みを行わない証明コマンドを実行してください。公開ベンチマークでは、6つの OSS コードベースを対象に、180件のタスクを人手で検証しています。手法と正解データは sverklo/sverklo-bench にあります。ベンチマーク · 論文 · 90秒のデモ

cd your-project
npm exec --yes --package=sverklo@latest -- sverklo prove --no-write --guided --markdown
sverklo init --dry-run
npm install -g sverklo && sverklo init

sverklo prove --no-write --guided --markdown を実行すると、中核となるファイル、呼び出し元を持つ実際のシンボル、その証明が選ばれた理由、エージェントに貼り付ける正確なプロンプト、簡単なフィードバック用テンプレートが表示されます。MCP 設定や指示ファイルが書き込まれることはありません。~/.sverklo にローカルモデルやインデックスがキャッシュされる場合はありますが、プロジェクトは変更されません。次に sverklo init --dry-run を実行すると、init が変更するファイルを事前に確認できます。sverklo init は、エージェント用の MCP 設定を書き込み、AGENTS.md または CLAUDE.md にローカルの指示を追記し、ハンドシェイクを検証するために sverklo doctor を実行します。同梱プロバイダーを使う場合、コードのインデックス作成と埋め込みはお使いのマシン上で行われます。明示的に設定したリモート埋め込みプロバイダーには、埋め込み対象のコードチャンクが送信されます。

共有できる情報が必要ですか？sverklo prove --no-write --guided --markdown を実行して、リポジトリから GitHub／Discord ですぐ共有できる証明レシートを出力し、証明スレッドに投稿してください。

最新の書き込みなし証明の実行結果： calesthio/OpenMontage@9066dcb（インデックス作成済みファイル1,284件）で、Sverklo は tools/base_tool.py:120 の ToolResult を選び、81ファイルにわたる475件の参照を見つけました。同じチェックアウトを使った従来のトークン効率デモでは、grep と一致した上位10ファイルの読み取りを組み合わせた方法と比べ、推定入力トークン数を21.9分の1に削減しました。見つからなかったものも明記しています。レシートを読む · OpenMontage のディスカッション

Sverklo アカウント向けにローカルでのローンチ計画が必要ですか？sverklo marketing は、運用担当者が提供したスナップショットを使って、ローカルファーストの Twitter/X エージェントチーム・ワークフローを実行します。投稿、スクレイピング、返信、いいね、リポスト、フォロー、プロフィール変更を行うことなく、機会の優先順位付け、投稿の種となるコンテンツ案のキュー作成、プロフィールの健全性チェックを行い、人間による決定を記録します。

「地図は領土ではない。」 — Alfred Korzybski

学習データは地図です。コードベースは領土です。Sverklo はエージェントに領土を与えます。

エディターのショートカット

sverklo prove で役立つリポジトリの情報が見つかったら、証明スレッドに、実行結果、修正点、より良い grep の例、またはセットアップでつまずいた点を投稿してください。役に立った場合は、リポジトリにスターを付けていただくと、エージェントを多用するほかのチームにも見つけてもらいやすくなります。

▶ YouTube で 90 秒のデモを見る — sverklo init → audit → 37 個の MCP ツール → ブラスト半径とシンボルグラフの探索を使った Claude Code とのライブ統合。

AI エージェントが UserService.validate() を編集します。しかし、その関数をほかに47個の関数が呼び出していることを知りません。学習データでの表記に合わせて getUserByEmail() をでっち上げますが、あなたのコードで使っているのは findByEmail() です。昨日決めた設計方針も、コンテキストが圧縮されたため忘れてしまいます。依存関係をモックしているためテストは通ります。そして、破壊的変更がリリースされます。

Sverklo はエージェントが作業する前にリポジトリを詳しく調べます。シンボルグラフ、影響範囲、意味検索、そして Git に紐づいたメモリを使い、エージェントが学習データのパターンに頼るのではなく、あなたのコードをもとに推論できるようにします。

cd your-project
npm exec --yes --package=sverklo@latest -- sverklo prove --no-write --guided
sverklo init --dry-run
npm install -g sverklo && sverklo init

これだけです。sverklo prove --no-write --guided を実行すると、プロジェクトの設定を変更する前に、独自のコードベースを使った最初の有用なリポジトリメモリの検証ができます。sverklo init --dry-run はすべてのセットアップ対象をプレビューします。sverklo init はインストール済みの AI コーディングエージェント（Claude Code、Cursor、Windsurf、Zed）を自動検出し、適切な MCP 設定を書き込み、AGENTS.md があればそこに（なければ CLAUDE.md に）指示を追記して、セットアップを検証するために sverklo doctor を実行します。sverklo prove --markdown を使えば、公開の検証スレッドで検証結果を共有できます。macOS、Linux、Windows で動作します。デフォルトでは、バンドルされたローカル埋め込みモデルを使用します。リモート埋め込みモデルを使うのは、明示的に設定した場合のみです。テレメトリはオプトイン方式で、デフォルトではオフです。

バンドルされた埋め込みモデル（all-MiniLM-L6-v2 ONNX、約86 MB）は、初回使用時に HuggingFace から ~/.sverklo/models/ へダウンロードされます。ダウンロード後は、キャッシュされたローカルモデルを使ってバンドルされた埋め込みプロバイダーを実行できます。明示的に設定したリモートプロバイダーは、代わりにリモートエンドポイントを使用します。

インストール前に検証結果を確認しますか？ /report リーダーボードで、人気のある OSS リポジトリ47件（express、react-hook-form、vite、lodash、prisma、…）に対する Sverklo の監査結果を確認できます。デッドコード、循環依存、結合度、セキュリティの評価カードを掲載しています。

「でも、これは単に……？」

似たようなツールを見たことがあるかもしれません。率直な回答を一段落でまとめ、詳しい比較へのリンクを掲載しています。

……ひと手間加えた grep にすぎないのでは？ いいえ。ただし、正確な文字列がわかっている場合は、チューニングした grep が実際に有力な選択肢になります。180タスクのベンチマークでは、sverklo は総合 F1 で首位（0.58 対 smart-grep の 0.34）に立ち、ナイーブな grep と比べて入力トークンを約 35 分の 1 に抑えながら、タスクごとのツール呼び出しは 1 回です。200K のコンテキストウィンドウを持つ AI エージェントにとって、ここが重要な軸です。ターミナルを使う人間にとっては、今でも grep で十分です。

……単に Sourcegraph Cody では？ 検索機能（ハイブリッド BM25 ＋ベクトル＋グラフ）は同じですが、デプロイモデルとライセンスが異なります。Cody はソースコードを公開しており、エンタープライズ向けの開発者ごとの料金（月額 9～19 ドル）がかかります。sverklo は MIT ライセンスで、登録不要でノートパソコン上で動作します。詳しい比較 →

……単に Greptile では？ Greptile はホスト型の PR レビューボットです（月額 30 ドル／開発者）。Sverklo はローカルファーストの MCP です。リスクスコアリングという目標は同じですが、デプロイモデルは正反対です。コンプライアンス上の理由でコードをマシンの外に出せない場合、Greptile は選択肢になりません。詳しい比較 →

……単に Cursor の @codebase では？ Cursor のインデックス作成はクラウドベースで、エディターに依存します。sverklo は MCP サーバーとして Cursor と併用でき、Cursor の @codebase では利用できないシンボルグラフ、影響範囲、双時間メモリを追加します。詳しい比較 →

……単に Claude Context（Zilliz）では？ Claude Context には Milvus データベースが必要です。sverklo は組み込み SQLite だけで動作するため、管理する追加サービスはありません。詳しい比較 →

……単に Aider の repo-map では？ Aider の repo-map はシステムプロンプト内の静的な情報です。小さなリポジトリには適していますが、約 100 ファイルを超えると拡張できません。sverklo は、より大きなコードベース向けに、Aider が MCP 経由で呼び出せる検索レイヤーです。競合するものではなく、相互に補完し合います。詳しい比較 →

……ニッチなメモリ MCP では？ 多くのメモリ MCP は、外部ベクトルデータベースのラッパーです。sverklo のメモリは双時間型（valid_from_sha、valid_until_sha、superseded_by）で、Git の SHA に固定されます。そのため、「このチームはコミット abc123 時点で認証についてどう考えていた？」と質問すれば、当時正しかった回答を得られます。codebase-memory-mcp との詳しい比較 →

……Aider、Continue、Codex CLI、Claude Code については？ これらはコードを生成して適用するエージェントです。sverklo は、エージェントがコードを書く前に呼び出す検索レイヤーです。両方を使いましょう。sverklo init はインストール済みのエージェントを自動検出します →

ここで取り上げられていないもので、知りたいことがあれば、イシューを作成してください。追加します。

0.20 の新機能

• 双時間メモリレイヤーでの矛盾検出。 memories mode:"conflicts" は、共通のピン（ファイルパスまたはシンボル名）を持ち、矛盾している可能性があるアクティブなメモリの組を提示します。たとえば、どちらも src/auth.ts にピン留めされた「ミドルウェア内の JWT」と「ルートハンドラー内の JWT」などです。対象は決定・好み・パターンのカテゴリに限定されます（手順・コンテキストは追加情報であり、矛盾しないためです）。SHA が同じ組は除外されます。共通するピンの数と経過時間で並べ替えられます。設計上、慎重に候補を提示し、エージェントまたは人間による確認を促します。自動的に解決することはありません。双時間モデルはすでに矛盾の両方の情報を保持しており、今回の変更によって見つけやすくなりました。

0.19 の新機能

• C#（.cs）言語のサポート — #22 における @NerdChieftain によるコミュニティからの貢献です。Tree-sitter（文法がインストールされている場合）と正規表現フォールバックパーサーに対応しています。名前空間（ブロックスコープと C# 10 以降のファイルスコープ）、クラス、構造体、レコード（通常のもの／record class／record struct）、インターフェース、列挙型、メソッド、コンストラクター、using ディレクティブをインデックス化します。インストール対象に [email protected] の WASM 文法が追加されます。Sverklo はこれで 12 言語に対応します。

0.18 の新機能

• Vue.js（.vue）のサポート。 単一ファイルコンポーネントに正式対応しました。<script> ブロックは既存の TS/JS パイプラインで解析され（SFC に合わせて行番号を再マッピング）、Composition API ヘルパー（ref、computed、reactive、defineProps など）はシンボルとしてインデックス化されます。また、PascalCase のテンプレートタグは相対インポートを出力するため、PageRank がコンポーネントのグラフを認識できます。さらに、import type { X } from 'y' が検出されなかった既存の TS バグも修正されます。
• sverklo init が AGENTS.md に対応。 AGENTS.md が存在する場合、prefer-sverklo ブロックは CLAUDE.md ではなく AGENTS.md に追記されます。sverklo doctor は2つのファイルの不一致を警告するため、複数エージェントのセットアップを同期した状態に保てます。
• Windows のパス処理を修正。 sverklo init と sverklo doctor が Windows で動作するようになりました。絶対パスには path.basename() を使用し、保存される relativePath はスラッシュに正規化されるため、すべての後続処理でクロスプラットフォーム対応となります。
• npm run bench:swe — 第三者が再現可能なリポジトリ横断評価です。5つの OSS リポジトリ（express、nestjs、vite、prisma、fastapi）をクローンし、根拠に基づく65の質問を実行して、集計した再現率を出力します。質問を追加する PR を歓迎します。
• Tree-sitter パーサーのオプトイン対応。 sverklo grammars install（6言語で約3.5 MB）と SVERKLO_PARSER=tree-sitter を設定すると、インデクサーが TypeScript／TSX／JavaScript／Python／Go／Rust の実際の AST を使用します。文法がインストールされていない場合は、通知なしで正規表現にフォールバックします。デフォルトの切り替え計画については docs/parser-parity.md をご覧ください。
• ワークスペース共有メモリ。 sverklo workspace memory <name> add/list/search と、エージェントからの remember scope:"workspace" により、決定事項を一度書き込むだけで、ワークスペース内の他のすべてのリポジトリから検索できます。recall はワークスペースの結果をプロジェクトの結果の下に [ws] バッジ付きで表示します。
• sverklo memory export — Markdown／Notion／JSON に対応しています。チームの決定ログを実際の保存先に移行できます。
• PR ボットのインラインレビュー。 sverklo review --format github-review-json と、アクションで新たにデフォルト有効となった inline-comments: true により、既存の固定サマリーと合わせて、pulls.createReview を通じた行ごとのレビューコメントを投稿します。
• VS Code 拡張機能のひな形を extensions/vscode/ に用意し、ビルド済みの sverklo-vscode-0.1.0.vsix を同梱しました。すべての関数ヘッダーに呼び出し元の数をインライン表示します（⟵ 47 callers）。マーケットプレイスへの公開ワークフローは未稼働です。今すぐ code --install-extension extensions/vscode/sverklo-vscode-0.1.0.vsix でインストールできます。
• sverklo digest [--since 7d] — 監査に使える傾向、新規メモリと古いメモリの比較、変更された PageRank 上位ファイルを5行で要約します。cd 時に実行されるシェルフックに組み込めば、毎日の sverklo チェックインに使えます。

Grep と Sverklo — 同じ質問を並べて比較

ここに挙げたのはすべて、先週、実際のエンジニアが実際の AI アシスタントに尋ねた質問です。Grep は行を返します。Sverklo はランキング付きの回答を返します。

質問への答えが「文字列 X と完全一致するものがどこかにあるか」なら、grep の勝ちです。grep を使いましょう。答えが「グラフ上でランキングした、実際に重要な 5 つのファイルはどれか」なら、sverklo が必要です。

すべての MCP エディターに対応

主なツール

以下の全 37 ツールをご覧ください。

コミット前ゲート — アーキテクチャのリグレッションをリリース前に阻止

sverklo audit-diff は、ローカル優先の差分品質ゲートです。git diff を読み込み、変更されたファイルの境界サブグラフに対して Tarjan の SCC アルゴリズムを実行し、差分によって新たな循環依存が導入された場合、またはファイルの fan-in がしきい値を超えた場合に、ゼロ以外の終了コードを返します。.git/hooks/pre-commit のステップとして実行するよう設計されており、通常の実行時間は 200 ms を大きく下回ります。

# manual
sverklo audit-diff
echo $?   # 0 = clean, 1 = gate failure, 2 = config error

# CI variant
sverklo audit-diff --format json | jq .pass

（プレーンな git で）コミット前フックとして設定します。

cat > .git/hooks/pre-commit <<'EOF'
#!/usr/bin/env bash
set -e
sverklo audit-diff
EOF
chmod +x .git/hooks/pre-commit

Husky を使う場合：

npx husky add .husky/pre-commit "sverklo audit-diff"

既存の循環依存や fan-in の急増ではゲートは作動しません。作動するのは、差分によって導入された違反だけです。既存の負債を確認するには、sverklo audit-diff --show-existing を実行します（終了コードは変わりません）。

sverkloを使うべきとき、使うべきでないとき

率直にお伝えします。Sverkloは魔法のように速度を5倍にするものではなく、grepに取って代わるものでもありません。特定の用途に向けた、より鋭いツールです。

sverkloが役立つとき：

• 何を検索すればよいか、正確にはわからない
• デッドコードであることを証明する必要がある（シンボルグラフ全体で参照がゼロ）
• リファクタリングを始める前に、その影響範囲を把握する必要がある
• 大規模なPRをレビューしていて、何から読むべきか知りたい

grepが今も適しているとき：

• 完全一致の文字列検索 — 「この文字列リテラルは存在するか？」
• ソースファイルが約50個未満の小規模なコードベース — すべて読んでしまいましょう
• 単一ファイルの差分 — git diff と Read の組み合わせに勝るものはなかなかありません
• ビルドとテストの検証 — npm test を実行できるのは Bash だけです

どんな用途にも最適だと謳うローンチ記事を見かけたら、タブを閉じてください。

よくある質問

Claude Codeがコードベースについて幻覚を起こさないようにするには？

Claudeは、あなたのリポジトリではなく、学習データのパターンをもとにコードを生成します。シンボルグラフがなければ、コードで使われているのは findByEmail() なのに、getUserByEmail() をでっち上げてしまいます。Sverkloは、実際のシンボルグラフを使ってエージェントの回答を裏付けます。lookup と refs は名前を file:line に解決し、エージェントが呼び出しを書く前に、そのシンボルが存在することを証明します。検証可能な検索（verify）を使えば、引用した範囲が引用元のSHAで現在も存在するかをエージェントが再確認できます。そのため、古い引用をでっち上げてしまうのではなく、検出できます。

コードベースの記憶に使えるローカルファーストのMCPサーバーはありますか？

はい、sverkloです。remember と recall は、双時点メモリレイヤーを提供します。すべてのメモリは作成時のgit SHAに紐付けられ、valid_until_sha と superseded_by によって上書きするのではなく、置き換えの履歴をタイムラインとして保持します。Recallは、同梱のONNX埋め込みモデルを使ったFTS5とコサイン類似度のハイブリッド検索をデフォルトで使用し、インデックスは組み込みSQLiteに保存されます。外部のベクトルデータベースは不要です。明示的に設定したリモート埋め込みプロバイダーには、埋め込み対象のテキストが送信されます。

ローカルで実行できる、Sourcegraph Codyのオープンソース代替製品はありますか？

Sverkloは、コードベースに関するQ&A向けのSourcegraph Codyのオープンソースなローカル代替製品です。BM25、ベクトル検索、PageRankを組み合わせたハイブリッド検索、シンボルグラフのナビゲーション、ソース公開ではなくMITライセンス、Codyのエンタープライズ向けデプロイではなく単一マシンでの運用、そして開発者1人あたり月額9～19ドルではなく無料で利用できます。Sverkloは同じ機能一式の提供を目指しているわけではありません。ホスト型IDEプラグインではなく、AIコーディングエージェント向けのプリミティブ層（MCPツール37個）です。ただし、「エージェントにコードベースの意味的な理解を与える」という用途では、同じ領域をカバーします。

sverkloを使うと、コードはどこに送信されますか？

デフォルトでは、Sverkloは組み込みSQLiteと同梱のONNX埋め込みモデルを使ってローカルでインデックスを作成します。モデルは初回使用時にHuggingFaceからダウンロードされ（約86 MB）、その後 ~/.sverklo/models/ にキャッシュされます。リモート埋め込みプロバイダーを明示的に選択した場合、Sverkloは埋め込みに必要なコードのチャンクをそのプロバイダーに送信します。インデックスはローカルに保持されます。テレメトリは別の機能で、オプトイン方式のため、デフォルトではオフです。固定イベントスキーマには、コード、クエリ、ファイルパス、シンボル名、メモリの内容は含まれません。

sverkloはCursorの@codebaseやCursor Tabと連携しますか？

SverkloはCursorの組み込みインデックスを置き換えるのではなく、併用できます。Cursorの@codebaseはIDE内で埋め込みベースの検索を提供します。sverkloは、Cursorでは利用できないシンボルグラフ、影響範囲、差分を考慮したリスクスコア付きレビュー、双時点メモリを追加します。CursorでsverkloをMCPサーバーとして設定すると、両方のレイヤーをエージェントが同時に利用できます。同じ設定は、Claude Code、Windsurf、Zed、Antigravityなど、MCPに対応するあらゆるツールでも使えます。

ここでしか見つからない3つの検索手法

ほとんどのコード検索 MCP は、Milvus や pgvector 上で BM25 とベクトル検索を RRF で統合するだけです。Sverklo の再現率は、単なるテキスト類似度ではなく、コードベースの構造を活用する3つの手法によって実現されています。それぞれ、実際の質問で発生した検索漏れを解消するために追加されました。これらを組み合わせた結果、マネージドベクトルデータベースなしで、sverklo の調査ベンチマークは再現率99％（32件中31件）を達成しています。

1. ファイル名をシグナルとして使う検索

クエリのトークンがファイル名に一致すると、そのファイルの本文が FTS に一致しない場合でも、sverklo はそのファイル内の名前付き定義をすべて候補に加えます。逆に、FTS が何らかの理由（コメントの一致、インポート行など）でファイルを検出すると、そのファイル内のすべての定義が回答候補になります。この手法によって、「プライベートヘルパー関数」の見つけにくさを解消します。関数が短すぎて埋め込みでは判別できず、誰も grep しないような名前であっても、一致するコードの隣にあるため見つけられます。実装箇所は src/search/investigate.ts（runDefinitionsByPathTokens、runDefinitionsInFtsFiles）です。

2. チャネル別の RRF 融合

ほとんどのハイブリッド検索システムは、fts ∪ vector に対して1回だけReciprocal Rank Fusion を実行し、それで終わりです。Sverklo は RRF をチャネルごと（FTS、ベクトル、ドキュメントセクション、パス、シンボル名）に実行し、各チャネルの順位をチャネル固有の重みで融合します。ファイル名の一致は精度に偏るため、パスチャネルの重みは 1.5× です。ドキュメントのチャンクは独自のチャネルでスコアリングされるため、200行の Markdown セクションが4行の関数本体を埋もれさせることはありません。これは、単なる字句検索と意味検索の組み合わせではなく、構造に基づく検索です。実装箇所は src/search/investigate.ts（チャネル別 RRF と重み付き融合）です。

3. superseded_by の系譜を持つ双時間メモリ

すべてのメモリは valid_from_sha と valid_until_sha を保持します。メモリを更新しても上書きはされません。新しい行を追加し、古い行に valid_until_sha を設定して、superseded_by で両者をリンクします。検索クエリでは無効になった行が自然に除外されますが、タイムライン表示ではすべての内容が保持されます。そのため、「コミット abc123 時点で、このチームは認証フローについてどう考えていたか」と尋ねれば、その時点で有効だった回答を得られます。sverklo prune は、系譜を維持しながら、類似するエピソード記憶のクラスターを1つの意味的なノートにまとめます。実装箇所は src/storage/memory-store.ts と src/memory/prune.ts です。

仕組み

Your codebase                                              Agent query
     │                                                          │
     ▼                                                          ▼
┌─────────────┐                                          ┌─────────────┐
│   Parse     │  tree-sitter (12 langs) or               │  Tool call  │
│   chunks    │  regex fallback                          │  (1 of 37)  │
└──────┬──────┘                                          └──────┬──────┘
       │                                                         │
       ├─────────────┐         Index time                        │
       │             │                                           │
       ▼             ▼                                           │
  ┌────────┐    ┌─────────┐                                      │
  │ Embed  │    │ Import  │                                      │
  │ ONNX   │    │ graph   │                                      │
  │ MiniLM │    │ + PageRank                                     │
  └───┬────┘    └────┬────┘                                      │
      │              │                                           │
      ▼              ▼                                           │
  ┌──────────────────────────┐                                   │
  │ SQLite + sqlite-vec      │ ← single-file index, ~/.sverklo/  │
  │ chunks · embeddings ·    │                                   │
  │ symbols · refs · imports │                                   │
  │ memories (bi-temporal)   │                                   │
  └────────────┬─────────────┘                                   │
               │                                                 │
               │            Query time                           │
               ▼                                                 ▼
        ┌──────────────────────────────────────────────────────────┐
        │             Channelized RRF retrieval                    │
        │                                                          │
        │   FTS · Vector · Doc-section · Path · Symbol-name        │
        │      └─ each ranked independently ─┘                     │
        │                                                          │
        │   Fused with channel weights (path 1.5×, doc 0.7×, …)   │
        └─────────────────────────┬────────────────────────────────┘
                                  │
                                  ▼
                       ┌────────────────────────┐
                       │ Token-budgeted answer  │ ← the agent gets
                       │ file:line + chunk      │   ranked code, not
                       │ + provenance           │   a wall of text
                       └────────────────────────┘

1. 解析：コードベースを関数、クラス、型に解析します（TS、JS、Vue、Python、Go、Rust、Java、C、C++、Ruby、PHP、C#）。
2. 埋め込み：all-MiniLM-L6-v2 ONNX（384d、デフォルトでバンドルされ、ローカルで動作）、ローカルの Ollama モデル、または埋め込むコードチャンクを受け取る、明示的に選択したリモートプロバイダーを使ってコードを埋め込みます。
3. グラフ化：依存関係をグラフ化し、PageRank を計算します（構造上重要なファイルほど上位にランクされます）。
4. 検索：チャネル別 RRF を使って検索します。チャネル固有の重みを用いたチャネルごとの順位融合により、プライベートヘルパー関数の検索漏れを解消するアーキテクチャ上の選択を実現します。
5. 記憶：セッションをまたいで決定事項を記憶し、git SHA に紐付けます（双時間メモリ）。
6. 監視：ファイルの変更を監視し、インデックスを段階的に更新します（編集あたり約1秒）。

パフォーマンス

実際のコードベースでの実測値です。npm run bench で再現できます（測定方法）。

• 4,000ファイルのモノレポでも、検索 p95 は26 ms未満
• 影響分析は1ミリ秒未満 — 文字列の走査ではなく、インデックス化された SQL 結合を使用
• 24言語に対応：主要言語向けの構造解析パーサー10種と、正規表現フォールバック言語14種

Retrieval benchmark — bench:primitives

6つのOSSコードベース（express、lodash、sverklo、requests、flask、fastapi）を対象に、180件のタスクを手作業で検証した評価での、ハイブリッド検索のF1スコアとgrepベースラインの比較です。sverkloが「負ける」すべての区分を含む公開レポートは、sverklo.com/bench/ をご覧ください。方法論のリポジトリ：github.com/sverklo/sverklo-bench。

最新の公開済み180タスクの実行結果（sverklo v0.20.21、2026年5月）：

Sverkloは全体のF1スコアで首位に立ち、P4のファイル依存関係に関する質問で圧倒的な性能を示します。また、grepスタイルのベースラインが引き続き最も強いデッドコード検出では、正直に劣る区分も公開しています。トークン効率は、naive grepと比べて入力トークン数が約35分の1で、タスクごとのツール呼び出しは1回です。

再現するには、npm run bench:quick を実行してください。BASELINES=sverklo,jcodemunch DATASETS=express npm run bench:quick で絞り込めます。

ベースラインを投稿しますか？benchmark/src/baselines/<your-tool>.ts を追加するPRを作成してください。PRでは自動ベンチマークCIが実行され（expressデータセット、約10分）、結果テーブルのコメントを投稿します。詳細は .github/workflows/auto-bench.yml をご覧ください。

クイックスタート

インストール方法は3つあります。環境に合った方法を選んでください。

cd your-project
npm exec --yes --package=sverklo@latest -- sverklo prove --no-write --guided
sverklo init --dry-run
npm install -g sverklo && sverklo init

{
  "mcpServers": {
    "sverklo": {
      "command": "/full/path/to/sverklo",
      "args": ["."]
    }
  }
}

git clone https://github.com/sverklo/sverklo.git
cd sverklo
npm install
npm run build
npm link
sverklo init    # in your project directory

npm run bench:quick

Git ワークツリー

はい、sverklo は git worktree で動作します。各ワークツリー内で sverklo init を実行してください。これにより、ワークツリーごとに分離されます。

• インデックスは ~/.sverklo/<basename>-<hash>/index.db に保存され、絶対パスをキーとして使用します。同じリポジトリのワークツリーが2つある場合、それぞれ独立したデータベースが使われます。
• メモリージャーナルはワークツリー内の <worktree>/.sverklo/memories.jsonl に保存されます。双時点 SHA ピン留めにより、1つのワークツリー内でブランチを切り替えても、それぞれのメモリーは「コミット X 時点で何が真実だったか？」に正しく答えられます。
• .git リンクファイル：特別な設定は不要です。Sverklo は cwd: rootPath で git を呼び出すため、git CLI がワークツリーのリンクファイルを透過的に処理します。
• MCP 設定：ワークツリーのルートから args: ["."] を指定してください（デフォルトの sverklo init が書き込みます）。ワークツリーからメインのチェックアウトを指定すると、ブランチごとの分離が損なわれます。
• 複数の Claude Code セッションを異なるワークツリーで同時に実行：デフォルトで安全です。rootPath が異なれば DB ファイルも異なるため、競合しません。

sverklo init は .gitignore に .sverklo/ を自動的に追加するため、ワークツリーごとのジャーナルがコミットされることはありません。

任意の MCP クライアント（npx によるワンショット実行）

npx sverklo /path/to/your/project

グローバルインストールは不要です。初回の呼び出し時に npx が sverklo を解決して実行します。CI、一時的なサンドボックス、またはグローバルインストールを避けたいホストで使用してください。

Claude Code プラグインマーケットプレイス

Claude Code 内で次を実行します。

/plugin marketplace add github:sverklo/sverklo
/plugin install sverklo-skill@sverklo-marketplace

バンドルされたスキル（search、impact、review_diff、remember などをいつ使うべきか Claude に教える手順書）をインストールします。グローバルのスキルディレクトリには手を加えません。

初回実行時の注意： バンドルされた ONNX 埋め込みモデル（約 90 MB）は、初回起動時に自動的にダウンロードされます。約 30 秒かかります。その後は、バンドルされた埋め込みプロバイダーがキャッシュ済みのローカルモデルを使って動作します。

代替手段との比較（2026-04 時点）

AI 対応度を監査 — sverklo audit

ほとんどのリンターは構文をチェックします。sverklo audit は、コードベースがAI エージェントにとって読みやすいかをチェックします。エージェントがつまずくリスクの大きい「神ノード」、変更のたびに広範囲へ影響が連鎖するハブファイル、デッドコードか公開 API か判別できない孤立シンボル、シンボルグラフを混乱させる循環依存関係、そしてセキュリティ上の懸念事項をスキャンします。A〜F の健全性評価を出力し、README バッジとして掲載できます。

sverklo audit                     # markdown report in the terminal
sverklo audit --format html --open  # self-contained HTML you can share
sverklo audit --badge             # A-F shield markdown for your README
sverklo audit --format sarif      # GitHub code-scanning alerts
sverklo audit --format json       # machine-readable for CI gates

形式は markdown、html、json、sarif、csv、badges の 6 種類です。リファクタリング前にシンボルごとの影響範囲を確認したい場合は、impact（MCP ツール）と組み合わせてください。

CLI ツール

Sverklo には、CI とローカルで使える CLI が付属しています。リスクスコア付きの差分レビューには sverklo review --ci --fail-on high（GitHub Actions では PR の参照を自動検出）、コードベースの健全性レポートには sverklo audit を使えます。また、PR にレビューコメントを投稿する GitHub Action もあります。sverklo audit-prompt または sverklo review-prompt を実行すると、実績のあるワークフロー用プロンプトを取得できます。任意のエージェントに貼り付けて使用できます。

Claude Code フックのレシピ

Sverklo は Claude Code hooks と相性よく動作します。最も簡単に設定できるフックは、ツール使用後のレビューです。Claude がファイルを編集した後に、作業ツリーに対して sverklo review を実行し、リスクの高い検出結果をエージェントのトランスクリプトに表示します。次の設定を ~/.claude/settings.json に追加してください。

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "sverklo review --ref HEAD --format json --fail-on high || true"
          }
        ]
      }
    ]
  }
}

末尾の || true により、sverklo がインストールされていない場合や、作業ツリーにまだ差分がない場合でも、フックによって編集がブロックされません。プロジェクト単位のフックを設定する場合は、同じブロックをリポジトリのルートにある .claude/settings.json に記述してください。

テレメトリー

オプトイン方式で、デフォルトでは無効です。 テレメトリーが無効の場合、データは送信されません。オプトインした場合も、匿名の使用状況メトリクスのみが送信されます（コード、クエリ、ファイルパス、シンボル名、メモリの内容は送信されません）。テレメトリーは、バンドルモデルの初回ダウンロードや、明示的に設定したリモート埋め込みプロバイダーとは別の機能です。スキーマと実装の詳細は TELEMETRY.md をご覧ください。

オープンソース、オープンコア

MCP サーバー全体は無料でオープンソース（MIT）です。37 個すべてのツールを制限なく利用でき、テレメトリはオプトイン方式で、デフォルトでは無効です。「無料プラン」はありません。境界線はそこにはありません。

Sverklo Pro（今年後半に提供予定）では、意思決定のスマートな自動記録、プロジェクトを横断したパターン学習、より大規模な埋め込みモデルが追加されます。Sverklo Teamでは、チームで共有できるメモリとオンプレミスでのデプロイが追加されます。

オープンコアの方針は、Pro では新機能を追加し、現在の機能を利用制限することは決してないというものです。現在 OSS サーバーにある機能は、今後もずっと OSS サーバーで利用できます。

リンク

• ウェブサイト
• npm
• 課題
• 初回実行ガイド
• ベンチマーク
• 論文（Zenodo、CC BY 4.0）

Sverklo の引用

研究で Sverklo またはそのベンチマーク（bench:primitives、bench:swe）を使用する場合は、以下のように引用してください。

Groshin, N. (2026). Sverklo: A Local-First Code Intelligence MCP Server and a Cross-Repository Software Engineering Benchmark. Zenodo. https://doi.org/10.5281/zenodo.19802051

BibTeX：

@misc{groshin2026sverklo,
  author    = {Groshin, Nikita},
  title     = {{Sverklo}: A Local-First Code Intelligence {MCP} Server and a Cross-Repository Software Engineering Benchmark},
  year      = {2026},
  publisher = {Zenodo},
  doi       = {10.5281/zenodo.19802051},
  url       = {https://doi.org/10.5281/zenodo.19802051}
}

スターの推移

sverklo によって、コードベースに存在しない関数名を AI がでっち上げるのを防げたなら、最も役立つのは**⭐ このリポジトリにスターを付けること**と、チームメイト 1 人に共有することです。

ライセンス

MIT