Sverklo

🇬🇧 English · 🇨🇳 中文

Give your coding agent repo memory.

Sverklo gives coding agents repo memory: symbols, callers, diffs, blast radius, and git-pinned decisions before they edit. It is an open-source local-first MCP server for Claude Code, Cursor, Windsurf, Codex CLI, and any MCP-speaking coding agent.

Local-first ◦ MIT ◦ bundled local embeddings by default ◦ remote embeddings only when explicitly configured ◦ telemetry opt-in and off by default

Use Sverklo when your agent needs relationships before editing: callers, dependencies, tests, diff risk, or prior repo decisions.

Use grep/ripgrep when you know the exact string, the repo is tiny, or the change is one file.

Start with the no-write proof command before installing MCP config. The public bench covers 180 hand-verified tasks across 6 OSS codebases; the methodology and ground truth live in sverklo/sverklo-bench. Bench · paper · 90-second demo

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 shows central files, a real symbol with callers, why that proof was selected, the exact prompt to paste into your agent, and a small feedback template before any MCP config or instruction files are written. It may cache the local model/index under ~/.sverklo, but it does not mutate your project. sverklo init --dry-run then previews the files init would touch; sverklo init writes the MCP config for your agent, appends local instructions to AGENTS.md or CLAUDE.md, and runs sverklo doctor to verify the handshake. With the bundled provider, code indexing and embeddings stay on your machine. An explicitly configured remote embedding provider receives the code chunks it embeds.

Need something shareable? Run sverklo prove --no-write --guided --markdown to print a GitHub/Discord-ready proof receipt from your repo, then post it in the proof thread.

Latest no-write proof run: on calesthio/OpenMontage@9066dcb (1,284 indexed files), Sverklo selected ToolResult at tools/base_tool.py:120 and found 475 references across 81 files. The legacy token-efficiency demo on the same checkout used 21.9× fewer estimated input tokens than grep+reading the top 10 matched files, with one miss called out plainly. Read the receipt · OpenMontage discussion

Need local launch planning for the Sverklo account? sverklo marketing runs a local-first Twitter/X agent-team workflow from operator-provided snapshots. It ranks opportunities, drafts seed-content queues, checks profile health, and records human decisions without posting, scraping, replying, liking, reposting, following, or changing the profile.

*"The map is not the territory."* — Alfred Korzybski

Training data is the map. Your codebase is the territory. Sverklo gives the agent the territory.

Editor shortcuts

If sverklo prove surfaces useful repo context, please post a receipt, correction, grep-better case, or setup-friction report in the proof thread. If it helped, starring the repo also helps other agent-heavy teams find it.

▶ [Watch the 90-second demo on YouTube](https://www.youtube.com/watch?v=OX7aEgdlqhQ) — sverklo init → audit → 37 MCP tools → live Claude Code integration with blast-radius and symbol-graph traversal.

Updates

• 2026-05-04 — v0.20.2: parser brace-counter + lookup exact-match fixes. Lodash P1 0/10 → 9/10. Overall F1 0.45 → 0.56 (now leader on the public bench). release notes
• 2026-05-04 — Bench expanded to 3 datasets, 5 baselines, 90 tasks. Lodash 4.17.21 added per #26. sv-p5 ground truth refined per #27.
• 2026-05-03 — v0.20.1: sverklo receipt ships — token-spend summary parsed from ~/.claude/projects/**/*.jsonl. why we built it
• 2026-05-02 — Bench-as-feedback-loop story: 5-baseline expansion exposes blind spots on both sides of the bench. issue #25
• 2026-05-01 — MCP STDIO command-injection audit: the class Anthropic won't patch, and the 30-second audit any maintainer can run.

Why

Your AI agent edits UserService.validate(). It doesn't know 47 other functions call it. It hallucinates getUserByEmail() because that's how its training data spelled it — your code uses findByEmail(). It forgets the design decision you made yesterday because context was compacted. Tests pass because they mock the dependency. Breaking changes ship.

Sverklo drills into your repo before the agent does — symbol graph, blast radius, semantic recall, and git-pinned memory — so the agent reasons about *your* code instead of pattern-matching from training data.

37 MCP tools your agent uses < 1 s incremental refresh after each edit local-first bundled embeddings stay on-device by default

cd your-project

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

That's it. sverklo prove --no-write --guided gives you the first useful repo-memory proof from your own codebase before project config changes; sverklo init --dry-run previews every setup target; sverklo init auto-detects your installed AI coding agent (Claude Code, Cursor, Windsurf, Zed), writes the right MCP config, appends instructions to AGENTS.md if present (otherwise CLAUDE.md), and runs sverklo doctor to verify the setup. sverklo prove --markdown makes that proof shareable in the public proof thread. Works on macOS, Linux, and Windows. Bundled local embeddings by default. Remote embeddings only when explicitly configured. Telemetry opt-in and off by default.

The bundled embedding model (all-MiniLM-L6-v2 ONNX, ~86 MB) is downloaded from HuggingFace on first use into ~/.sverklo/models/. After that download, the bundled embedding provider can run from the cached local model. An explicitly configured remote provider uses its remote endpoint instead.

Want proof before installing? Browse the /report leaderboard — Sverklo audits of 47 popular OSS repos (express, react-hook-form, vite, lodash, prisma, …) with grade cards for dead code, circular deps, coupling, and security.

---

"But isn't this just…?"

Likely you've seen tools that look adjacent. The honest one-paragraph answers, with detailed comparisons linked.

…just grep with extra steps? No, but tuned grep is genuinely competitive when you know the exact string. On the 180-task bench, sverklo leads overall F1 (0.58 vs smart-grep's 0.34) while using about 35× fewer input tokens than naive grep and one tool call per task. For an AI agent inside a 200K context window, that's the load-bearing axis. For a human at a terminal, grep is still fine.

…just Sourcegraph Cody? Same retrieval surface (hybrid BM25 + vector + graph), different deployment model and license. Cody is source-available with enterprise per-developer pricing ($9-19/dev/mo); sverklo is MIT and runs on a laptop with no signup. Full comparison →

…just Greptile? Greptile is a hosted PR-review bot ($30/dev/mo). Sverklo is local-first MCP. Same risk-scoring goal, opposite deployment model. If your code can't leave the machine for compliance reasons, Greptile isn't an option. Full comparison →

…just Cursor's @codebase? Cursor's indexing is cloud-based and editor-bound. Sverklo runs alongside Cursor as an MCP server, adding the symbol graph, blast-radius, and bi-temporal memory that Cursor's @codebase doesn't expose. Full comparison →

…just Claude Context (Zilliz)? Claude Context requires a Milvus database. Sverklo runs entirely on embedded SQLite — no extra services to manage. Full comparison →

…just Aider's repo-map? Aider's repo-map is a static signal in the system prompt — fine for small repos, doesn't scale past ~100 files. Sverklo is the queryable retrieval layer Aider can call via MCP for larger codebases. They're complementary, not competing. Full comparison →

…a niche memory MCP? Most memory MCPs are wrappers around an external vector DB. Sverklo's memory is bi-temporal (valid_from_sha, valid_until_sha, superseded_by) and pinned to git SHAs, so you can ask "what did this team believe about auth at commit abc123?" and get the answer