Sverklo：coding agent のための local repo memory
AI coding agent は、かなり手を動かせる同僚に近づいてきた。ただし、つまずきやすい場所は残っている。今開いている file は直せるが、その function が何箇所から呼ばれているかまでは見えていない。grep の結果は読めるが、dependency graph の中でどの file が重要かは分からない。Context window に残っている決定には従えるが、compaction、restart、別 session のあとには、昨日の project convention をまた説明し直すことになる。
この問題は雑に言うと「model にもっと context を渡せばよい」に見える。しかし実際の repository では、context が大きいほどよいとは限らない。十数個の file を prompt に入れると token は増え、焦点はぼやけ、agent は古い実装と新しい実装を混ぜることがある。必要なのはむしろ、編集前に「関連する symbol は何か、誰が呼んでいるか、この diff の risk surface はどこか、この module について team は以前どんな decision をしたか」を答える能力だ。
今日見るのは sverklo/sverklo。自分たちでは repo memory for coding agents と位置づけている。Claude Code、Cursor、Windsurf、Codex CLI、その他 MCP client に対して、code retrieval、symbol relationship、blast radius、diff-aware review、git-pinned decisions を提供する local-first MCP server だ。Agent を置き換える editor ではなく、agent が code を書く前に、より信頼できる repository map を渡す layer と見たほうがよい。
GitHub repository API、README、LICENSE、Releases、Tags、recent commits を 2026-08-14 時点で確認すると、sverklo/sverklo は 76 stars、11 forks。主要言語は TypeScript。GitHub repository API は license を MIT と報告しており、LICENSE file も MIT text だ。Repository created time は 2026-04-06 16:51:31 UTC、latest public push は 2026-08-12 15:48:37 UTC、default branch は main。最新 GitHub Release は v0.29.5、published time は 2026-08-12 15:49:10 UTC。Recent commit は b0a7b81、message は “chore(release): v0.29.5”。package.json 上の npm package name は sverklo、version も 0.29.5、CLI bin は sverklo、runtime requirement は Node.js >= 24.0.0 になっている。
プロジェクト概要
| 項目 | 内容 |
|---|---|
| リポジトリ | sverklo/sverklo |
| 位置づけ | coding agent 向け local repo memory / MCP server |
| Stars | 76 |
| Forks | 11 |
| 主要言語 | TypeScript |
| ライセンス | MIT |
| 作成日時 | 2026-04-06 16:51:31 UTC |
| Latest push | 2026-08-12 15:48:37 UTC |
| Default branch | main |
| 最新 GitHub Release | v0.29.5、2026-08-12 15:49:10 UTC |
| Recent commit | b0a7b81、chore(release): v0.29.5 |
| キーワード | MCP、repo memory、symbol graph、semantic search、diff review、local-first |
解いているのは agent の「編集前の視野」
Sverklo の中心にある判断は分かりやすい。Coding agent に足りないのは、よりきれいな chat box ではなく、編集前に repository の関係を理解する力だ。README では symbols、callers、diffs、blast radius、git-pinned decisions といった言葉が繰り返し出てくる。関心は「この code を生成して」ではなく、「この code を変える前に、repository 内でそれが何を意味するか教えて」にある。
この種の tool は、大きめの repository ほど価値が分かりやすい。たとえば agent が UserService.validate() を変更するとする。Context window だけなら、見えているのは現在の file と隣の test かもしれない。通常の text search なら、comment、mock、古い path、同名 helper を含む大量の match が返る。Sverklo が目指すのは、より構造化された答えだ。実際の references、callers、dependency path、影響しそうな tests、そして diff の中で相対的に重要な file を返す。
Agent に見せるのも、単一の search endpoint ではない。README に出てくる代表的な機能には、hybrid BM25 + vector + PageRank search、refs、impact、review_diff、audit-diff などがある。つまり、経験ある maintainer が頭の中に持っている repository map を、agent が呼べる tool 群に分けようとしている。すべての file を一度に prompt へ詰め込む発想とは違う。
local-first が hosted code search との境界になる
Sverklo のもう一つの明確な選択は local-first だ。README では bundled local embeddings が default、remote embeddings は明示的に設定した場合だけ、telemetry は opt-in で default off と説明している。Default path では、index、symbol graph、memory layer は手元の repository を中心に動く。Bundled embedding provider を初めて使うときは all-MiniLM-L6-v2 ONNX model を ~/.sverklo/models/ に download し、その後は local cache から動かせる。
これは agent workflow では重要だ。AI に code を手伝わせたい team は多いが、private repository 全体を外部の code search service に渡したくない team も多い。Hosted tool は、team collaboration や permission management では強いかもしれない。一方で「手元の Claude Code や Codex に、この repo を編集前に理解させたい」という用途なら、local MCP server の deployment boundary は受け入れやすい。
README は grep も雑に否定していない。正確な文字列が分かっている、repository が小さい、変更が一 file に閉じているなら grep/ripgrep を使えばよいと書いている。Sverklo が向くのは、名前が曖昧、関係で ranking したい、call chain を見たい、diff risk を見たい、team decision を git SHA と結びつけて残したい、といった場面だ。
no-write proof は試しやすい入口
Repo memory 系 tool の難点は、最初から agent config を入れ、project instruction file を書き、index を初期化させられることだ。試す前の friction が高い。Sverklo の README は、まず no-write proof command から始めることを勧めている。
cd your-project
npm exec --yes --package=sverklo@latest -- sverklo prove --no-write --guided --markdownこの command の目的は、すぐ MCP config を書き換えることではない。Project file を変更せずに、一度だけ確認できる repository context proof を出すことだ。Central files、実在する symbol と callers、その proof を選んだ理由、agent に貼れる prompt、簡単な feedback template を表示する。その後で sverklo init --dry-run により触る file を preview し、sverklo init で MCP config と local instructions を書き、sverklo doctor で handshake を検証する流れになる。
この入口はかなり実務的だ。Retrieval layer は、説明だけでは強そうに見えがちだが、自分の repository で本当に効くかは別問題だ。No-write proof を先に走らせれば、見つけた symbol、callers、risk hint が実際の構造に合っているかを早く判断できる。最初の proof がずれているなら、install まで進む必要はない。
git-pinned memory は普通の「記憶」より具体的
Agent memory はかなり混み合った領域になっている。多くの実装は、text fragment を vector DB に入れて、次回に similarity search するものだ。それ自体は有用だが、code repository では問題が出る。Project decision は期限切れになる。ある architecture choice は commit abc123 の時点では正しいが、三週間後の refactor ではもう当てはまらないかもしれない。Memory がどの code state に属するかを知らないと、agent に古い事実を渡しやすい。
Sverklo の README では bi-temporal memory と git-pinned decisions が強調されている。たとえば valid_from_sha、valid_until_sha、superseded_by のような状態を扱う。この design は「long-term memory」という広い言葉よりかなり具体的だ。Code knowledge は永遠の事実ではなく、commit history と結びついた engineering fact だと認めている。
Multi-agent や長期 maintenance では、この方向は見る価値がある。ある agent が今日「auth logic は middleware に置く」と記録し、別の agent が来週 route handler を触るとき、その decision がどの commit 以降で有効か、すでに supersede されていないかを知れれば、古い convention を誤用する確率は下がる。
Caveats
Sverklo はまだ若い。76 stars、11 forks なので、early attention はあるが、成熟した infrastructure と呼べる community size ではない。Release は最近かなり頻繁で、活発さとしては良い。一方で API や behavior がまだ動く可能性もある。Team の main workflow に入れる前に、critical ではない repository で indexing speed、result quality、MCP handshake、memory usage、false positive を見たほうがよい。
二つ目の threshold は runtime だ。package.json は Node.js >= 24.0.0 を要求している。多くの project がまだ Node 20/22 に固定されていることを考えると、これは少し先に行っている。Developer machine や CI で runtime を別管理する必要があるかもしれない。Default local embedding model も初回は download が必要なので、offline environment では cache を先に用意する必要がある。
三つ目に、Sverklo は exact search の代わりではない。探したい文字列が分かっているなら rg のほうが直接的だ。これは人間向けの万能 search UI というより、agent の repository awareness layer と考えるほうが自然だ。毎回の edit 前にいくつか構造化された問いを投げる tool、と位置づけると期待値が合う。
まとめ
sverklo/sverklo が面白いのは、agent programming で繰り返し出てくる問題をかなり具体的に分解しているところだ。Model が code を書く前に必要なのは、より多くの file ではなく、よりよい relationship graph、risk ranking、そして時間の境界を持った project memory なのだ、という見方である。
Project はまだ小さく、Node version requirement も新しめだ。それでも方向は今の CLI agent workflow に近い。Local repository、local MCP、symbol graph、blast radius、diff review、git-pinned decisions。Claude Code、Codex CLI、Cursor、Windsurf をすでに使っている developer なら、まず no-write proof を自分の repository で走らせ、その repo memory が grep output より maintainer 視点に近いかを見てみる価値はある。