Cursor’s indexer is excellent inside Cursor. Tab complete, inline edit, chat, and the agent inside that window already sit on top of a project index Cursor operates for the opened workspace. If Cursor is the only surface you write in, and that index already finds the right files, stay there. That is the honest stay-put case, and it is the right first sentence of this page.
\nThis piece is about the other half of a common week. The same repository is also opened in Claude Code, asked about from Codex CLI, reviewed on a second machine, or queried by an agent running in CI. The question is not “which indexer is better.” The question is whether the map the agent trusts in one window is the same map it trusts in the next.
\nMaguyva is that traveling map. It is a remote MCP codebase-context layer. The agent queries it the same way it queries any other MCP tool. Results come back as ranked paths with line numbers. Cursor stays the editor. The context is what moves.
\nCursor’s built-in indexing exists so chat, agent, and search inside the editor can retrieve relevant code instead of relying only on whatever fits in the model’s raw context window. That is the right design for an IDE. The index is native to Cursor. It is not an MCP server and is not reachable from any other client.
\nHow it works, as described in Cursor’s public docs and Cursor’s own account at time of writing: the primary search path is no longer a cloud-embedding index. Cursor’s team stated on their community forum that dedicated semantic/embedding-based search is being wound down in favor of grep-based retrieval, because current models search a live tree well enough on their own without one. In its place is Instant Grep, a local search index built from n-grams, inverted lists, and bloom filters, kept in a memory-mapped lookup table so queries resolve on the developer’s own machine rather than a server.
\nThe index itself lives inside the repository’s own .git/cursor/ directory, anchored to a specific git commit; edits since that commit layer on top of it instead of triggering a rescan, and the index only rebuilds when local state has drifted far from what it was built against. Because it sits inside .git, it is never tracked and never pushed — delete the folder and the index is gone. .gitignore is respected by construction, since only git-tracked content is eligible, and .cursorignore is enforced on the read path. There is no server-side embedding step and no remote vector database in that path anymore. Earlier docs described a cloud-assisted design — chunk encryption, a Merkle-tree sync, cross-teammate index reuse — and Cursor’s own team has since said that design is being turned down, so this piece no longer describes it as current.
A standout inside the editor is Cursor’s Explore subagent. It can spawn multiple parallel searches in its own context window on a faster model and return only the relevant findings, so the main conversation does not swell with search hits. That is a genuine in-editor strength. Keep it.
\nMulti-root workspaces are supported: each opened folder’s context is available to Agent. Some git-dependent features such as worktrees are disabled in multi-root setups, and Cloud Agents do not support multi-root workspaces at all.
\nNone of that is a reason to leave Cursor. It is a precise description of a map that is excellent where it lives.
\nA map travels when the same questions return the same kind of answer, with citations you can open, from more than one client.
\nparseConfig defined, and who calls it?”If each surface builds its own private index, you do not have one map. You have several caches that drift. The editor index can be current for the tree on disk. The CLI session can be a day behind. The CI job can be looking at a different checkout. The agent will still sound confident.
\nCursor’s indexer is not supposed to solve that. Because it lives inside the editor, the context it builds is for that editor. A reader who also needs a CLI, a CI pipeline, or a different editor needs a separate tool for those surfaces. That is a scope fact, not a defect. Maguyva is the separate tool.
\nA published language count for Cursor’s indexer is not stated in the notes this draft is allowed to use. Maguyva publishes 279+ languages and text-based technologies. Pricing for Cursor is likewise not copied here; see their pricing page. Maguyva bills per workspace, not per seat, with published plans at $0, $19, $49, and $149 depending on indexed footprint and workspace size.
\nMaguyva is a remote MCP server. You connect GitHub, pick the repositories, and the cloud pipeline builds symbols, graph edges, and a ranked map. You add an API key to the MCP config of the client you already use. Maguyva has setup guides for 24 documented MCP clients — including Cursor — and can connect to other MCP-compatible clients that support standard MCP configuration.
\nThe Cursor setup page is the editor-specific path if that is where you work. The same server answers Claude Code, VS Code, Windsurf, Codex CLI, and the rest. You do not switch editors. You give every agent the same tool surface: 11 customer-facing MCP tools across search, symbols, dependency analysis, file retrieval, repository context, and deterministic utility workflows. Semantic, structural, graph, and text retrieval are fused into ranked results.
\nThat is the portability benefit. The citations you graded in Cursor this morning are the same shape of citations Codex CLI will return tonight. File path and line number. Open them. If they are wrong, you see it. If they are right, the next edit has a place to land. The approved claim is fewer hallucinated edits, not a promise that every edit is correct.
\nFreshness is published. Snapshots are timestamped, so the agent knows which version it is reading. Rebuild cadence is daily on the free plan and hourly on paid plans. The honest limit is un-synced local work: an edit that exists only in a working tree is not in the hosted map yet. That limit is the same no matter which client you query from, which is the point. Drift between clients is no longer a second, hidden limit.
\nThe docs give the activation loop that applies to every client: index one repo you already know, connect the client, ask one question you can verify. Do that once in Cursor. Do it again from the CLI you actually use on review days. If both answers cite the same handler, the map traveled.
\nUse both. They are not alternatives in the comparison-page sense.
\nThe editor index remains the best tool for “what is on disk in this window, right now.” The hosted map is the best tool for “what does this workspace look like to every agent that will touch it today.” Those sentences do not compete.
\nWorkspace quotas are published on the pricing page: repos, indexed lines, and users, billed per workspace. Agents and humans share the same user count. Start free on a repo you can already grade. Raise the workspace only after the citations survive contact with the tree.
\nIt does not claim that Cursor’s indexer is weak, incomplete, or a reason to switch editors. The first sentence of this draft is the opposite.
\nIt does not claim Maguyva replaces Instant Grep or the Explore subagent. Those are Cursor features. They stay in Cursor.
\nIt does not invent a language count, a latency figure, or a token-savings number for either product. Unknown figures stay unpublished.
\nIt does not pretend un-pushed local work is in the hosted map. Timestamped snapshots make that limit visible. They do not remove it.
\nThe test is ordinary. Index one repo you already know. Ask one question you can verify, first in Cursor, then in a second MCP client. Context that travels is the same citation in both places.
\n// same map, wherever you opened it.
Two different jobs sit on either side of a pull request. Before the agent writes, it needs a map of the tree it is about to change. After the agent opens a PR, something should read that change against the rest of the system and leave comments a human can act on.
\nThose jobs look similar from a distance because both involve “understanding the codebase.” They are not the same product. One answers “where should this edit land?” The other answers “what did this diff break that a line-by-line linter will miss?” Mixing them up produces a worse first draft and a noisier review.
\nThis piece is a joint-workflow guide. Maguyva is the map the agent queries first. Greptile is the review agent that comments on the PR second. The pairing is complementary by construction: Maguyva does not review pull requests, and Greptile does not replace the context layer the agent used to write them.
\nA coding agent that starts from training priors plus a few pasted files will invent a plausible path and edit it. That is the wrong-file failure, and it is a retrieval problem. Maguyva is a remote MCP codebase-context layer: semantic, structural (AST), graph/dependency, and text retrieval fused into ranked results, plus symbol lookup and file fetch. Grounded answers come back as path/file.ext:line so you can reject a miss before a patch exists. The claim stays modest: fewer hallucinated edits. The model can still guess. The first step stops being a guess.
Greptile is an AI code review agent. In their own words, it automatically reviews every pull request with complete understanding of the codebase, and it positions that against traditional linters that check files in isolation rather than the whole system. Setup is installing the GitHub or GitLab app and selecting repositories. There is no local index for you to operate. Hosting is Greptile Cloud (they state SOC 2 Type II compliance, with a report available on request), with a self-hosted option offered for enterprises.
\nTheir own numbered flow is: connect and build a dependency graph of every function, class, and dependency; on every pull request, analyze the change using that full-repo graph and post findings as PR comments with suggested fixes, in about three minutes; each comment can hand the issue to a coding agent the team already uses. They also state they read prior human PR comments over time to learn a team’s coding standards and reduce noisy suggestions. Their learning system is stated to need 2–3 weeks to adapt.
\nThat is review, not drafting. Greptile’s standout is full-repository graph context on the change that already landed in a PR, then a closed loop that sends the finding to Claude Code, Codex, Conductor, Cursor, or Devin. Maguyva’s standout is the ranked map the agent queried before that change was written. Use both. Do not ask either to do the other’s job.
\nA first-party Maguyva–Greptile product integration is not stated. You do not need one. Maguyva talks to the agent over MCP. Greptile talks to GitHub or GitLab through their app. They meet at the pull request. No glue script, no cron that pipes one tool into the other. The pairing is bash-free because each product already sits on the surface it owns.
\nThis is not a teardown of Greptile. It is not a “switch your reviewer” page. Greptile launched on Hacker News on 5 March 2024 as a Y Combinator W24 company, and that thread is how a lot of people first met the product. If that is how you found them, keep them. This page is the missing front half of that loop: ground the agent so the PR Greptile sees is already aimed at the right files.
\nGreptile’s marketing materials lead with review-speed and bug-catch claims. Treat those as Greptile’s own claims, not independently verified numbers. This draft does not repeat them as facts.
\nLanguage coverage is the same kind of honesty. Greptile frames support as covering all programming languages rather than an enumerated list; a precise count is not stated. Maguyva publishes 279+ languages and text-based technologies, with a technical split (parser-backed AST versus text-only) on the site when the question is technical. Those are different products making different claims. Do not blend them.
\nPricing for Greptile is not stated in the notes this draft is allowed to use. Paid plans exist; see their pricing page. Maguyva bills per workspace, not per seat. Plans start free. The pricing page lists the published tiers if you need the workspace numbers.
\nThree named stages. Run them in this order. Skip none of them the first time you try the pairing.
\nIndex one repository you already know. Connect the MCP client you already write in — Claude Code, Cursor, Codex CLI, VS Code, Windsurf, or another MCP-compatible client. Maguyva has setup guides for 24 documented MCP clients and can connect to other clients that support standard MCP configuration.
\nAsk a question you can grade before anyone writes a line. “Where is session expiry handled, and what calls it?” is a better first move than “fix auth.” Demand citations. Open the file.ext:line results. Follow the symbol. Confirm the dependency you are about to touch.
Maguyva exposes 11 customer-facing MCP tools across search, symbols, dependency analysis, file retrieval, repository context, and deterministic utility workflows. Four retrieval modes are fused into ranked results; find_symbol is a separate tool when you already know the name. The docs describe the shortest path: start free, index a repo you already know, connect the client, then ask one question you can verify.
Snapshots are timestamped, so the agent can tell which version of the tree it is reading. The honest limit is un-synced local work. If the edit exists only in a working tree and has not been pushed, the hosted map does not contain it yet. Instruction files (CLAUDE.md, AGENTS.md) still belong here for conventions and what not to touch. They are not a live map. Use them for behavior. Use Maguyva for facts.
Do not let the agent open a PR until the citations survive contact with the repo. That gate is the whole point of this stage.
\nThe same agent now writes the change in the client you already pay for. Maguyva is not an editor and not a reviewer. The agent still produces the diff. You still open the pull request on GitHub or GitLab the way you already do.
\nWhat should be different is the first file. The PR should name the handler that actually implements the behavior, the caller that will break, and the test that will fail if the change is wrong. If stage 1 was skipped, stage 3 will spend its comments on a change that landed in the wrong package. Greptile can still find systemic issues. It should not have to also recover from a hallucinated path.
\nKeep the PR scoped. A grounded first file is not a license to rewrite the module. The complementary pairing works when the agent did one job with a map, then asked a reviewer to do a different job on a bounded diff.
\nGreptile is already connected to the repository through the GitHub or GitLab app. On the new pull request it analyzes the change using the full-repo graph it built and posts findings as comments with suggested fixes. Their own materials put that pass at about three minutes.
\nRead the comments the way you would read a careful teammate: open the cited location, decide whether the finding is real, then act. Where Greptile offers “Fix with your Agent,” it sends the issue — file paths, line numbers, suggested code — to Claude Code, Codex, Conductor, Cursor, or Devin. “Fix All” sends every issue in the review at once. They also ship a Greptile MCP and a Claude Code plugin for that hand-off. Maguyva is not on that named target list; that absence is not a problem. Maguyva already did its work in stage 1. The coding agent that wrote the PR is the one that should receive the fix payload.
\nExpect noise for the first 2–3 weeks while Greptile’s learning system adapts to the comments your team actually leaves. That is their stated timeline, not a defect in the pairing. Human review stays in the loop. Greptile is the automated first pass, not the merge button.
\nIf a Greptile comment points at a file the agent never queried in stage 1, that is useful signal. Either the map missed a caller, or the agent skipped a citation. Fix the draft against the comment. Do not disable the reviewer.
\nThe loop is ordinary once it is named. Map first. Agent PR. Review second. Each product stays on the side of the pull request it is good at.
\n// map first. review second. in that order.
A large repository doesn’t fit in a context window, and if you’ve ever pointed a laptop indexer at a real monorepo you know it doesn’t fit comfortably there either — the RAM spikes, the first index takes an hour, and your agent still starts the next session guessing which files matter.
\nThe usual answer is to run an indexer next to the editor, and for a repo that fits comfortably on one machine, it’s a good one. If your monorepo already indexes fast in Cursor and that’s the only place you need the map, this post has nothing to add — skip it.
\nThis post is about the other case — when you need an agent to have a queryable map of a large repo, and you don’t want to run a local indexer to get it.
\nA local index assumes the code lives on the machine that will query it, and at real monorepo scale that assumption strains even inside a single editor. The repo is simply bigger than you want to keep warm on a laptop: you work in one package while the blast radius lives three directories over, and a cold first index of a two-million-line tree is not something you want to sit through twice — on your machine, or on a CI runner that never cloned the tree before. Or a teammate should be querying the same map you are, without waiting for their own machine to grind through the same index first.
\nNone of that is a reason to throw away a good editor indexer. It’s a reason to also have a hosted map that any of your agents can query over MCP.
\nAnd the scale problem runs deeper than “too many files to paste.” On a large tree, the interesting question is almost never “show me this file” — it’s which file, which symbol, which callers, which tests. An agent that starts by listing src/ and reading the first three hits will happily miss the handler in apps/api and the generated client in packages/sdk. What you need is retrieval that was built from the whole tree, then ranked, then cited.
Dumping files into the prompt isn’t context — it’s a smaller, worse copy of the tree. What your agent actually needs is to ask questions and get cited answers back: where is this symbol defined and who calls it, what depends on the module I’m about to change, which test file covers this behavior, and what does the tree look like now, not last quarter.
\nThose answers have to come from an index built from your repo rather than from the model’s memory of other people’s repos, and the index has to live somewhere other than the agent’s context window. For this problem, it should also live somewhere other than your laptop.
\nOne more thing instruction files can’t do for you: CLAUDE.md and AGENTS.md are the right place for conventions and behavior, but they are not a live, ranked, queryable map of a two-million-line tree. Use rules for behavior; use repo intelligence for facts.
Maguyva is a remote MCP codebase context layer. You connect GitHub, pick your repositories, and walk away while cloud pipelines parse the tree, build the symbols and graph edges, and keep a ranked map — no local indexer, ever.
\nWhen you push code, changed files are parsed incrementally, and the graph and ranking layers rebuild on a schedule: daily on the free plan, hourly on paid ones. Every snapshot is timestamped, so your agent can tell which version of the tree it’s reading. The honest limit here is un-synced local work — an edit that exists only in your working tree, never pushed, isn’t in the hosted map yet.
\nThen you wire up whichever client you already use by adding an API key to its MCP config. There are setup guides for 24 documented MCP clients, and any other MCP-compatible client that supports standard configuration can connect too. If Cursor is where you live, the Cursor page walks that path; the same server answers Claude Code, VS Code, Windsurf, Codex CLI, and the rest.
\nYou don’t switch editors. You give your agent a tool surface — 11 MCP tools across search, symbols, dependency analysis, file retrieval, and repository context — with coverage across 279+ languages and text-based technologies, which matters more than you’d think on a monorepo that stopped being one language years ago.
\nAnswers come back grounded, as file paths with line numbers. Semantic, structural, graph, and text retrieval are fused into ranked results, so a question like “what depends on parseConfig” gets you neither a grep dump nor a single semantic chunk, but the handful of locations that actually matter.
\nDon’t start by indexing the whole company. Here’s the path that works:
\nfile.ext:line results and check them against the tree in front of you.If the first repo is a good fit and your tree is large, raise the workspace to match your indexed lines and rebuild cadence. Humans and agents share the same user count — Maguyva bills per workspace, not per seat — so adding a third agent to the loop costs you nothing.
\nThe activation test is the same one the docs recommend for any first run: index one repo you already know, ask one question you can verify. A large repo doesn’t change the test; it only makes a wrong first file more expensive.
\nKeep an eye on three things. Freshness: paid plans rebuild hourly, free rebuilds daily, and un-pushed local work will not be in the map — that’s the trade you’re making. Scope: index a representative set of repos, not every archived fork; the free tier is deliberately sized for finding out whether the answers are worth keeping. And verification: a large-repo map that can’t cite paths and line numbers is just a slower guessing engine, so make your agent show you the location before it ships the patch.
\nThen run the same test you’d run on a small repo. Index one repo you already know. Ask one question you can verify. If the map is real, your agent stops starting from a cold tree.
\n// no laptop got hot building this map.
The tell is not a wrong function body. It is a confident edit to a file that does not exist, or to a file that exists but is not the one that implements the behavior.
\nYou asked for a session-expiry fix. The agent opened src/auth/session.ts. That path is plausible. It is also wrong. The real handler lives in apps/api/src/middleware/expiry.ts, renamed two refactors ago. The agent did not lie to you. It completed a path-shaped string from training priors plus whatever was already in the context window.
This is the common failure mode on a real repository. The model can write code. The miss is choosing the wrong place to write it.
\nA coding agent is a next-token model with tools. When you say “fix session expiry”, it has to name a file before it can read or patch anything. If it does not already have a grounded map, it constructs a path from:
\nsrc/auth/session.ts is a frequent shape.CLAUDE.md and AGENTS.md tell the agent how to behave. They are not a live index of symbols, callers, or current paths.None of those sources is a map of this repo, today. The model fills the gap the way it fills any gap: with a high-probability continuation. That continuation often looks like a real path. Sometimes the file exists and is adjacent to the right one. Sometimes it existed on a branch that merged last month. Sometimes it never existed.
\nGrep does not save you here if the agent never searches for the right string. The agent guessed a path, then read whatever that path returned, then edited it. The first wrong step was the path, not the patch.
\nReading files is also not the same as finding the right ones. Claude Code, Cursor, Codex, and similar tools can open whatever you point them at. The question is whether they reliably find the right files, the important symbols, the dependencies, the tests, and the blast radius before they edit. File access without a map still starts with a guess.
\nTreat the invented path as a retrieval miss, not a personality flaw.
\nIf the agent had to return path/file.ext:line before it was allowed to edit, two things would happen. First, you could open the citation and reject the work in ten seconds. Second, the agent would have to query something that actually knows the tree.
That is the job of a codebase context layer. Semantic search alone is not enough. A chunk that “sounds like session expiry” can still land in a deprecated package. You also need exact text when you know the string, symbol lookup when you know the name, structural search when you know the shape, and a dependency graph when you need callers and blast radius.
\nMaguyva is that layer for MCP-compatible coding agents. It is not an editor. Claude Code, Cursor, Codex CLI, VS Code, Windsurf, and other MCP clients stay where they are. The agent queries a ranked map before it touches a line.
\nThe claim is modest on purpose: fewer hallucinated edits. Maguyva does not remove the model’s ability to guess. It changes the default first step from “invent a plausible path” to “ask for ranked, cited locations.”
\nA useful answer to “where is session expiry handled” is not a paragraph. It is a short list of locations:
\napps/api/src/middleware/expiry.ts:48 - the handlerapps/web/src/lib/auth-client.ts:112 - the callerapps/api/tests/expiry.test.ts:20 - the test that will fail if the change is wrongYou can open those lines. If they are wrong, you stop. If they are right, the agent may edit. The verification is the point, not a slogan.
\nMaguyva exposes 11 customer-facing MCP tools across search, symbols, dependency analysis, file retrieval, repository context, and deterministic utility workflows. Four retrieval modes (semantic, structural, graph/dependency, and text) are fused into ranked results; symbol lookup is a separate MCP tool (find_symbol). Grounded answers come back with file paths and line numbers so you can grade them against the tree in front of you.
The docs describe the shortest path: start free, index a repo you already know, connect the client, then ask one question you can verify.
\nYou do not need a new workflow religion. You need one extra step before the first write.
\nIf step 2 returns nothing useful, the agent does not get to improvise a path. It searches again, or you point it. That single gate is what produces fewer hallucinated edits. The model is the same model. The map is what changed.
\nInstruction files still matter. Keep them. Use them for conventions, review rules, and what not to touch. Do not ask them to be the index. A CLAUDE.md that lists three important directories will be stale the week after a package split. A queryable map updates when the repo updates.
A related failure is the near-miss file: the agent opens auth.ts when the behavior lives in auth-client.ts, or patches a generated file instead of the source, or edits the copy in packages/legacy because the name matched. Citations do not make those mistakes impossible. They make them visible before the diff lands.
Be clear-eyed about what you’re getting. A grounded map won’t make every edit correct — your agent can still write a bad patch in exactly the right file. If your codebase leans on dynamic dispatch, reflection, or monkey-patching, some symbol lookups will come back thinner than you’d like, because that’s what runtime indirection does to any static index. And if you’re hoping for a percentage — “hallucinated paths down by X%” — you won’t find one here, because nobody can honestly measure that number for your repo but you.
\nWhat you can expect is narrower and more useful: the agent stops opening its edits with a guessed path. That first step gets grounded in a real map, and that is where fewer hallucinated edits comes from. Everything after the citation — reading the diff, judging the patch — is still your job, the same as it ever was.
\nThe test costs you almost nothing: index one repo you already know and ask one question you can verify. Start with a path you have been burned by. If the citations are wrong, you’ll see it immediately. If they are right, your agent’s next edit has a better place to land.
\n// it doesn't know the file. it knows how to find it.
\n\nBenchmark numbers in this post reflect the RTEB leaderboards at publication (June 2026). Leaderboards move; treat the rankings as a snapshot, not a permanent fact.
\n
Semantic search is only as good as the embeddings underneath it.
\nWhen an agent asks Maguyva “where do we handle retries,” it is not grepping for the word “retry.” It is asking for the meaning — the backoff loop, the circuit breaker, the thing that wraps a flaky call. That question gets answered by a vector model that turns code into a point in space and finds the neighbors. Pick a better model and every semantic query in the product gets quietly sharper.
\nSo we changed ours. As of June 2026, Maguyva’s code embeddings run on voyage-4-large, replacing voyage-code-3.
We did not make this call on vibes. The public Retrieval Embedding Benchmark (RTEB) ranks embedding models on real retrieval tasks, and on its Code leaderboard voyage-4-large sits at #1 overall (90.86) — ahead of gemini-embedding-2-preview (90.26) and, notably, ahead of the model we were already using, voyage-code-3 (89.73, #3).
That is a small absolute gap. But it is a gap in the right direction, on a public benchmark, on the exact task we care about: retrieving code by meaning.
\nHere is the part most “we upgraded our model” posts leave out.
\nMaguyva does not store full-precision vectors. We store binary-quantized embeddings: each 2048-dimensional vector collapses to a 2048-bit signature — 256 bytes per vector. Those signatures are searched with Hamming distance, indexed and partitioned per tenant.
\nThat is a deliberate trade. Binary quantization gives up some retrieval precision in exchange for dramatically smaller storage and fast, cheap distance math with no separate vector database to operate. For a product that indexes whole repositories per workspace, that economics matters more than squeezing out the last fraction of a benchmark point.
\nvoyage-4-large fits this design without forcing a migration of the storage layer: it produces 2048-dimensional output, same as voyage-code-3, so our bit(2048) columns and Hamming search path did not change. The model got better; the schema stayed put.
Maguyva is a code-intelligence tool. But we’re also customer zero, and we point it at something else: the markdown that lives in our repos alongside the code. Architecture decision records, runbooks, contracts, finance and policy docs — all of it version-controlled in Git, all of it behind the same MCP server, a semantic index over the documents, not just the source.
\nThat is exactly why voyage-4-large’s breadth matters. On the same RTEB family of leaderboards it is #1 on finance, #1 on healthcare, and #1 on overall text retrieval — ahead of Google’s Gemini Embedding, Cohere’s Embed v4, and OpenAI’s text-embedding-3-large. (Voyage is a co-creator of RTEB, so we read it as a strong public signal rather than a perfectly neutral referee — but it is benchmarked head-to-head against every major commercial model, on private hold-out sets.) The same index that finds the right function for an agent finds the right clause in a contract or the right line in a policy — and on those domains, voyage-4-large isn’t a compromise, it’s the leader.
\nThere’s a cheaper way to do search, and a lot of it is free. Lexical search — BM25 and its kin — matches keywords, runs locally, and costs nothing. Open-source embedding models like BGE, Nomic, and embeddinggemma give genuinely decent semantic retrieval, and you can self-host them for the price of a GPU. Maguyva uses the free side too: every query fuses text, AST, graph, and semantic search. What we don’t cheap out on is the semantic layer.
\nWe pay per token for premium embeddings — voyage-4-large — instead of self-hosting a free model, for two reasons. First, keyword search alone can’t answer “where do we handle retries” when the code says backoff and circuit breaker and never says the word “retry” — meaning is the whole point of the embedding, and on the domains we serve the open models trail the premium ones: a couple of points behind on general text, and further behind in niches like code, contracts, and finance. Second, in our experience retrieval quality shapes the final answer more than the model on the other end does — a strong agent handed the wrong context still answers wrong, and it never sees the document it was never given.
So premium embeddings are a per-token bill that scales with every repo and document we index — and we pay it on purpose. For the outcome our users get, the right function or the right clause, we think that trade is worth it.
\nVoyage’s own documentation still labels voyage-code-3 as the code-optimized model. So why move?
Because we read the public benchmark, not just the vendor’s model table, and the benchmark put voyage-4-large on top for code retrieval. This was a forward-looking call: take the newer, generally stronger model and validate it against a public leaderboard on the tasks that matter. We’re comfortable making that bet because the evidence is broad — voyage-4-large doesn’t just win on code, it leads on finance, healthcare, and overall retrieval too.
Every tool we expose — semantic search, task-context gathering, grounded Q&A — bottoms out in retrieval. When the retriever improves, the agent on the other end gets better evidence, makes fewer wrong turns, and grounds its answers in the right code — or the right clause, or the right policy. A sharper embedding model is not a flashy feature. It is the floor under everything else, and we just raised it. You won’t notice. That’s the point.
\n", "date_published": "2026-06-09T00:00:00.000Z", "tags": [ "Embeddings", "Search", "Architecture" ] }, { "id": "https://maguyva.ai/blog/autonomous-quality-loops-language-grind", "url": "https://maguyva.ai/blog/autonomous-quality-loops-language-grind", "title": "Language Recursive Self-Improvement: Grinding Code Intelligence Across ~280 Languages", "summary": "We support code intelligence for ~280 languages. No human can hand-audit that. So we built a language recursive self-improvement loop — spot-check, LLM-as-judge, fix one thing, re-validate — and run it with a fleet of isolated agents until extraction is actually right, not just green.", "content_html": "\n\nNumbers in this post reflect the system at publication (May 2026). See our team page for current figures.
\n
Maguyva extracts symbols, references, and a dependency graph from source code in roughly 280 languages. Each language is a custom tree-sitter handler — queries, heuristics, edge cases — and every handler can be subtly wrong in its own way. A method call emitted as a read. A function attributed to the wrong enclosing scope. A relationship that simply isn’t there.
\nYou cannot hand-audit that. No team can read extraction output across 280 grammars and spot the bad edges. So the interesting question isn’t “is our extraction correct” — it’s “how do you find out that it’s wrong, at this breadth, without a human in every loop.” Our answer is language recursive self-improvement: a quality loop driven by language agents, an LLM acting as judge, and one rule we keep relearning: green is not the same as correct.
\nEvery language has a fixture suite, and a release gate scores it across five dimensions — accuracy, structural integrity, completeness, quality, and performance. A language goes GREEN only when, on its fixtures, precision ≥ 0.95, recall ≥ 0.99, and F1 ≥ 0.97, with at least 20 expected edges for statistical confidence. Below that it’s YELLOW or RED, and it doesn’t ship.
\nThat gate is necessary and not sufficient. Fixtures validate against fixtures we wrote. They encode the cases we already thought of. A handler can be flawless on its fixtures and still mangle a pattern that only shows up in real code — a macro idiom, a generic-bound method, a language feature nobody wrote a fixture for. GREEN means the fixtures pass. It does not mean a real repository extracts cleanly. So the loop has to leave the fixtures behind and look at the wild.
\nThe core loop runs one language at a time:
\n ┌──────────────────────────────────────────────────────────┐\n │ │\n ▼ │\n 1. corpus run ── clone real-world repos, extract relationships │\n │ │\n ▼ │\n 2. spot-check 100 edges (seed 42, then seed 123 to cross-check) │\n │ │\n ▼ │\n 3. LLM judge classifies every sampled edge: │\n CORRECT · FALSE_POSITIVE · TYPE_ERROR · │\n SCOPE_ERROR · METADATA_ERROR │\n │ │\n ▼ │\n 4. fix ONE thing — handler .py, .scm query, or config │\n │ │\n ▼ │\n 5. re-validate — F1 + re-classify + manifest diff (no regressions)│\n │ │\n better? ──no──► revert, try a different fix ────────────────────┤\n │ yes │\n ▼ │\n 6. promote the fix into fixtures (a permanent regression guard) ──┘A few things make this work rather than thrash.
\nThe judge is the agent, not an API call. When we say “LLM-as-judge,” we mean the language agent itself reads each sampled edge against the real source and classifies it with a fixed five-category rubric: is this edge correct, a false positive, the right relationship with the wrong type, attached to the wrong scope, or carrying wrong metadata? That rubric is the whole game — “23% error rate” is meaningless until you know whether those are real defects or the judge miscounting.
\nFix one thing, then prove it. Each iteration changes exactly one editable asset, then re-runs against a fixed harness and keeps the change only if F1 improves and the re-classification looks better. If it doesn’t, it reverts. No batch of speculative edits, no “should be better.” A change earns its place or it’s gone. And when a fix sticks, it’s promoted into the fixture suite — so the bug it fixed can never silently come back. That promotion step is what makes the loop recursive rather than merely repetitive: every pass hardens the oracle the next pass validates against.
\nHere’s the trap, and we walked straight into it. The secondary corpus metrics — how often an extracted target has no resolvable symbol, how many symbols look “orphaned,” and so on — massively over-report problems. They are mostly paradigm artifacts, not bugs.
\nThe cleanest example: llvm once showed a 73% “source-without-symbol” rate and got branded catastrophic. We dug in. Real accuracy was 98.5%. The “missing symbols” were almost all legitimate external references — calls into the standard library, into frameworks, into code that lives outside the repo. The metric was measuring a property of the language, not a defect in the handler. Languages like Zig, COBOL, and Odin show 65–70% “orphan” rates and are entirely correct; COBOL had zero real errors.
If we had let those numbers drive the work, we’d have spent weeks “fixing” handlers that were already right and ignoring the languages with quiet, real bugs. The conclusion is blunt: the aggregate metrics are a rough triage signal at best. The real quality signal is the spot-check with edge classification — looking at actual edges in actual repositories and judging them one by one. Data over intuition, but only once you know which data is telling the truth.
\nOne language at a time would take forever across 280 of them, so the inner loop is wrapped in an outer one that runs many in parallel.
\n pick a wave of near-GREEN / high-error languages\n │\n ▼\n fan out 10–15 agents, each ISOLATED in its own git worktree,\n each grinding ONE language, committing to its own branch\n │\n ▼\n orchestrator integrates serially: file-scoped apply, then\n `manifest diff` — any cross-language regression blocks the batch\n │\n ▼\n gated push (reviewed and confirmed) ──► rotate to the next waveEach agent works in a throwaway worktree so they can’t step on each other. The orchestrator integrates their fixes one at a time, each behind a full-manifest regression check: a change that helps its own language but quietly breaks three others doesn’t land. Integration is gated and confirmed before anything is pushed — the regression gate decides what’s safe, a human still decides what ships. Then the pool rotates to the next set of languages and the whole thing runs again.
\nThe judge can be wrong, and wrongness has a direction: an agent running with too little context over-reports. In one batch, eight languages were flagged at 5–20% error; on inspection only one was a real per-language bug — the rest were judge mistakes from missing the language’s own semantics (one source line legitimately emitting several edges, parameter bindings modeled as assignments, reference-per-identifier languages). That’s why we sample with two seeds and cross-check, and why a disagreement between the judge and the fixtures is treated as the most interesting signal, not a settled verdict — sometimes the fixture is the thing that’s wrong.
\nWe’re also honest about the target. The goal is zero real errors, full stop — but “zero” is a direction we grind toward, language by language, not a box that’s checked. There is always another repo with another idiom.
\nEverything Maguyva does for an agent — finding a symbol, tracing a dependency, answering a question with cited code — rests on the extraction underneath being right. Across 280 languages, “right” can’t be asserted; it has to be continuously earned against real code. The loop is how we earn it: an autonomous spot-check-and-fix cycle that treats its own metrics with suspicion, proves every change, and turns each fix into a guard against the next regression. It’s not glamorous. It’s the work that lets us say “we support your language” and mean it. Green is easy. Correct is earned.
\n", "date_published": "2026-05-26T00:00:00.000Z", "tags": [ "Architecture", "Languages", "Agents" ] }, { "id": "https://maguyva.ai/blog/multi-modal-fusion-search", "url": "https://maguyva.ai/blog/multi-modal-fusion-search", "title": "Multi-Modal Fusion Search: Picking the Right Retriever For Every Query", "summary": "A query like 'where is parseConfig defined' wants a different search than 'how does auth work'. Maguyva classifies the intent, weights four retrieval modalities accordingly, and fuses the results with weighted Reciprocal Rank Fusion.", "content_html": "\n\nHistorical design note: this April 2026 article describes the routing design at that time, not the current default behavior. The September correction below addresses a measurement claim only. For current routing, presets, and explicit modality controls, see How It Works.
\n
A search query is not one thing.
\n“where is parseConfig defined” wants an exact symbol — one precise location, fast. “how does authentication work” wants meaning — the spread of related code that explains a concept. “what breaks if I change this function” wants the dependency graph. “find the string ECONNREFUSED” wants a literal match, nothing clever.
Grep is excellent for literal matches and useful for some reference hunts, but it is not a dependency graph and it does not understand meaning. Embeddings cover the semantic side, but they are the wrong tool for exact strings and impact analysis. Most code search tools pick one engine and make every query live with that choice. Maguyva doesn’t pick. It works out what kind of question you asked, then blends four retrievers in the proportion that question deserves.
\nUnder the hood there are four independent ways to find code:
\nEach is strong on a different class of question. The trick is deciding how much to trust each one for the query in front of you.
\nBefore any retrieval runs, a lightweight classifier sorts the query into one of six intents, with a confidence score. It’s deliberately cheap — ordered heuristics, first match wins — because it runs on the hot path and adds only a millisecond or two:
\ndef , class , func , import … → find_definition (confidence 0.95)\"string\" or an error token like traceback → exact_match (0.85–0.90)CamelCase or snake_case identifier → find_definition (0.60–0.80)Each intent carries a weight profile across the four modalities. These are the real numbers:
\n| Intent | \nsemantic | \ntext | \nstructural (AST) | \ngraph | \n
|---|---|---|---|---|
| find_definition | \n0.2 | \n0.1 | \n0.6 | \n0.1 | \n
| find_references | \n0.1 | \n0.2 | \n0.2 | \n0.5 | \n
| understand_code | \n0.5 | \n0.2 | \n0.2 | \n0.1 | \n
| find_similar | \n0.4 | \n0.3 | \n0.2 | \n0.1 | \n
| impact_analysis | \n0.1 | \n0.1 | \n0.1 | \n0.7 | \n
| exact_match | \n0.0 | \n0.9 | \n0.1 | \n0.0 | \n
So “where is parseConfig defined” leans hard on AST (0.6). “how does auth work” leans on semantic vectors (0.5). “what depends on this” is almost all graph (0.7). “find ECONNREFUSED” is almost all trigram (0.9), with the embedding model switched off entirely — because semantic similarity is exactly the wrong tool for an exact string.
When the classifier is confident — score ≥ 0.85 — and the query is a normal one, Maguyva skips fusion entirely and routes straight to the single dominant modality. “where is X defined” doesn’t need four retrievers; it needs the AST index, now. That direct path is reported back as fusion_strategy: \"direct\".
Everything ambiguous goes through fusion. The four (or three, on the default preset) modalities run in parallel, each returning its own ranked list, and we combine them.
\nFusing heterogeneous retrievers is harder than it sounds: a cosine similarity of 0.82 and a trigram score of 137 and a graph centrality of 0.004 are not on the same scale, so you cannot just add them. Reciprocal Rank Fusion sidesteps the problem by throwing away the raw scores and keeping only the rank each engine assigned. A result’s contribution from one modality is:
\ncontribution = weight × 1 / (k + rank + 1)where rank is its position in that modality’s list and k is a smoothing constant. Contributions are summed across modalities for any result that more than one engine found — agreement between retrievers naturally floats to the top. We use k = 40 on the default preset and 60 on thorough (quick runs semantic-only, so fusion never kicks in there). The original RRF work landed on k = 60 for general-purpose retrieval; we default slightly sharper, which gives top-ranked agreement between modalities a bit more weight — and we don’t recommend hand-tuning it.
On top of that, results carry a graph-importance boost. A hub — a function the whole codebase leans on — should outrank an obscure leaf even at the same textual relevance, so we multiply each contribution by:
\nboost = min(1 + 0.3 × ln(1 + centrality), 1.5)Centrality comes from the pipeline’s precomputed PageRank/degree metrics, and the boost is clamped at 1.5× so a popular function can’t completely bury a more relevant obscure one. Finally we demote results from vendor, build, and archive paths, and dedupe to the best chunk per file.
\nThe intent classifier is a stack of regexes, not a learned model. It handles common query shapes with heuristics, and an ambiguous query falls through to understand_code and a semantic-leaning blend. An earlier version of this post described a zero-result reduction from roughly 15% to under 5% as achieved. The December 2025 proposal actually listed an estimated baseline and a target; no supporting query set or measurement receipt is supplied. We withdraw that achieved-improvement claim; see the source evidence and correction. We haven’t replaced the classifier with a trained model because the cheap version is fast and good enough for its intended routing role, and because a wrong-but-confident classifier is worse than an honest fallback. The weights themselves are hand-chosen priors, not learned from click data we don’t collect.
An agent shouldn’t have to know whether to reach for grep or embeddings or the call graph — it should ask its question in plain terms and get the right answer. Multi-modal fusion is what lets find_symbol, semantic search, and dependency analysis sit behind one query surface: the system reads the shape of the question and quietly assembles the right retriever for it. The model that scores the embeddings matters, but so does knowing when not to use them. Picking the right tool for each query is its own kind of quality, and it’s one we’d rather own than push onto the caller.
// you bring the question. it brings the tools.
Agent systems fail in weird ways.
\nSometimes the model is the problem. Sometimes the tool is the problem. Sometimes your MCP server is fine, but the agent chose the wrong specialist, or spent half the session doing shell work you did not expect, or silently burned cost in a loop that looked productive from the outside.
\nIf you cannot see the difference, you are not really operating an agent system. You are guessing.
\nSo we built an observability stack for our own workflow: Claude Code, Codex, Claude hook events, Codex notify events, native OpenTelemetry, Grafana Alloy, and Grafana Cloud on the other side.
\nThe interesting part is not “we made a dashboard.” The interesting part is that we had to split telemetry into two different streams because no single feed gave us the whole picture.
\nModern coding agents already emit some telemetry. That helps, but it is not enough.
\nNative OTEL is good at answering questions like:
\nIt is much worse at answering questions like:
\nBash, a built-in file tool, or an MCP call?That second class of question lives closer to hooks than traces.
\nBut the inverse is also true: some of the most important performance questions live closer to traces than hooks.
\nIf you want to know where latency actually accumulated, which spans were slow, or whether the session burned time in model calls versus tool execution, you need trace data as well as semantic events.
\nWe run two telemetry paths side by side.
\nClaude Code\n native OTEL -> Alloy -> Grafana Cloud\n hooks -> send_event.py -> Grafana Cloud Loki\n\nCodex\n native OTEL -> Alloy -> Grafana Cloud\n notify hook -> codex_notify.py -> shared Loki schemaThat split is deliberate.
\nIt is also asymmetric. Claude Code gives us a much richer lifecycle hook surface. Codex gives us native OTEL plus a notify surface, so we normalize thinner turn-completion events into the same log schema instead of pretending both runtimes expose the same controls.
\nNative OTEL gives us the baseline stream: logs and traces from the runtime itself, plus metrics where the runtime actually emits them.
\nHook and notify events give us the semantic layer: things like PreToolUse, PostToolUse, PostToolUseFailure, UserPromptSubmit, SubagentStop, SkillActivated, and the classified metadata we actually care about when debugging agent behavior. Claude Code contributes the richer event stream here. Codex contributes a thinner but still useful normalized stream.
Our hook pipeline enriches events before they hit Loki.
\nInstead of just saying “a tool ran,” we classify the event into fields like:
\ntool_type: builtin, mcp, skill, agent, bashmcp_server: which MCP backend handled the callbash_cli: the shell command familysubagent_type: what kind of specialist got dispatchedagent_tool: whether the source was Claude Code or CodexThat means we can ask questions that matter operationally:
\n{service_name=\"claude-code-hooks\"} | agent_tool=\"codex-cli\"\n{service_name=\"claude-code-hooks\"} | tool_type=\"mcp\"\n{service_name=\"claude-code-hooks\"} | json | bash_cli=\"git\"Those are not vanity fields. They are the difference between “the agent felt slow” and “the agent spent the last ten minutes in shell-heavy git operations with a high tool failure rate.”
\nOne implementation detail that looks stranger than it is: the shared Loki stream still uses service_name=\"claude-code-hooks\" as the label even when the event came from Codex. The real split between runtimes happens on agent_tool.
Grafana Alloy is not just a forwarder in this setup. It is the policy boundary.
\nWe point the native OTEL stream from Claude Code and Codex at a local Alloy proxy on localhost:4318, then let Alloy clean up the payload before forwarding it to Grafana Cloud.
That matters because raw agent telemetry is full of high-cardinality fields that are useful for analysis but terrible as indexed labels:
\nsession_idprompt_idIf you index everything, you get a label explosion and a bad day.
\nSo Alloy does three things for us:
\nThe important idea is simple: observe more, index less.
\nThe hook stream is already shaped for Loki.
\nBy the time send_event.py pushes an event, we have already decided which fields deserve label treatment and which belong in the structured JSON body. That stream goes straight to Grafana Cloud’s OTLP gateway instead of taking another pass through Alloy.
So the system has a clear division of labor:
\nThat keeps the architecture simpler than trying to force everything through one path.
\nThe screenshot below is from one of the observability dashboards behind our agent workflow. It is not a benchmark, and the numbers are just a point-in-time slice. The point is the shape of the data: activity feed, tool calls, failures, prompts, and breakdowns by agent, built-in tools, MCP usage, shell commands, and skills.
\nThe useful part is that this dashboard lives on the same Grafana stack as the rest of the agent telemetry. We can filter by source agent and tool family and look across runtimes without inventing a different observability story for each system.
\nLogs tell us what category of work happened. Traces tell us how the work unfolded over time.
\nThat distinction matters in agent systems because “slow” is too blunt to be useful.
\nA trace can tell us whether the pain came from:
\nIn practice we use the hook stream and Tempo traces together.
\nThe combination is what turns observability from a dashboard into an explanation.
\nCodex is part of the same stack, but it is not identical to Claude Code.
\nFor Codex we wire two pieces:
\ncodex_notify.py, which maps turn completions into the same Loki schema we use for hook eventsThat gives us a unified filter like agent_tool=\"codex-cli\" inside the same log stream.
The honest caveat: Codex’s notify payload is currently thinner than Claude Code’s hook payload because it is not the same kind of integration surface. In our setup today, Codex turn completions can be normalized into the shared schema, but rich tool-by-tool extraction is still better in the native OTEL stream than in the notify bridge.
\nThat is not a reason to avoid the post. It is the point of the post. Real observability systems are assembled from imperfect signals.
\nThe bigger shift is that Grafana is not only a place humans visit in a browser.
\nIn this repo we also expose Grafana through MCP. That means an agent can query Loki, Prometheus, and Tempo directly instead of waiting for a human to manually inspect the dashboards first.
\nThat turns observability into an active input to the workflow.
\nAn agent can ask:
\nOnce you have that, you are very close to a self-improvement loop.
\nThis is the part we find most interesting.
\nOnce the observability stack is queryable from the agent layer, telemetry stops being a passive reporting surface and becomes a control signal.
\nThe loop looks like this:
\nThat is how you move from “interesting dashboard” to “measurable improvement system.”
\nThe goal is not to maximize one tool category. It is to land on the right mix of CLI, built-in tools, MCP calls, and skills for the work actually being done.
\nOnce both runtimes land in the same Grafana stack, we can answer operational questions much faster:
\nThis is especially useful in multi-agent workflows, where “the agent was busy” tells you almost nothing.
\nIf one specialist keeps getting dispatched and producing high failure rates, that is a routing or prompt-shaping problem.
\nIf one MCP server dominates all calls, that may be good architecture or a sign that everything else is dead weight.
\nIf tool failures spike while cost stays high, you have an operational problem, not a quality problem.
\nIf shell work keeps failing in predictable, avoidable ways where a higher-level tool should exist, that is a product signal.
\nIf one skill activates constantly but does not improve outcomes, that is a prompt or routing signal.
\nThe deeper lesson here is that agent observability needs both runtime telemetry and workflow telemetry.
\nRuntime telemetry tells you what the system did.
\nWorkflow telemetry tells you what the agent thought it was doing.
\nWe need both.
\nIf you only keep traces and counters, you miss the semantic layer. If you only keep hook events, you miss latency, spans, and the broader runtime picture.
\nAnd if you keep both but never feed them back into the agent layer, you have monitoring, not adaptation.
\nThe combination is what makes the system explainable enough to operate and tunable enough to improve.
\nThere are still rough edges.
\nThat last point is intentional. We would rather show the real instrument panel than pretend agent systems are magically self-explanatory.
\nMaguyva is about giving agents better code intelligence. But once agents are actually doing useful work, a new requirement appears immediately: you need to see how they are behaving.
\nSearch quality, routing quality, tool selection, and context efficiency all become observable problems.
\nThat is why we think this is worth writing about. The future agent stack is not just prompts and tools. It is prompts, tools, and the instrumentation layer that tells you whether the whole thing is working.
\nIf you are building serious agent workflows, observability is not optional infrastructure. It is part of the product.
\n", "date_published": "2026-03-24T00:00:00.000Z", "tags": [ "Observability", "Grafana", "OpenTelemetry", "Architecture" ] }, { "id": "https://maguyva.ai/blog/mining-workflow-closing-the-loop", "url": "https://maguyva.ai/blog/mining-workflow-closing-the-loop", "title": "Mining the Loop: How Changes Become Institutional Memory", "summary": "Git commits become structured changelog entries and architectural decision records, then feed back into AI agents as queryable institutional memory.", "content_html": "\n\nNumbers in this post reflect the system at publication (February 2026). See our team page for current figures.
\n
Every engineering team faces the same challenge: changes happen constantly, but the why behind those changes disappears. Six months later, someone asks “why did we adopt DuckDB for pipeline stages?” and the answer lives only in the head of whoever made that call—if they’re still around.
\nWe built a mining workflow that closes this loop. Changes flow through git commits, get processed by our mining pipeline, become structured changelog entries and architectural decision records, and then feed back into our AI agents through CLI queries. The result: institutional memory that both humans and AI can access.
\nConsider a typical scenario. A developer commits:
\nfeat(canonical): add DuckDB runtime for pipeline stagesThis commit represents a significant architectural choice. The team evaluated options, considered trade-offs, and landed on DuckDB for specific reasons. But all that context lives in:
\nThree months later, a new team member asks: “Should I use DuckDB or SQLite for this new stage?” Without institutional memory, they either reinvent the wheel or make inconsistent choices.
\nOur mining workflow transforms git history into queryable knowledge:
\nGit Commits\n │\n ▼\n┌─────────────────────┐\n│ mine sync │ ← Build index from git history\n└─────────────────────┘\n │\n ▼\n┌─────────────────────┐\n│ mine candidates │ ← Surface commits for review\n└─────────────────────┘\n │\n ▼\n┌─────────────────────┐\n│ Classification │ ← Human or LLM assessment\n│ (changelog or ADR) │\n└─────────────────────┘\n │\n ├──────────────────────┐\n ▼ ▼\n┌─────────────┐ ┌───────────────┐\n│ Changelog │ │ Decisions │\n│ Ledger │ │ Registry │\n│ (JSONL) │ │ (YAML files) │\n└─────────────┘ └───────────────┘\n │ │\n ▼ ▼\n┌─────────────┐ ┌───────────────┐\n│ CHANGELOG.md│ │ orkestra CLI │\n│ per package │ │ queries │\n└─────────────┘ └───────────────┘\n │ │\n └──────────────────────┘\n │\n ▼\n ┌───────────────┐\n │ AI Agents │\n │ (via CLI) │\n └───────────────┘The key insight: both changelogs and architectural decisions flow from the same git history, processed through a unified pipeline. This ensures nothing falls through the cracks.
\nuv run orkestra mine syncThis command scans git history and builds an index of all commits. It extracts structured signals from each commit:
\nfeat, fix, chore, docs)uv run orkestra mine statusHere’s what our current status looks like:
\nMining Status\n=============\n\nDecisions\n---------\n Coverage: 100.0%\n Processed: 15637 (of 15637)\n Extracted: 476\n Skipped: 15161\n\nChangelog\n---------\n Coverage: 100.0%\n Processed: 15637 (of 15637)\n Released: 6799\n Skipped: 883815,637 commits processed. 476 became architectural decisions. 6,799 became changelog entries. Every commit classified.
\nuv run orkestra mine candidates --limit 50 --fullThis surfaces commits that haven’t been processed yet, with full context for classification:
\n{\n \"sha\": \"90571786d99166c0039ca2e80e4d9cd96184bd85\",\n \"date\": \"2026-01-26\",\n \"subject\": \"feat(canonical): add DuckDB runtime for pipeline stages\",\n \"signals\": {\n \"commit_type\": \"feat\",\n \"scope\": \"canonical\",\n \"breaking\": false,\n \"is_releasable_type\": true,\n \"domains_affected\": [\"pipeline\", \"data-architecture\"]\n },\n \"body\": \"Establishes DuckDB as canonical in-process analytical database...\",\n \"files_changed\": [\"packages/canonical/pipelines/stages/duckdb_runtime.py\", \"...\"],\n \"stats\": {\"files\": 8, \"insertions\": 450, \"deletions\": 120}\n}The signals help guide classification: is_releasable_type: true suggests this should appear in the changelog. The large insertion count and infrastructure files suggest it might also be an architectural decision.
Two paths diverge here: changelog entries and architectural decisions.
\nFor changelog entries:
\nuv run orkestra mine classify abc123 --changelog addedThis records that commit abc123 should appear in the changelog under the “Added” category.
For architectural decisions:
\nFirst, get a real decision ID:
\nuv run orkestra registry decisions new --domain pipeline --dry-run\n# Returns: DEC-PL-143Then classify with the decision ID:
\nuv run orkestra mine classify abc123 --decision DEC-PL-143This links the commit to a decision record that will be created or updated.
\nFor batch processing (what we actually do):
\n# Generate classifications file with LLM assistance\nuv run orkestra mine commit --input classifications.jsonlThe JSONL format supports both domains in one pass:
\n{\"sha\":\"abc123\",\"domain\":\"changelog\",\"action\":\"release\",\"category\":\"added\",\"summary\":\"Add DuckDB runtime for pipeline stages\"}\n{\"sha\":\"abc123\",\"domain\":\"decisions\",\"action\":\"extract\",\"decision_id\":\"DEC-PL-142\"}\n{\"sha\":\"def456\",\"domain\":\"changelog\",\"action\":\"skip\",\"reason\":\"Chore: dependency update\"}uv run orkestra registry changelog render --package <pkg>This generates per-package CHANGELOG.md files from the ledger. The changelogs are derived artifacts—delete them and they regenerate perfectly from the source ledger.
Extracted decisions become YAML files with rich metadata:
\nid: DEC-PL-142\ntitle: Adopt DuckDB as Canonical Processing Runtime for Pipeline Stages\ndomain: pipeline\nstatus: active\ncreated: '2026-01-26'\nsummary: |\n Establishes DuckDB as the canonical in-process analytical database for pipeline\n stage transformations. Provides a shared runtime module that resolves settings\n from pipeline defaults with stage-level overrides.\n\ncontext: |\n Pipeline stages performing data transformations each independently configured\n DuckDB connections. This led to inconsistent settings, duplicated configuration\n code, and no way to tune DuckDB globally for a pipeline run.\n\nrationale:\n - DuckDB provides efficient in-process OLAP with zero configuration deployment\n - Centralized runtime module eliminates duplicated DuckDB setup across stages\n - Hierarchical settings enable global tuning with stage-level overrides\n - Memory limits and thread counts can be adjusted per-pipeline\n\nimpact:\n positive:\n - Consistent DuckDB configuration across all pipeline stages\n - Single point of control for memory/thread tuning\n - Reduced code duplication in conversion and export stages\n negative:\n - Adds dependency on shared runtime module\n - Stages must adopt new configuration pattern\n\nsource_commits:\n - sha: 90571786d99166c0039ca2e80e4d9cd96184bd85\n message: 'feat(canonical): add DuckDB runtime for pipeline stages'\n date: '2026-01-26'\n role: primary\n\nfiles:\n - packages/canonical/pipelines/stages/duckdb_runtime.py\n - packages/canonical/pipelines/runner.py\n - packages/canonical/pipelines/stages/convert_hdx_admin_boundaries_to_geoparquet.py\n\nrelated:\n - DEC-DA-014 # Data architecture decisions that influenced thisEvery decision links back to its source commits. Every decision specifies which files it affects. Relationships between decisions are explicit.
\nThis is where the loop closes. Agents can query decisions through the CLI:
\n# Search by topic\nuv run orkestra registry decisions search --query \"retry\"Returns decisions about retry logic, error handling, recovery patterns.
\n# Get full details on a specific decision\nuv run orkestra registry decisions info DEC-PL-142Returns the complete decision record with context, rationale, and impact.
\n# List recent decisions for context\nuv run orkestra registry decisions list --limit 15Shows what architectural choices were made recently.
\nOur orchestrator’s baseline instructions include:
\n**Essential CLI commands:**\n- `orkestra registry decisions search \"X\"` — Find architectural decisionsWhen an agent is asked to implement something related to DuckDB, it can first check:
\nuv run orkestra registry decisions search --query \"DuckDB\"And discover DEC-PL-142, learning:
\nThe agent doesn’t reinvent the wheel. It builds on established patterns.
\nNot every commit deserves a decision record. We use the Three Questions Test to filter:
\nIf a commit answers “yes” to at least one of these questions, it’s a candidate for decision extraction. Our typical rate: 1-4 decisions per 100 commits (about 1-4%).
\nFor changelog entries, the bar is lower: any user-facing change (features, fixes, improvements) gets recorded. Internal chores, documentation updates, and refactors typically get skipped. Our typical rate: 30-50 changelog entries per 100 commits.
\nThe mining system uses append-only JSONL ledgers for conflict-free multi-agent operation:
\npackages/orchestration/ai_assets/reference/changelog/\n├── commits_processed.jsonl # Classification ledger (both domains)\n├── release_notes.jsonl # Changelog entries\n└── commits_index.yaml # Derived index (gitignored)\n\npackages/orchestration/ai_assets/reference/decisions/\n├── registry.yaml # Decision index\n└── records/\n ├── DEC-AD-001.yaml\n ├── DEC-AD-002.yaml\n └── ...The JSONL format with merge=union in .gitattributes means multiple agents can classify commits simultaneously without merge conflicts. Each line is independent.
Before any mining session, we run validation:
\nuv run orkestra mine validate --quickThis checks:
\nAfter classification, we validate again before committing changes.
\nThe feedback loop we’ve built solves several problems:
\nFor new team members: Instead of asking “why did we do X?”, they can search the decisions registry. The context is preserved.
\nFor AI agents: They don’t operate in a vacuum. They can query institutional knowledge before making recommendations. When asked to add a new pipeline stage, they can discover the DuckDB pattern and follow it.
\nFor architectural consistency: Decisions are explicit and searchable. When someone proposes an approach that contradicts an existing decision, the system can surface the conflict.
\nFor changelog generation: Release notes aren’t a last-minute scramble. They’re a byproduct of continuous classification during development.
\nFor onboarding: New agents inherit the full context of the codebase. They don’t just see the code—they see the decisions that shaped it.
\nAs of today:
\nEvery commit since we started has been classified. The institutional memory is complete and queryable.
\nIf you want to implement something similar:
\nStart with conventional commits. The mining pipeline works best when commits have structured prefixes (feat:, fix:, chore:).
Define your domains. We use domains like pipeline, agent-design, observability, data-modeling. These organize decisions by area.
Build the classification habit. Mining works when teams regularly classify commits. Batch processing with LLM assistance helps scale.
\nMake decisions queryable. The value compounds when agents can search decisions via CLI. Structure your output for machine consumption.
\nClose the loop. Decisions should influence future work. Include decision references in agent instructions and code review checklists.
\nThe goal isn’t perfect documentation. It’s making the why behind changes accessible to both humans and AI, today and six months from now. When changes become institutional memory, teams build on established patterns instead of reinventing them.
\nThe mining workflow is part of our orchestration engine, specifically the context engine module in our orchestration package.
\n", "date_published": "2026-02-03T00:00:00.000Z", "tags": [ "Architecture", "Workflows" ] }, { "id": "https://maguyva.ai/blog/skill-mining-3500-and-counting", "url": "https://maguyva.ai/blog/skill-mining-3500-and-counting", "title": "Skill Mining: From 3,500 Candidates to 466 Capabilities", "summary": "We screened 3,500 skill candidates and adopted 466. A systematic mining and ingestion loop for building a coherent AI agent skill library at scale.", "content_html": "\n\nNumbers in this post reflect the system at publication (January 2026). See our team page for current figures.
\n
When we started building an agent orchestration system, we faced an interesting challenge: there are thousands of potential skills scattered across the AI ecosystem. GitHub repositories, vendor documentation, community projects, internal patterns - skills exist everywhere. But which ones matter? Which ones work? And how do you maintain a coherent skill library that agents can actually use?
\nOur answer: a systematic mining and ingestion loop.
\nJust over three months after Anthropic launched Agent Skills on October 16, 2025, here’s where we stood when this post was published on January 27, 2026:
\n| Metric | \nCount | \n
|---|---|
| Candidates identified | \n3,500+ | \n
| Skills adopted | \n466 | \n
| Vendor skills | \n373 | \n
| Internal skills | \n93 | \n
| Active vendors | \n25+ | \n
| Average tokens per skill | \n2,834 | \n
| Tools referenced | \n89 | \n
| Unique tags | \n635 | \n
We’ve reviewed over 3,500 skill candidates. We’ve adopted 466. That’s a 13% adoption rate - and that selectivity is by design.
\nNot all skills are created equal. We organize them into five knowledge layers (K0-K4), each representing a different scope of applicability:
\nSkills every agent should have. These represent “good thinker” capabilities that work anywhere.
\nfoundations/\n├── test-first-discipline # TDD: Red-Green-Refactor\n├── evidence-based-completion # Verify before claiming done\n├── systematic-debugging # Root cause methodology\n├── structured-planning # Break work into tasks\n└── context-budget-awareness # Manage token consumptionK0 skills are portable to any project, any domain, any stack. They encode universal cognitive patterns.
\n“Good engineer” or “good researcher” skills that apply across projects within a discipline.
\nidentities/\n├── research-workflows # Multi-source research\n├── web-extraction-playbook # Content extraction\n├── code-review # PR review patterns\n└── cli-interface-standards # CLI design patterns“Good database expert” or “good security engineer” skills portable within a field.
\ndomains/\n├── schema-migration-workflow # Safe migration patterns\n├── rpc-validation-checklist # RPC health checks\n├── auth-validation-checklist # JWT/OAuth patterns\n└── secrets-audit-checklist # Credential scanning“Good Supabase user” or “good Cloudflare developer” skills for specific technology stacks.
\nstacks/\n├── maguyva-quickstart # Our semantic search patterns\n├── cloudflare-deployment # Workers/Pages deployment\n└── mcp-tool-best-practices # MCP tool selectionSkills specific to our organization and workflows.
\nproject/\n├── agent-creation-workflow # How we build agents\n├── skill-authoring-workflow # How we write skills\n├── mining-session-workflow # This very process\n└── vendor-skill-evaluation # Evaluation rubricsSkills come from everywhere:
\nVendor Repositories: AWS, Anthropic, Cloudflare, Supabase, and community contributors publish skill collections. We track 25+ vendor roots.
\nCommunity Projects: GitHub is full of Claude Code templates, agent patterns, and workflow definitions.
\nInternal Patterns: As our team solves problems, patterns emerge. These get formalized into skills.
\nDocumentation Mining: Technical documentation often contains implicit skills - procedures, checklists, decision trees.
\nDiscovery is continuous. We use a skill backlog to track candidates before formal evaluation.
\nEvery candidate goes through the same rubric:
\nadoption_criteria:\n - fills_real_gap: true # We lack this capability\n - well_structured: true # Progressive disclosure\n - actively_maintained: true # Commits in last 6 months\n - portable: true # Not hyper-specific\n - tested: true # Evidence of usageAll five product criteria must pass. This is why 87% of candidates are rejected.
\nThen every candidate goes through a separate trust review. We do not treat an official vendor repository, a well-known community maintainer, and a random GitHub repo as equivalent sources of truth.
\ntrust_review:\n vendor_credibility:\n - ownership_verified # Official vendor, known maintainer, or internal source\n - maintenance_signal # Recent commits, issue response, release history\n - adoption_signal # Evidence of real use, stars alone are not enough\n - provenance_clear # We can trace where the skill came from\n prompt_injection_scan:\n - hidden_instruction_check # Buried \"ignore previous instructions\" patterns\n - exfiltration_check # Prompts that try to leak files, secrets, or context\n - authority_check # Claims of priority over system or developer rules\n script_audit:\n - inspect_scripts # Read shell/python/js helpers before adoption\n - network_and_exec_review # curl|bash, remote downloads, subprocess execution\n - file_and_secret_review # Env vars, credential access, broad file writes\n - destructive_action_check # rm, reset, overwrite, or unsafe automationTrusted vendors get a lighter provenance review, but not a free pass. Untrusted or unknown sources get a deeper manual audit, and we do not execute bundled scripts until they have been read, scoped, and classified as safe.
\nGap Analysis: Before adopting, we search our registry:
\nuv run orkestra skills search \"<capability>\"If we already have it, we don’t need it. If we have something close, we might merge rather than adopt.
\nDepth and Standards Scoring: We also score how fully a candidate uses the agent-skill model. A lone SKILL.md can still be useful, but deeper skills are more valuable when they separate instructions from references, scripts, and assets in the way agentskills.io encourages.
skill_depth:\n - level_1: SKILL.md only # Single instruction file\n - level_2: SKILL.md + strong description # Clear triggers and scope\n - level_3: adds references/ # Load docs only when needed\n - level_4: adds atomic scripts/ # Small, reviewable helpers\n - level_5: adds assets/examples/templates # Full progressive disclosure\ndepth_signals:\n - standards_adherence # Structure aligns with agentskills.io conventions\n - reference_quality # Curated references, not giant context dumps\n - script_atomicity # Focused helpers, not opaque monoliths\n - tool_boundary_clarity # Clear limits on what the skill can execute\n - community_signal # Stars/forks/users help, but only as a weak boostGitHub stars can elevate a credibility score a bit, but they never rescue a shallow or unsafe skill. A high-star repo with one vague SKILL.md and opaque scripts scores below a smaller repo with a precise description, curated references/, and atomic helpers that actually leverage the full skill capability.
Structural Analysis: We check skill quality:
\nwc -l vendor/<repo>/<skill>/SKILL.md # Size check\nls vendor/<repo>/<skill>/scripts/ # Supporting files\nls vendor/<repo>/<skill>/references/ # Bundled docsIf a candidate includes scripts, that review gets more stringent. A good skill is not just useful; it has to be legible, bounded, and safe to hand to an agent. That safety filter alone disqualifies a meaningful slice of otherwise interesting candidates.
\nWhen a skill passes evaluation, it enters the registry. But skills are never adopted unchanged. They’re modified to fit our system.
\nModifications on Adoption:
\nA typical skill YAML after ingestion:
\nmetadata:\n identifier: vendor-skill-evaluation\n name: vendor-skill-evaluation\n description: Systematic evaluation of vendor skills for adoption.\n type: workflow\n layer: K4\n semantic_folder: project\n source: core\n last_updated: '2026-01-17'\n\nfrontmatter:\n tags:\n - agents\n - meta\n - skill-adoption\n - vendor\n allowed_tools:\n - Bash\n - Read\n - Write\n - Edit\n - Grep\n - Glob\n - TaskSkills are assigned to scopes - categories that determine which agents load which skills:
\nscopes:\n database:\n primary_skills:\n - domains/schema-migration-workflow\n - domains/rpc-validation-checklist\n - vendor/supabase/supabase-database\n - vendor/supabase/supabase-auth\n\n research:\n primary_skills:\n - identities/research-workflows\n - identities/web-extraction-playbook\n - identities/dataset-discovery-quickstartAgents declare their scopes, and skills are automatically assigned:
\n# Agent definition\nscopes: [database, research]\n# Gets: all database skills + all research skills + universal skillsSkills don’t live as YAML in production. They’re rendered into SKILL.md files that Claude Code can load:
\nuv run orkestra syncThis command:
\n.claude/skills/The final output structure:
\n.claude/skills/\n├── foundations/ # K0: Universal\n├── identities/ # K1: Discipline\n├── domains/ # K2: Subject\n├── stacks/ # K3: Technology\n├── project/ # K4: Organization\n└── vendor/ # External skillsOne of our most powerful patterns is “adopted-but-not-loaded” skills. We call these dormant scopes.
\nConsider scientific computing skills from the k-dense-scientific repository. We’ve adopted 120+ skills covering bioinformatics, chemistry, quantum computing, and clinical informatics. But most of our agents don’t need molecular docking or gene expression analysis.
\nInstead of loading all 120 skills into every agent (bloating context windows), we:
\nbioinformatics)# In scopes.yaml - dormant scope\nbioinformatics:\n description: \"Bioinformatics and genomics\"\n primary_skills: [] # Empty - skills exist but aren't loaded\n\n# When an agent needs bioinformatics:\n# Agent YAML\nscopes: [research, bioinformatics] # Now loads bioinformatics skillsThis pattern lets us have 466 skills in the registry while typical agents load only 40-60 relevant ones.
\nSkills come in three cognitive patterns:
\nOrdered procedural steps: “1. Do X, 2. Then Y, 3. Finally Z”
\ntype: workflow\n# Examples: schema-migration-workflow, mining-session-workflowBehavioral guardrails: “Always X”, “Never Y”, “Prefer Z”
\ntype: discipline\n# Examples: test-first-discipline, evidence-based-completionVerification criteria: “Confirm X”, “Verify Y”, “Check Z”
\ntype: checklist\n# Examples: auth-validation-checklist, secrets-audit-checklistEvery skill must pass validation before it ships:
\nvalidation:\n file_exists: true # Skill file at declared path\n frontmatter_valid: true # Frontmatter parses correctly\n sections_complete: true # Expected sections present\n tools_registered: true # Declared tools exist in registryDescriptions must be 50-400 characters with trigger phrases (“Use when…”, “When you need…”) so Claude Code knows when to suggest them.
\nWe validate continuously:
\nuv run orkestra validate --show-warningsOur 373 vendor skills come from:
\n| Provider | \nSkills | \nDomain | \n
|---|---|---|
| AWS Agent | \n19 | \nCloud services | \n
| Anthropic | \n12 | \nDocument generation | \n
| Cloudflare | \n8 | \nEdge computing | \n
| Supabase | \n5 | \nDatabase | \n
| k-dense | \n100+ | \nScientific computing | \n
| silvainfm | \n4 | \nData science | \n
| Java Developer Kit | \n45+ | \nSpring/Java | \n
| Vercel | \n1 | \nBrowser automation | \n
Each vendor root is declared in metadata.yaml:
\nvendor_roots:\n - path: vendor/aws-agent-skills\n provider: aws\n - path: vendor/k-dense-scientific/scientific-skills\n provider: k-dense\n - path: vendor/supabase-skills\n provider: supabaseWhen orkestra sync runs, vendor skills are symlinked into .claude/skills/vendor/ with their provider namespace.
Selectivity pays off. It’s tempting to adopt everything that looks useful. But each skill costs tokens. With 2,834 average tokens per skill, bloat hurts fast. Our 13% adoption rate keeps agents lean.
\nStructure enables discovery. The K-tier system isn’t just organization - it’s about portability. K0 skills can be reused anywhere. K4 skills are intentionally project-specific. This clarity helps both humans and agents find what they need.
\nDormant scopes scale. You can adopt hundreds of skills without loading them all. Scopes let you build a comprehensive registry while keeping individual agent context windows manageable.
\nModification on adoption is essential. Raw vendor skills rarely fit your system. The ingestion process - adding metadata, assigning tiers, enriching tags - makes external skills work internally.
\nMining is continuous. The 3,500 number keeps growing. New vendor repos appear. Community patterns emerge. Internal workflows solidify. The loop never stops.
\nWe’re working on several improvements:
\nThe skill mining loop is infrastructure. It’s not glamorous. But it’s what makes 41 agents work coherently with 466 capabilities while staying within context limits.
\nThat’s the story of how 3,500 becomes 466. Not by ignoring 3,000 - by evaluating them systematically and adopting only what works.
\nWant to see the skill system in action? Check out uv run orkestra skills list to explore our current registry.
\n\nNumbers in this post reflect the system at publication (January 2026). See our team page for current figures.
\n
Agent systems are opaque by design. They make decisions, invoke tools, and coordinate work across dozens of specialists. But when something goes wrong—or when you simply want to understand what’s happening—where do you look?
\nThe answer is progressive disclosure: a layered interface that reveals exactly as much complexity as you need, exactly when you need it.
\nA modern agent orchestration system might have:
\nThis complexity is intentional. Agents need access to rich context—domain knowledge, code intelligence, database schemas—to make good decisions. But that same richness creates a visibility problem.
\nHow do you know which agent handles database migrations? What decisions shaped the search system’s ranking behavior? Which tools does the architecture advisor have access to?
\nWithout structured access, you’re left reading source code or hoping the documentation is current.
\nProgressive disclosure isn’t just a UI pattern. It’s an architectural principle: organize information in layers, each deeper than the last, so users can stop at the level that answers their question.
\nFor agent systems, this translates to CLI commands at increasing depths:
\n| Level | \nCommand | \nQuestion Answered | \n
|---|---|---|
| 1 | \norkestra system status | \nIs everything healthy? | \n
| 2 | \norkestra agents list | \nWhat agents exist? | \n
| 3 | \norkestra agents info <name> | \nWhat does this agent do? | \n
| 4 | \norkestra decisions search | \nWhy does it work this way? | \n
| 5 | \nMaguyva MCP tools | \nShow me the code. | \n
Each level answers a natural follow-up question. You rarely need to jump straight to level 5.
\nThe first question is always: is everything working?
\n$ orkestra system status{\n \"agents\": 40,\n \"skills_internal\": 466,\n \"skills_vendor\": 240,\n \"skills_total\": 706,\n \"commands\": 17\n}One command. Four numbers. Enough to know the system is configured and the registries are populated.
\nIf an agent count drops unexpectedly or skills fail to load, you see it here first. No log diving required.
\nOnce you know the system is healthy, the next question is: what’s available?
\n$ orkestra agents listThis returns structured data—agent names, descriptions, model preferences, domain coverage. The output is JSON by default, making it easy to pipe into jq for filtering:
$ orkestra agents list | jq '.agents[] | select(.model == \"opus\") | .name'Want agents that handle database work? The search command narrows it down:
\n$ orkestra agents search \"database\"This scans names, descriptions, and capabilities. You find the right specialist without reading 40 agent definitions.
\nFound an agent that looks relevant? The info command reveals everything:
$ orkestra agents info architecture-advisorThe output includes:
\nHere’s a sample of what you see:
\n{\n \"metadata\": {\n \"name\": \"architecture-advisor\",\n \"model\": \"opus\",\n \"description\": \"Strategic decision-making and architectural guidance...\"\n },\n \"domains\": [\n \"product\",\n \"development/architecture\",\n \"meta/strategy\"\n ],\n \"tools\": {\n \"mcp_tools\": [\n \"mcp__maguyva__intelligent_search\",\n \"mcp__maguyva__analyze_dependencies\",\n \"mcp__supabase__execute_sql\",\n ...\n ]\n }\n}This tells you exactly what the agent can do. No source code required.
\nAgents behave according to documented decisions. When you need to understand why something works a particular way, the decisions registry is the source of truth.
\n$ orkestra decisions search \"agent\"This returns matching architectural decisions:
\n{\n \"results\": [\n {\n \"id\": \"DEC-SR-049\",\n \"title\": \"AI-Agent-First Defaults with Graph Intelligence\",\n \"domain\": \"search\",\n \"status\": \"active\"\n }\n ]\n}Each decision has full provenance—when it was made, why, what trade-offs were considered, which commits implemented it:
\n$ orkestra decisions info DEC-SR-049{\n \"id\": \"DEC-SR-049\",\n \"title\": \"AI-Agent-First Defaults with Graph Intelligence\",\n \"summary\": \"Changes default values for search tools to AI-agent-optimal behavior...\",\n \"rationale\": [\n \"AI agents work better with pre-ranked, importance-weighted results\",\n \"Graph metrics already computed by pipeline - leverage them\",\n \"Community context helps agents understand feature scope in single query\"\n ],\n \"source_commits\": [\n {\n \"sha\": \"156a880d05eae295669ef7c194b039023f245511\",\n \"message\": \"feat(maguyva): enable boost_by_importance...\"\n }\n ]\n}This is architectural documentation that stays current because it’s mined from commits, not manually maintained.
\nWhen you need to see the actual implementation—not metadata about it—Maguyva’s MCP tools provide direct access.
\nFrom within an agent session:
\nmcp__maguyva__intelligent_search\n query: \"agent context loading\"This auto-routes across semantic, text, and AST search to find relevant code. For specific symbols:
\nmcp__maguyva__find_symbol\n symbol_name: \"load_agent_context\"For dependency analysis:
\nmcp__maguyva__analyze_dependencies\n target: \"packages/orchestration/core/agents.py\"These aren’t just grep replacements. They’re graph-aware, semantically indexed, and integrated with the same code intelligence that powers the agents themselves.
\nSometimes you don’t know which registry holds the answer. The unified search spans everything:
\n$ orkestra search \"database\" --summary{\n \"query\": \"database\",\n \"total\": 254,\n \"counts\": {\n \"agents\": 40,\n \"skills\": 59,\n \"decisions\": 476,\n \"truths\": 2,\n \"packages\": 1\n }\n}254 matches across five registries. The summary tells you where to drill down. Remove --summary for detailed results, or add --limit 5 to keep output manageable.
Progressive disclosure isn’t just about convenience. It changes how you interact with complex systems.
\nDebugging becomes tractable. When an agent makes an unexpected decision, you don’t grep through logs. You check which tools it has access to (agents info), what decisions shape its behavior (decisions search), and trace the implementation if needed (intelligent_search).
Onboarding accelerates. New team members don’t need to read the entire codebase. They start with system status, explore with agents list, and go deeper only when they hit something they don’t understand.
Documentation stays current. Because the CLI reads from the same registries that configure the agents, the output is always accurate. There’s no drift between what the docs say and what the system does.
\nWe could have built a web dashboard. We could have written extensive documentation. Instead, we built a CLI that reads from the source of truth.
\nThe CLI has advantages:
\njq, integrate with scriptsFor systems where correctness matters more than aesthetics, CLI wins.
\nIf you’re building agent systems, consider how users will inspect them:
\nEach layer answers a follow-up question. Build them in order of frequency—most users stop at layer 2 or 3. Only power users reach layer 5.
\nThe goal isn’t to expose everything. It’s to expose exactly what’s needed, exactly when it’s needed. That’s progressive disclosure applied to agent architecture.
\n", "date_published": "2026-01-20T00:00:00.000Z", "tags": [ "Architecture", "CLI", "Tooling" ] }, { "id": "https://maguyva.ai/blog/ground-truths-anchoring-ai-to-reality", "url": "https://maguyva.ai/blog/ground-truths-anchoring-ai-to-reality", "title": "Ground Truths: Anchoring AI Agents to Reality", "summary": "AI agents hallucinate confidently. Ground truths are versioned, scoped facts that anchor agent behavior to reality. Here is how we built and enforce them.", "content_html": "\n\nNumbers in this post reflect the system at publication (January 2026). See our team page for current figures.
\n
AI agents are remarkably capable. They can reason, synthesize, and generate. But they have a fundamental weakness: they make things up. Not maliciously, but confidently. An agent might invent API parameters that do not exist, reference configurations that were never defined, or apply patterns from its training data that contradict your actual architecture.
\nThe standard mitigation is “give the agent more context.” But context can be contradictory. Documentation drifts from implementation. Comments lie. Even code can mislead when read without understanding intent.
\nWe needed something more explicit. Something that could not be ignored or misinterpreted. Something that would anchor agents to verifiable reality.
\nWe call them Ground Truths.
\nA ground truth is an explicit, versioned statement of fact that agents must respect. It is not documentation. It is not a comment. It is a first-class entity in the system with:
\nGT-MAG-015 or GT-MAG-036)Here is an example from our Maguyva code intelligence platform:
\n- id: GT-MAG-015\n status: current\n scope: package\n statement: |\n Fuzzy symbol matching is opt-in via `find_similar=true`.\n Default behavior returns empty results for non-existent symbols;\n `exact_match=true` enforces strict matching and disables all fuzzy fallbacks.\n rationale: |\n Deterministic defaults prevent agents from receiving misleading results.\n Typos should fail explicitly rather than silently returning unrelated symbols.\n evidence:\n - \"packages/maguyva/server/src/maguyva/services/code_analysis_service.py\"\n - \"packages/maguyva/server/docs/quick_reference/parameters.md\"\n last_verified: \"2026-01-25\"\n tags:\n - product\n - ai_first\n - principleThis is not prose. It is a contract. When an agent encounters this ground truth, it knows:
\nfind_similar, exact_match) with defined behaviorsGround truths live in YAML registries under ai_assets/reference/ground_truths.yaml. Each package or domain can have its own registry. The structure is:
metadata:\n title: \"Maguyva Ground Truths\"\n summary: \"Foundational constraints and principles that guide Maguyva.\"\n last_updated: \"2026-01-26\"\n owner: \"maguyva\"\n render:\n include_statuses: [current, tentative]\n show_deprecated: true\n groups:\n - title: \"Product Principles\"\n tags: [product, principle, brand]\n - title: \"Architecture & Boundaries\"\n tags: [architecture, boundaries, cqrs]\n\nstatements:\n - id: GT-MAG-001\n status: current\n scope: package\n statement: \"Maguyva is read-only with respect to user repositories...\"\n ...The registry includes metadata about the collection itself, render configuration for documentation generation, and the statements themselves. Each statement follows a strict schema validated by Pydantic models:
\nclass GroundTruthStatement(BaseModel):\n id: str\n status: GTStatus # current, tentative, deprecated\n source: GTSource | None # claude-code, orkestra, discipline\n scope: GTScope # platform, package, domain\n statement: str\n rationale: str | None\n evidence: list[str]\n last_verified: str | None\n tags: list[str]\n agent_guidance: AgentGuidance | NoneGround truths are exposed through multiple channels:
\nThe orkestra sync command transforms YAML registries into readable markdown:
uv run orkestra syncThis generates GROUND_TRUTHS.md files that are included in agent context. The rendered output groups statements by status and category:
## Current\n### Product Principles\n- Maguyva is read-only with respect to user repositories... (GT-MAG-001)\n- Design tool responses for AI agents first... (GT-MAG-009)\n\n### Architecture & Boundaries\n- Pipeline and Maguyva boundaries are intentional... (GT-MAG-006)Agents with shell access can search ground truths programmatically:
\nuv run orkestra registry truths search \"embedding\"\nuv run orkestra registry truths search --tag security\nuv run orkestra registry truths list --status currentThe search function scores matches across multiple fields with weighted relevance:
\ndef truth_fields(gt: GroundTruthStatement) -> list[FieldSpec]:\n return [\n FieldSpec(name=\"id\", weight=6, values=[gt.id]),\n FieldSpec(name=\"statement\", weight=5, values=[gt.statement]),\n FieldSpec(name=\"rationale\", weight=4, values=[gt.rationale] if gt.rationale else []),\n FieldSpec(name=\"tags\", weight=3, values=gt.tags or []),\n FieldSpec(name=\"evidence\", weight=2, values=gt.evidence or []),\n ]When agents are rendered from YAML definitions, their context can reference ground truth registries:
\ncontext_composition:\n domain_knowledge:\n - packages/maguyva/ai_assets/reference/ground_truths.yamlThis ensures relevant ground truths are loaded before the agent begins work.
\nLooking across our registries, ground truths cluster into several patterns:
\nConstraints on what the product is and is not:
\n\n\n“Maguyva is read-only with respect to user repositories; the only non-rebuildable asset is the paid embeddings cache.” (GT-MAG-001)
\n
Where responsibilities live and why:
\n\n\n“Pipeline and Maguyva boundaries are intentional: pipeline is reusable, Maguyva holds code-specific logic, and CQRS separates stage writes from server reads.” (GT-MAG-006)
\n
Explicit mandates that keep tool contracts deterministic instead of inferred:
\n\n\n“Fuzzy symbol matching is opt-in via
\nfind_similar=true. Default behavior returns empty results for non-existent symbols;exact_match=trueenforces strict matching and disables all fuzzy fallbacks.” (GT-MAG-015)
Standards that must be maintained:
\n\n\n“Changes to shared infrastructure (post_filters.py, relationship extractors, shared handlers) MUST be validated against ALL supported languages via full manifest generation before commit. A single-language validation is insufficient for shared code.” (GT-MAG-036)
\n
Implementation requirements:
\n\n\n“Use
\nasyncio.to_thread()for CPU-bound work in async contexts; the deprecatedloop.run_in_executor()pattern should not be used in new code.” (GT-MAG-018)
Ground truths are not static. They evolve through a defined lifecycle:
\nA proposed truth under evaluation. The statement is recorded but may change:
\n- id: GT-MAG-044\n status: tentative\n statement: |\n get_file with include_metadata=false may still return metadata in the\n response because middleware may re-inject it for AI agent disambiguation.A verified truth that agents must respect. Evidence has been validated:
\n- id: GT-MAG-017\n status: current\n last_verified: \"2026-01-26\"\n evidence:\n - \"packages/maguyva/server/src/maguyva/services/supabase.py\"A truth that no longer applies. Kept for historical reference with a pointer to what replaced it:
\n- id: GT-MAG-099\n status: deprecated\n superseded_by: GT-MAG-015\n notes: \"Replaced when we moved to explicit matching behavior\"Documentation serves a different purpose. It explains. It teaches. It can be vague, can use qualifiers like “generally” or “typically.”
\nGround truths cannot be vague. They are assertions. They either apply or they do not.
\nConsider the difference:
\nDocumentation: “The API generally returns empty results when a symbol is not found, though fuzzy matching may be enabled in some configurations.”
\nGround Truth: “Default behavior returns empty results for non-existent symbols; exact_match=true enforces strict matching and disables all fuzzy fallbacks.”
The first is helpful for humans learning the system. The second is actionable for agents making decisions.
\nSome ground truths include explicit agent guidance:
\n- id: GT-MAG-022\n statement: |\n Accuracy fixes must happen at extraction time via production code,\n never via validator filters.\n agent_guidance:\n do:\n - \"Fix extraction bugs in YAML config, handlers, or tree-sitter queries\"\n - \"Add test cases at the layer where the fix lives\"\n avoid:\n - \"Adding validator filters to mask production bugs\"\n - \"Creating test-only workarounds for extraction issues\"This removes ambiguity. An agent reading this knows not just what is true, but what actions that truth implies.
\nGround truths require maintenance. We track:
\nA ground truth with stale verification dates or broken evidence links is a signal to investigate. Either the truth is still valid and needs re-verification, or reality has changed and the truth needs updating.
\n- id: GT-MAG-014\n statement: |\n Maguyva queries are search patterns, not executable code.\n SQL injection prevention is handled by PostgREST parameterization;\n application-layer SQL keyword blocking must never be added.\n rationale: |\n Blocking SQL keywords breaks legitimate code search. Users search FOR\n code containing patterns like 'DROP TABLE', they don't execute them.This ground truth prevents a class of misguided “security improvements” that would break the product.
\n- id: GT-MAG-022\n statement: |\n Accuracy fixes must happen at extraction time via production code\n (YAML config, handlers, queries), never via validator filters.\n rationale: |\n Validator filters only run during tests. They can hide extractor bugs\n while production responses remain wrong.This came from painful experience. Agents would patch failing language packs by adding validator-only filters that made the test harness look greener, while the live Maguyva extractor still emitted the wrong edges. The rule forces fixes back into the real path: YAML config, queries, or handlers.
\n- id: GT-MAG-023\n statement: |\n Language engine uses three-tier filtering: external_method_patterns\n (builtins/stdlib), allowlists (legitimate idioms), and expected_call_targets\n (validation-time deduplication). Each tier serves a distinct purpose.\n rationale: |\n Conflating filter purposes leads to either over-filtering (missing real\n relationships) or under-filtering (noise).This prevents agents from adding filters in the wrong place, a common mistake that caused accuracy regressions.
\nGround truths are one layer of a broader context system:
\nAn agent working in the system has access to all four. Ground truths provide the factual anchor, while decisions explain history, patterns guide implementation, and anti-patterns warn of pitfalls.
\nSince introducing ground truths, we have observed:
\nThe investment in maintaining ground truths pays off in reduced debugging and clearer system boundaries.
\nTo add a ground truth to your system:
\nground_truths.yaml in your package’s ai_assets/reference/ directoryuv run orkestra sync to generate documentationStart with the facts that cause the most confusion or the constraints that get violated most often. Those are your highest-value ground truths.
\nAI agents will hallucinate. That is their nature. But we can create environments where hallucination is constrained, where certain facts are non-negotiable, where agents can check their assumptions against verified reality.
\nGround truths are not a complete solution. They require maintenance. They can become stale. They add overhead to the development process.
\nBut they provide something valuable: a shared vocabulary of facts that both humans and agents can trust. In a world where agents increasingly participate in software development, that shared foundation becomes essential.
\nThe alternative is endless cycles of agents making confident mistakes and humans correcting them. Ground truths break that cycle by making the corrections explicit and durable.
\nYour agents deserve to know what is true. Tell them.
\n", "date_published": "2026-01-13T00:00:00.000Z", "tags": [ "Architecture", "Grounding" ] }, { "id": "https://maguyva.ai/blog/orkestra-agent-orchestration", "url": "https://maguyva.ai/blog/orkestra-agent-orchestration", "title": "Orkestra: Orchestrating AI Agents at Scale", "summary": "One orchestrator routes work to specialist AI agents, each with distinct skills and memory. How Orkestra coordinates 46 agents and 466 skills in production.", "content_html": "\n\nNumbers in this post reflect the system at publication (January 2026). See our team page for current figures.
\n
When we started building with Claude Code, we ran into a problem that every team using AI coding assistants eventually faces: a single agent cannot do everything well.
\nYou can prompt an agent to be a database specialist. Or a security auditor. Or a frontend engineer. But the moment you ask it to be all three at once, quality suffers. Context gets diluted. Instructions conflict. The agent becomes a generalist that is mediocre at everything.
\nSo we built Orkestra.
\nOrkestra is an agent orchestration system for Claude Code and similar AI coding tools. It coordinates multiple specialized agents, each with distinct expertise, under a single orchestrator that routes work to the right specialist.
\nThink of it as a staffing agency for AI agents. The orchestrator receives a task, identifies which specialist should handle it, and delegates with the right context. When the work is done, results flow back to the orchestrator for synthesis.
\nThe numbers tell the story:
\n| Component | \nCount | \n
|---|---|
| Specialist agents | \n46 | \n
| Reusable skills | \n466 | \n
| Identity archetypes | \n27 | \n
| Mindsets | \n11 | \n
| Communication styles | \n10 | \n
| Knowledge domains | \n21 | \n
The core insight behind Orkestra is that agent behavior emerges from three composable primitives:
\nIdentity defines what the agent is. An architect designs system structures. A debugger traces failures to root causes. A guardian enforces compliance and security boundaries. We have 27 identity archetypes that can be mixed.
\nMindset defines how the agent thinks. An analytical mindset grounds assertions in evidence and quantifies uncertainty. A skeptical mindset questions assumptions and seeks disconfirming evidence. An exploratory mindset embraces ambiguity and tries multiple approaches.
\nStyle defines how the agent communicates. A technical style includes exact values and references specific files. A concise style cuts fluff and leads with the answer. A diplomatic style balances honesty with tact.
\nAn agent combines these primitives:
\n# architecture-advisor.yaml\nidentity:\n - knowledge-architect\n - architect\n - strategist\nmindset: analytical\nstyle: conciseThis composition creates an agent that designs systems (architect), connects knowledge across domains (knowledge-architect), sets strategic direction (strategist), thinks in evidence and data (analytical), and communicates without fluff (concise).
\nThe power is in combinatorial explosion. 27 identities times 11 mindsets times 10 styles yields nearly 3,000 possible agent personalities. But you only define the combinations that matter for your work.
\nSkills are the knowledge and workflows that agents can invoke. They follow a tiered system based on scope:
\n| Tier | \nName | \nScope | \nExample | \n
|---|---|---|---|
| K0 | \nFoundations | \nUniversal methodology | \nTest-first discipline, evidence-based completion | \n
| K1 | \nIdentities | \nRole-based workflows | \nCLI interface standards, performance playbook | \n
| K2 | \nDomains | \nDomain-specific knowledge | \nDatabase migration patterns, authentication validation | \n
| K3 | \nStacks | \nTechnology-specific | \nCloudflare deployment, Supabase operations | \n
| K4 | \nProject | \nThis codebase only | \nProject-specific workflows and conventions | \n
Skills are lazy-loaded. An agent sees skill names and descriptions at startup, but full skill content only loads when triggered. This keeps context lean while making hundreds of skills discoverable.
\nEach skill includes:
\nThe 466 skills in our registry cover everything from git worktree isolation to web research workflows to deployment health validation.
\nSingle-agent architectures hit walls quickly:
\nContext dilution. A 200k token context window sounds large until you load database schemas, API docs, test fixtures, and domain knowledge. Specialists can work with targeted context.
\nInstruction conflicts. Telling an agent to “be thorough but fast” and “verify everything but don’t over-engineer” creates tension. Specialists resolve these by having clear scope.
\nExpertise depth. A generalist agent knows a little about everything. A specialist agent, composed with the right identity and skills, knows its domain deeply.
\nOrkestra implements flat orchestration: one orchestrator coordinates multiple specialists. Specialists cannot spawn sub-specialists. This prevents complexity explosion while enabling parallel work.
\nThe orchestrator has access to 2.2 million tokens of effective capacity: its own 200k window plus 10 concurrent subagents with 200k each. Work that would exhaust a single agent runs comfortably across the fleet.
\nAgent definitions live in YAML. Claude Code reads Markdown. Orkestra bridges this gap with a deterministic rendering pipeline:
\nYAML Registries → Jinja Templates → .claude/agents/*.mdOperators edit YAML source. Run orkestra sync. Rendered Markdown appears in .claude/agents/. Claude Code picks up the changes.
This separation serves different audiences:
\nThe pipeline composes identities, mindsets, styles, and skills into a single coherent prompt. An architect-analytical-concise agent gets a very different system prompt than a debugger-skeptical-technical agent, even if they share some underlying skills.
\nEvery knowledge domain follows a consistent structure:
\ndomain-name/\n decisions.md # Key choices, rationale, consequences\n patterns.md # Step-by-step guidance and examples\n anti-patterns.md # Failure modes and remediation\n evolution.md # Dated log of changesThis structure serves agent context loading. An agent working on authentication loads authentication/patterns.md for guidance and authentication/anti-patterns.md to avoid known pitfalls. The files are sized for efficient context loading: focused enough to be useful, comprehensive enough to be authoritative.
We maintain 21 top-level domains including analytics, authentication, data science, infrastructure, machine learning, performance, security, and more. Each domain can have sub-domains for finer granularity.
\nAll agents share a base layer of values that define how they operate:
\nSimplicity first. Use the simplest solution that works. Add complexity only when justified.
\nFix root causes. Never patch around failures. If a pipeline fails, debug the pipeline. If a test fails, fix the code or the test.
\nEvidence-based. Label claims as “verified” (with benchmarks) or “estimated” (with assumptions). Pattern detected does not equal problem confirmed.
\nContext economics. MCP tools cost 0.1% of context. File reads cost 2% each. Apply domain expertise before exploring code.
\nThese values propagate to every specialist through the rendering pipeline. An agent cannot bypass them by composition.
\nOrkestra ships with a CLI for managing the agent ecosystem:
\n# Discovery\norkestra agents search \"database\"\norkestra agents info database-architect\n\n# Validation\norkestra validate --show-warnings\n\n# Rendering\norkestra sync --dry-run\norkestra sync\n\n# Skills\norkestra skills list\norkestra skills info schema-migration-workflow\n\n# Decisions\norkestra decisions search \"authentication\"The CLI is the source of truth for what agents exist, what skills they have, and whether the system is healthy. It runs validation before sync to catch problems early.
\nWe built Orkestra to solve our own problem: coordinating AI agents at scale for a complex codebase. The patterns we discovered are not specific to our domain.
\nThe character composition system (identity + mindset + style) applies to any team defining agent personalities.
\nThe skill tier system (K0-K4) provides a mental model for organizing reusable capabilities by scope.
\nThe rendering pipeline pattern (YAML source + templates + generated artifacts) separates concerns between tooling and model consumption.
\nThe flat orchestration model (one coordinator, many specialists) avoids complexity while enabling parallelism.
\nWhether Orkestra becomes open source depends on whether these patterns have value for others building with Claude Code. If you are hitting the walls we described, the architecture might help.
\nBuilding Orkestra taught us that orchestration is not about making agents smarter. It is about making them more focused.
\nA single agent with perfect instructions still runs out of context. A single agent with all the skills still gets confused about which to apply. A single agent trying to be everything produces mediocre results everywhere.
\nForty specialists, each excellent in their domain, coordinated by an orchestrator that knows when to delegate: that is how we ship.
\nThe numbers matter less than the architecture. You might need five agents or fifty. The principle remains: composition over capability, specialization over generalization, coordination over individual heroics.
\nOrkestra powers the agent ecosystem behind Maguyva, our code intelligence platform. Want to learn more? Reach out to the team.
\n", "date_published": "2026-01-06T00:00:00.000Z", "tags": [ "Architecture", "Open Source" ] } ] }