Sverklo Is Not Just Grep with Embeddings: Verify the Code-Memory Evidence Chain

Many coding agents do not fail because a model forgot a sentence from the previous chat. They fail because the agent has no context layer that can explain where a code fact came from, how wide it applies, and whether it is still fresh. Sverklo is interesting as an engineering hypothesis: a local-first MCP server that combines repository indexing, symbol graphs, dependency tracing, diff-aware review, and persistent memory. The useful question is not whether it sounds like an intelligent search box. It is whether an agent can receive repository context that a human can replay and verify.

The upstream entry point is npm install -g sverklo, with Node.js >= 24 as the stated runtime. A successful install only proves that the CLI can be found. It does not prove that the index is complete, that the current repository is being served, or that the MCP client is calling the intended tool. I would start in a disposable test repository instead of binding the first run to a production workspace or the global registry.

I would make the first acceptance run observable at four layers. First, file discovery: does the index include the expected paths, honor ignore rules, and produce a plausible file count after reindexing? Second, code structure: can lookup find a known symbol, and do refs, deps, and impact return relationships rather than a list of filenames? Third, context delivery: does the context tool provide a useful onboarding bundle, and does a supplied token budget produce a smaller PageRank-pruned repository map? Fourth, the memory ledger: can a memory with a project scope, kind, related file, and time metadata be recalled, and does changing that file make the memory visibly stale?

Sverklo is not described as a single vector retriever. The Doramagic manual maps its retrieval surface to BM25 keywords, ONNX embeddings, and a PageRank symbol graph fused across signals. Search hits expose found_by, which gives the operator a way to tell whether multiple retrievers agree. There is an important boundary here: exact strings still belong to Grep/Read. Sverklo is better suited to exploration, dependency graphs, refactor blast radius, and semantic questions. Sending every query through embeddings would make the workflow less predictable and contradict the server's own MCP guidance.

An acceptance script can stay small and repeatable:

1. Create a temporary repository with a few modules, a test, a README, and one intentionally broken dependency.
2. Run sverklo init, register the project, and wait for indexing. Record the Node version, project name, index timestamp, and file count.
3. Call context for onboarding and pass a small budget; check whether the returned map actually contracts with the budget.
4. Use lookup on a known symbol, then use refs, deps, and impact to trace callers, dependencies, and change scope.
5. Write one file-pinned decision with remember, edit that file, and inspect sverklo://context or recall for an explicit stale signal.
6. Run review_diff on a small change and confirm that the result contains both readable Markdown and structured findings with path, line, and severity anchors.

The lifecycle is where a seemingly healthy setup can mislead an automation. Sverklo stores registered projects in ~/.sverklo/registry.json. The manual records issue #74: reindex can finish while leaving lastIndexed stale, so the timestamp in sverklo list is advisory rather than proof that the current index is fresh. After reindexing, automation should register again or read the index status and file evidence directly. Issue #73 reports that unregister takes the internal project name, not an absolute path. A worktree cleanup script should therefore resolve the name from sverklo list before unregistering.

MCP naming has another quiet production boundary. Sverklo already exposes internal sverklo_ tool prefixes. If a host also prefixes tool names using the server key, a name such as sverklo_sverklo_impact can appear. A connected badge is not enough. After integration, enumerate the tools and make one real call to context, lookup, or status so the host's names and response shape are verified.

My operator rule is to treat Sverklo as an observable local code-context candidate, not as an agent brain that becomes trustworthy after installation. Before putting it in a real workspace, retain four kinds of readback: index scope and freshness, symbol/dependency results, stale-memory behavior, and structured diff-review output. Without those artifacts, the only defensible claim is that the CLI started.

This is an independent Doramagic capability pack, not an official Sverklo release or endorsement. Project page: https://doramagic.ai/en/projects/sverklo/; Human Manual: https://doramagic.ai/en/projects/sverklo/manual/; upstream: https://github.com/sverklo/sverklo.

Comments

[Luis]

I found the concept of a local-first MCP server in Sverklo to be particularly intriguing, as it combines repository indexing, symbol graphs, and persistent memory to provide a more comprehensive context layer for coding agents. The idea of verifying the code-memory evidence chain through a series of acceptance tests, such as file discovery and context delivery, is a great way to ensure that the index is complete and accurate. I'm curious to know more about how the remember function works in terms of storing file-pinned decisions and tracking changes to files, and how this information can be used to improve the overall development workflow. Can you elaborate on the trade-offs between using Sverklo's embedded retrievers versus relying on external tools like Grep or Read for exact string searches?