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 — sverklo init → audit → 37 MCP tools → live Claude Code integration with blast-radius and symbol-graph traversal.

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

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 that was true then. Full comparison vs codebase-memory-mcp →

…what about Aider, Continue, Codex CLI, Claude Code? Those are agents — they generate and apply edits. Sverklo is the retrieval layer the agent calls before writing code. Use both. sverklo init auto-detects which agents you have →

If something is missing here that you'd ask about, open an issue — I'll add it.

---

What's new in 0.20

• Contradiction detection on the bi-temporal memory layer. memories mode:"conflicts" surfaces pairs of active memories that share a pin (file path or symbol name) and may contradict — e.g., "JWT in middleware" vs "JWT in route handler" both pinned to src/auth.ts. Restricted to decision/preference/pattern categories (procedural/context are additive, not contradicting). Same-SHA pairs are skipped. Sorted by shared-pin count and age. Conservative by design: surfaces candidates for the agent or human to review, not auto-resolution. The bi-temporal model already preserved both sides of the contradiction; this just makes them findable.

What's new in 0.19

• C# (.cs) language support — community contribution by @NerdChieftain in #22. Tree-sitter (when grammar installed) plus a regex fallback parser. Indexes namespaces (block-scoped + C# 10+ file-scoped), classes, structs, records (plain / record class / record struct), interfaces, enums, methods, constructors, and using directives. Adds tree-sitter-c-sharp@0.23.5 WASM grammar to the install set. Sverklo now supports 12 languages.

What's new in 0.18

• Vue.js (.vue) support. Single-file components are now first-class: the <script> block parses through the existing TS/JS pipeline (with line remapping back to the SFC), Composition API helpers (ref, computed, reactive, defineProps, …) are indexed as symbols, and PascalCase template tags emit relative imports so PageRank sees component graphs. Also fixes a preexisting TS bug where import type { X } from 'y' was missed.
• AGENTS.md aware sverklo init. When AGENTS.md exists, the prefer-sverklo block is appended there instead of CLAUDE.md. sverklo doctor flags drift between the two files so multi-agent setups stay in sync.
• Windows pathing fixed. sverklo init and sverklo doctor now work on Windows — absolute paths go through path.basename() and stored relativePath is normalized to forward slashes so every downstream consumer is cross-platform.
• npm run bench:swe — third-party-reproducible cross-repo eval. Clones 5 OSS repos (express, nestjs, vite, prisma, fastapi), runs 65 grounded questions, prints aggregated recall. PRs that add questions are welcome.
• Tree-sitter parser opt-in. sverklo grammars install (~3.5 MB across 6 languages) + SVERKLO_PARSER=tree-sitter routes the indexer through real ASTs for TypeScript/TSX/JavaScript/Python/Go/Rust. Silent regex fallback when grammars aren't installed. Plan to flip the default lives in docs/parser-parity.md.
• Workspace shared memory. sverklo workspace memory <name> add/list/search plus remember scope:"workspace" from the agent — write a decision once, query it from every other repo in the workspace. recall blends workspace results under project ones with a [ws] badge.
• sverklo memory export — markdown / Notion / JSON. Migrate your team's decision log to wherever it actually lives.
• PR-bot inline review. sverklo review --format github-review-json + the action's new inline-comments: true default posts per-line review comments via pulls.createReview, alongside the existing sticky summary.
• VS Code extension scaffold at extensions/vscode/ with a pre-built sverklo-vscode-0.1.0.vsix. Inline caller-count decorations on every function header (⟵ 47 callers). Marketplace publish workflow ships dormant; install with code --install-extension extensions/vscode/sverklo-vscode-0.1.0.vsix today.
• sverklo digest [--since 7d] — 5-line summary of audit-grade trend, new vs stale memories, and high-PageRank files touched. Wire into a shell-hook on cd for a daily sverklo check-in.

---

Grep vs Sverklo — the same question, side by side

Every one of these is a query a real engineer asked a real AI assistant last week. Grep gives you lines. Sverklo gives you a ranked answer.

The question	With Grep	With Sverklo
"Where is auth handled in this repo?"	grep -r 'auth' . -- 847 matches across tests, comments, unrelated vars, and one 2021 TODO	search "authentication flow" -- top 5 files ranked by PageRank: middleware, JWT verifier, session store, login route, logout route
"Can I safely rename BillingAccount.charge?"	grep '\.charge(' -- 312 matches polluted by recharge, discharge, Battery.charge fixtures	impact BillingAccount.charge -- 14 real callers, depth-ranked, with file paths and line numbers
"Is this helper actually used anywhere?"	grep -r 'parseFoo' . -- 4 matches in 3 files. Are any real, or just string mentions? Read each one.	refs parseFoo -- 0 real callers. Zero. Walk the symbol graph, not the text. Delete the function.
"What's load-bearing in this codebase?"	find . -name '*.ts' | xargs wc -l | sort -- the biggest files. Not the most important ones.	overview -- PageRank over the dep graph. The files the rest of the repo depends on, not the ones someone wrote too much code in.
"Review this 40-file PR — what should I read first?"	Read them in the order git diff printed them	review_diff -- risk-scored per file (touched-symbol importance x coverage x churn), prioritized order, flagged production files with no test changes

If the answer to your question is "exact string X exists somewhere," grep wins. Use grep. If the answer is "which 5 files actually matter here, ranked by the graph," you need sverklo.

---

Works with every MCP editor

Editor	MCP	Skills	Hooks	Auto-setup
Claude Code	yes	yes	yes	sverklo init
Cursor	yes	—	—	sverklo init
Windsurf	yes	—	—	sverklo init
Zed	yes	—	—	sverklo init
VS Code	yes	—	—	manual
JetBrains	yes	—	—	manual
Antigravity	yes	—	—	sverklo init
Codex CLI	yes	—	—	sverklo init
GitHub Copilot CLI	yes	—	—	sverklo init
Any MCP client	yes	—	—	npx sverklo /path

---

Hero tools

Tool	What it does
search	Hybrid BM25 + vector + PageRank search. Find code without knowing the literal string.
refs	All references to a symbol, with caller context. Flags likely dead-code candidates from the current reference graph.
impact	Walk the symbol graph, return ranked transitive callers — the real blast radius.
review_diff	Risk-scored review of git diff: touched-symbol importance x coverage x churn.

See all 37 tools below.

Pre-commit gate — block architectural regressions before they ship

sverklo audit-diff is a local-first incremental quality gate. It reads git diff, runs Tarjan SCC over the modified files' boundary subgraph, and exits non-zero if your diff introduces a new circular dependency or pushes a file's fan-in past the threshold. Designed to run as a .git/hooks/pre-commit step — typical run completes well under 200 ms.

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

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

Wire it as a pre-commit hook (plain git):

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

Husky variant:

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

Pre-existing cycles and fan-in spikes don't trip the gate — only violations introduced by your diff. To inspect legacy debt: sverklo audit-diff --show-existing (exit code is unchanged).

Search — find code without knowing the literal string

Tool	What
search	Hybrid BM25 + ONNX vector + PageRank, fused with Reciprocal Rank Fusion
search_iterative	Wider candidate pool with refinement hints between rounds
investigate	Parallel multi-channel fan-out (FTS / vector / path / symbol) with per-channel RRF
ask	Natural-language router — concepts + investigate + refs in one call
overview	Structural codebase map ranked by PageRank importance
lookup	Find any function, class, or type by name (typo-tolerant)
context	One-call onboarding — combines overview, code, and saved memories
ast_grep	Structural pattern matching across the AST, not just text
concepts	Browse the LLM-derived concept index (themes across the codebase)
clusters	Semantic clusters of related symbols, computed offline
patterns	Query symbols tagged with a design pattern (observer, repository, validator, ...)

Impact — refactor without the regression

Tool	What
impact	Walk the symbol graph, return ranked transitive callers (the real blast radius)
refs	Find all references to a symbol, with caller context
deps	File dependency graph — both directions, importers and imports
audit	Lint your codebase for AI-readiness. God nodes, hub files, dead code, circular deps, security smells, A-F health grade — all in one call

Review — diff-aware MR review with risk scoring

Tool	What
review_diff	Risk-scored review of git diff — touched-symbol importance x coverage x churn
critique	Second-pass critique of a review — what did the first read miss
test_map	Which tests cover which changed symbols; flag untested production changes
diff_search	Semantic search restricted to the changed surface of a diff
verify	Verify a quoted code span is still present at the cited SHA — citation gate

Memory — bi-temporal, git-aware, never stale

Tool	What
remember	Save decisions, patterns, invariants — pinned to the current git SHA
recall	Semantic search over saved memories with staleness detection
memories	List all memories with health metrics (still valid / stale / orphaned)
forget	Delete a memory
promote / demote	Move memories between tiers (core / archive)
pin / unpin	Pin a memory to a file path or symbol so recall surfaces it without semantic search

Post-filter primitives — refine the last response without re-querying

Tool	What
grep_results	Grep inside the previous result block instead of re-running the search
head_results	Take the first N hits from the previous response
ctx_peek	Peek at a referenced span by its handle without expanding it fully
ctx_slice	Slice a stored response by line range
ctx_grep	Grep within a stored context window
ctx_stats	Token-budget stats for stored response handles

Index health

Tool	What
status	Index health check, file counts, last update
wakeup	500-token codebase summary for system prompts on agents that can't run MCP

---

When to reach for sverklo — and when not to

We're honest about this. Sverklo isn't a magic 5x speedup and it doesn't replace grep. It's a sharper tool for specific jobs.

When sverklo earns its keep:

• You don't know exactly what to search for
• You need to prove dead code (zero references across the whole symbol graph)
• You need the blast radius of a refactor before you start
• You're reviewing a large PR and need to know what to read first