Working with Large Codebases
Code-context tooling for agentic development in 2026 — the four paradigms, the current SOTA, our chosen stack.
Executive summary
AI agents that touch large codebases fail in a predictable way: they burn context. The default
primitives an agent reaches for — grep, find, cat — return
everything, always. On a real codebase a single ripgrep call for a common identifier can return hundreds
of kilobytes. The context window fills before reasoning starts.
The 2026 answer is a small set of specialised tools that give the agent ranked, bounded, question-shaped retrieval instead of a firehose. This paper is a snapshot of that landscape, our chosen stack, and the reasoning behind each pick.
The framing that will hold up across future revisions is that code-context tools fall into four different paradigms — semantic, symbol, structural, and hosted docs — and no single tool spans all four. A production agent runs a small portfolio, and picks by question class.
Ozzy Dev ships four MCP tools in its curated catalog: ChunkHound for semantic recall, Serena for symbol navigation and refactoring, codesearch for structural / multi-repo work, and Context7 for public-library docs. All are open-source, local-first, and MCP-native.
Current status (2026-07): ChunkHound is re-enabled read-only in the shipped catalog (kilo.json ships enabled:true with --read-only; registry default flipped 2026-07-19) — upstream v5.2.0 shipped
auto-compaction plus mcp --read-only (no write path); indexing/watch stay
operator-run CLI until chunkhound#365. Semantic queries still route through codesearch hybrid (BM25 + dense + RRF) in the interim. Symbol tooling runs via Serena as a
supervised streamable-HTTP LaunchAgent on 127.0.0.1:24283; codesearch runs its
own serve LaunchAgent on 127.0.0.1:39725 (EMFILE fix applied). The
native search MCP ozzydev-search (ADR-007) is enabled and
production-dogfooded as a router across these backends. Full case-study evidence — including
the DuckDB index-growth incidents that triggered the pause — lives on Memory Tooling — Open Decisions & Measurement Log (decisions D1–D18).
Cutting-edge research
Two findings shape the current state of the art, and every serious tool in the space now uses both.
- cAST — Chunk AST for RAG on code — arXiv:2506.15655 (CMU, 2026). +4.3 recall on RepoEval and +2.67 pass@1 on SWE-bench vs. naive fixed-window chunking.
- Voyage Code-3 — Voyage AI blog (2024). +13.8% over OpenAI text-embedding-3-large on 32 code retrieval datasets.
- RAG for codebase — reference architecture — LLMversus (2026). Voyage Code-3 + tree-sitter AST chunking + Qdrant with metadata filters + Claude Sonnet 4 for cited answers. Symbol-level chunking is the biggest quality lever, not the LLM.
- Local code-graph MCP comparison — Andrey Kumanyaev, zzet.org (2026-05-28). The four-paradigm framing that this paper adopts: graph, embeddings, LSP, hosted docs.
- Codebase-Memory: Tree-Sitter knowledge graphs via MCP — arXiv:2603.27277 (2026). Persistent Tree-Sitter knowledge graph for LLM code exploration through MCP.
- Codebase RAG model comparison — Modal blog (2025). Head-to-head benchmarks of six code-embedding models on code retrieval.
The larger point is that symbol-level chunking is the biggest quality lever, not the LLM. Every serious 2026 tool uses AST-aware chunking; anything still doing fixed-window chunking will lose on any published code-retrieval benchmark.
Best-in-class embedding models
- Voyage Code-3 (API) — Current SOTA on code retrieval benchmarks: +13.8% over OpenAI text-embedding-3-large on 32 code datasets. Supports Matryoshka + int8/binary quantization (50–75% storage savings).
- SFR-Embedding-Code-400M (CodeXEmbed) (Local) — Salesforce, Apache-2.0. Strongest open-source local model at reasonable size. 12 languages, 5 retrieval categories.
- Nomic Embed Code (Local) — First code embedder with a Mixture-of-Experts architecture. 8k context window — excellent for long code files.
- Jina Code v2 (Local) — Multilingual, code-similarity-focused. Used by Microsoft monodex.
Ozzy Dev defaults to local Ollama with a code-optimised embedding so the clone-and-install experience needs no API key. Voyage Code-3 is exposed as an opt-in in the console Secrets panel for teams that want SOTA quality.
Voices to follow
This field moves weekly. These are the signals we track to catch shifts before they land in production tools.
- Anthropic Engineering — MCP protocol updates, Claude Code changelog, agent posts.
- Voyage AI Blog — Voyage Code-3, Rerank-2, quantization, code-embedding benchmarks.
- Nomic AI Blog — Nomic Embed Code, MoE embedders, open-source models.
- Simon Willison — The most consistent, high-signal daily coverage of AI tooling. Curates code-search + MCP developments continuously.
- Latent Space — swyx + Alessio. Podcast + newsletter. Frequent interviews with the teams behind Cursor, Codex, Cognition, etc.
- Andrey Kumanyaev — zzet.org — Author of the four-paradigm code-graph MCP comparison that anchored this paper.
- Salesforce AI Research — CodeXEmbed, code-retrieval research, open-source model releases.
- Modal Blog — Rigorous benchmarks on embeddings + inference for AI dev tools.
- Karpathy on X — North-star intuitions on agents + tokens + context windows.
The four paradigms
Every code-context tool falls into one of four categories. The category determines the class of question the tool answers well.
Semantic / vector — “Find code that does X.”
Vectors over code chunks, ranked by cosine similarity or fused with BM25.
Our pick: ChunkHound — RE-ENABLED READ-ONLY per D4 (v5.2.0 auto-compaction + mcp --read-only, no write path; registry default flipped 2026-07-19). Indexing/watch stay operator-run CLI until chunkhound#365; the ozzydev-search router semantic expert remains claude-context + codesearch hybrid pending the bakeoff..
Symbol / LSP — “Who calls this? What is the type? Rename this across the repo.”
Language-server queries: workspace symbols, references, call hierarchy, rename.
Our pick: Serena.
Structural / graph — “What is the blast radius of this change? Which files depend on this one?”
Import + call graph from AST parsing, with PageRank or shortest-path queries on top.
Our pick: codesearch (multi-repo hybrid).
Hosted docs — “What is the current API for library Y?”
A hosted index of public library documentation, injected into the prompt.
Our pick: Context7.
Our stack — the four we install
Ozzy Dev's curated MCP catalog seeds these four entries. The agent picks by question class; each tool has one clear job.
ChunkHound — semantic
The strongest semantic recall in the current group. Uses the cAST algorithm (arXiv:2506.15655) for AST-aware chunking. Runs fully local via Ollama; optional VoyageAI or OpenAI. MCP-native.
github.com/chunkhound/chunkhound
Serena — symbol / LSP
The only tool in this space that can refactor. Compiler-grade symbol accuracy across 40+ languages via LSP. Largest mindshare in the code-graph MCP category (~25k stars).
codesearch — structural / hybrid
Multi-repo serve mode with cross-repo RRF ranking — a natural fit for the nine Nexartis SDK monorepos. Hybrid vector + BM25 + symbol navigation in one Rust binary. CPU-only, hundreds of MB, fully offline.
github.com/flupkede/codesearch
Context7 — hosted docs
The only category-appropriate tool for “current API for React / SvelteKit / Cloudflare Workers.” Not indexing our repo — indexing the world.
A benchmark harness in the console runs a fixture query set drawn from the nine Nexartis SDK monorepos against every catalog entry side-by-side, scoring precision@1/5/10, cold and warm latency, tokens returned, freshness, and multi-repo capability. Every catalog choice is defensible from that score-card. The canonical recording schema lives at Experimental Framework.
Field notes — first production profiling
Profiled on a real workload: onboarding three new repos and running a cross-repo integration trace on a 16 GB Apple M5. What survives contact with production:
- Query-time cost is a solved problem; index-pipeline health is not. codesearch
answered hybrid queries in 140–190 ms (warm rerank 0.9 s, +relevance on prose
queries), and a freshly registered repo was queryable in under two minutes. Meanwhile
ChunkHound had been silently degraded for days: a single chunk containing a literal
<|endoftext|>string (in its own vendored source, ironically) failed an entire 146k-chunk embedding batch in a tight retry loop — leaving 3% semantic coverage (4,975 embeddings over 151,087 chunks) while regex search kept working. No error ever reached the agent. - The doctor needs a coverage ratio, not a liveness bit. "Running" was true the
whole time.
embeddings ÷ chunksas a first-class health metric would have caught the failure on day one. - Local-first has a hardware budget. A ~6 GB-resident Qwen3 embedder on a 16 GB machine makes backfills take hours and times out under concurrent load with a second indexer. The highest-leverage knob is model size (Qwen3-0.6B/4B raise batch sizes 2–4×); the second is never running two heavy indexers at once.
- Registries are daemons' property. Hand-editing codesearch's
repos.jsonwhile serve runs lost edits to a concurrent rewrite; the HTTP API (POST/DELETE /repos) is safe and also handles indexing and cleanup. - LSP tools fail silent, not loud. Serena resolved symbols in a 15-minute-old clone with no pre-index, but returned an empty reference list for a symbol with two call sites because the repo wasn't in its workspace folders. Repo onboarding is a checklist (clone → ignore file → registry POST → Serena workspace folder → verification query per system), not a habit.
Resolution — the opinionated stack
The field notes above forced a decision: local embedding models are not a viable production default on typical developer hardware. On a mid-range 16 GB developer laptop, a ~6 GB-resident Qwen3 embedder pushed the system to 21% free memory with pageouts, hour-scale backfills, and timeout cascades whenever a second indexer ran. The fix was not tuning; it was removing the local model from the default path.
The shipped configuration:
- ChunkHound → Voyage
voyage-code-3+rerank-2.5. 1024-dim float embeddings (the model's Matryoshka sweet spot — 92.28% retrieval quality vs 92.12% at 2048 per Voyage's published evals), 32K-token context per chunk. Final numbers on the reference machine: 9,199 files, 183,956 chunks, 100.0% embedding coverage, single-digit dollars once then pennies incrementally; memory pressure returned to 41% free and Ollama unloaded entirely. Ollama remains a selectable profile on the/memory/chunkhoundtab for machines that can hold a model — it is no longer installed bymcp/install.sh. Status 2026-07: ChunkHound is re-enabled read-only by default inkilo.json(v5.2.0 auto-compaction +mcp --read-only; registry default flipped 2026-07-19); indexing/watch stay operator-run CLI until chunkhound#365 fix; the interim semantic layer is codesearch hybrid (BM25 + dense + RRF), with symbol queries routed to Serena and the ozzydev-search MCP (ADR-007) fronting the router. See D4. - Rate-limit tiers are a real throughput knob. Voyage Tier 1 (payment method) gives voyage-code-3 3M tokens/min — one backfill saturated it (2.99M/3M) and finished the 48k-chunk tail in 176 s once limits lifted. Purchasing $100 of usage credits permanently doubles limits (Tier 2); ChunkHound's batch + exponential-backoff client behaviour matches Voyage's own guidance verbatim, so 429s degrade gracefully instead of failing.
- Bulk indexing bloats DuckDB files ~100×; compaction is mandatory tooling. A write-heavy backfill grew
chunks.dbto 225 GB for 2.3 GB of actual data (interrupted large transactions never reclaim pages, and DuckDB files never shrink). A dependency-orderedINSERT INTO…SELECTcopy with HNSW index rebuild — 21 s total — recovered it to 2.3 GB with all 13 indexes and 100% coverage intact. Run indexers to completion; never kill one mid-transaction. Subsequent repeat incidents at multi-repo scale (277 GB and 412 GB) are recorded on Memory Tooling — Open Decisions; the mandatorydatabase.max_disk_usage_mbcap and absolutedatabase.pathship in the currentmcp/install.shscaffold. - Keys are product surface, not ops surface. The Secrets panel (
/system→ API Keys, ADR-006) provides guided provider links with instructions that disappear once configured, live verification against the provider before acceptance, AES-256-GCM encryption at rest in the console's D1-portable SQLite database (master key in the macOS Keychain), write-only after save, and automatic application into.chunkhound.json/kilo.json. Setup time for both keys, measured: under two minutes. - codesearch stays fully local — MiniLM (minilm-l6-q, 384-dim) + BM25 hybrid at 140–190 ms needs no paid upgrade; the reranker is local too. Context7 moved from anonymous to keyed (higher rate limits) through the same panel.
- Serena backend is machine-specific: a JetBrains-backed deployment (ADR-005)
is selected via
.serena/project.local.yml; the plugin must be reachable (IDE open) or symbol tooling degrades — the doctor reports exactly that state.
The general lesson: a local-first default is only honest if the reference machine can run it with headroom. For embeddings on 16 GB hardware, a $5 API backfill beats a free model that silently starves the rest of the stack. Local-first still wins where CPU-sized models suffice (codesearch's 384-dim minilm-l6-q) — the paradigm split is by model footprint, not ideology.
Cross-repo strategy — the per-tool answer
Onboarding a workspace to 46 repos forced a decision earlier revisions ducked: how does each
tool actually index across a multi-repo tree? The answer is deliberately different per tool,
because the strengths differ per tool. This is codified in the workspace guide and mcp/install.sh.
- ChunkHound — one workspace-root index. Semantic recall benefits from a single
embedding space; v5 made root-indexed sub-tree lookups safe, so one
.chunkhound/dbpoints at the whole workspace and the semantic layer finds prior art across repos naturally. - codesearch — per-repo databases with group RRF fusion. BM25 statistics are
per-corpus by definition; blurring 46 repos into one lexical index would destroy the signal.
Per-repo
.codesearch.dbfiles, grouped (project→nexartis→all), fused at query time by Reciprocal Rank Fusion in the serve daemon. The SembleX architecture arrives at the same answer independently, which is the strongest external validation available. - Serena — per-repo LSP projects, activated on demand. A single root project
collapsed all TS references (upstream oraios/serena#1586); one project per repo restores them.
The harness runs with
--context ide-assistantand no--project; agentsactivate_projectthe repo being edited. The fix ships inmcp/install.sh; the root project is retained only for workspace-wide Python and docs. - Gap acknowledged. "Who uses this SDK export across all 46 repos?" has no
exact tool yet — see memory tooling decisions D13, which adopts
both SCIP-in-CI (for exact cross-repo symbol lookup) and a CoreGraph/stack-graphs pilot, with
a routing rubric. Day-to-day, approximate with
chunkhoundregex orcodesearch group="nexartis"and say so in findings.
Disk caps at multi-repo scale — a hard rule
Uncapped DuckDB stores have twice grown into runaway indexes at multi-repo scale (277 GB
and 412 GB incidents); both are known upstream failure modes tracked as chunkhound PRs #339
(compaction) and #340 (phased indexing). The shipped mitigations — absolute database.path, database.max_disk_usage_mb: 20000, fragmentation_threshold_pct: 30, and max_concurrent_batches: 3 — live
in the mcp/install.sh scaffold; the case-study record, with root causes and the
mitigate-vs-migrate decision, is on Memory Tooling — Open Decisions (D4, incident
series). The durable rule: disk caps are mandatory at multi-repo scale, and any new workspace-level
embedding store must ship with one before the first index run.
2026 benchmark consensus — similarity-only vector RAG is not enough
The published evidence from the last twelve months is unusually consistent. Similarity-only vector RAG underperforms at repository scale; the systems that win fuse lexical + dense + structural signals with an agentic loop on top of retrieval. This is the same shape as our stack — with the honest gap that our structural signal is per-repo (import/call graphs inside codesearch), not cross-repo.
- CodeRAG-Bench (NAACL'25) — first standardised code-RAG benchmark; hybrid consistently beats pure vector.
- AIRCoder (ACL'26) — RRF-fused import-graph + structural signals; ~10× faster than an LLM-rerank loop at the same accuracy.
- Hydra (arXiv 2602.11671) — dependency-aware retrieval for repository-scale QA.
- RANGER (arXiv 2509.25257) — repository knowledge graph + MCTS localisation.
- RAGSearch (arXiv 2604.09666) — agentic search over strong hybrid retrieval closes most of the gap that motivates full GraphRAG builds.
- CrossCodeEval — cross-file completion benchmark; retrieval quality dominates the gap.
- CoREB — reranker evaluation showing all rerankers are task-asymmetric; there is no universally best reranker across code-to-code, code-to-text, and NL-to-code.
- Cursor — secure codebase indexing — content-hash-keyed embedding cache + Merkle diff + simhash cross-worktree reuse; the freshness architecture we would fork-and-improve at our scale first — upstream PR only when world-class and operator-approved (D4 directive on upstream etiquette).
- Sourcegraph — SCIP cross-repo navigation — the enterprise-proven answer to exact cross-repo symbol lookup; adopted alongside the CoreGraph pilot per D13.
- Aider repomap — tree-sitter + PageRank ~1k-token map per repo; the pattern we intend to adopt as a drop-in MCP (queued as A1 in the decision log).
Embeddings — hold voyage-code-3, bench the challengers
voyage-code-3 + rerank-2.5 retained. Voyage has not shipped a voyage-code-4 — their code line stops at 3, and no head-to-head shows a dominator
on this workload class. Challengers worth benching, on a 100-query gold set drawn from real
agent traces: Qodo-Embed-1, jina-code-embeddings-1.5b, and SFR-Embedding-Code. CoREB makes it explicit that reranker choice is
task-asymmetric, so the same harness A/Bs rerank-2.5 against Qwen3-Reranker-4B on the
code-to-code slice. The benchmark harness is the vehicle; premature switches are not.
voyage-context-4 (2026-06-29) — evaluation pending. Voyage shipped voyage-context-4, a chunk-context-aware embedding model that ingests surrounding
chunks at embedding time ("stop worrying about chunking"). If it holds up on this workload it
could obsolete part of the cAST chunking tuning. Tracked as D6; adopt on evidence, not on brand refresh.
The wider landscape
The tools we did not adopt, and why. This section stays useful for a while — most of these are serious projects, and any of them might overtake our current pick.
- zilliztech/claude-context — semantic (cloud). The reference cloud implementation — Milvus + Voyage/OpenAI. Cited “~40% token reduction under equivalent retrieval quality.” Our benchmark target; not adopted because it requires Zilliz Cloud + an API key.
- claude-context-local — semantic (local). 100% local alternative to the above, ChromaDB + ONNX. Solid, but ChunkHound is a better-executed implementation of the same idea.
- codanna — structural (read-only). Fast Rust read-only graph server with FastEmbed for optional semantic search. Clean and focused; smaller mindshare than the others.
- Gortex — structural (hybrid + refactor). Graph + hybrid + blast-radius + multi-repo + refactor in one Go binary. Very powerful; heavier bootstrap. Worth revisiting when multi-repo refactoring becomes a first-class need.
- codixing — structural (hybrid). 71 MCP tools, field-weighted BM25, PageRank on symbol graph. Tested on the Linux kernel (63k files, 30M+ lines) with a 1.57s cold-start search. Larger footprint than codesearch.
- Microsoft monodex — semantic (monorepo). MSFT’s tool for large TypeScript monorepos. Jina Code v2 embeddings + fielded BM25. CLI-first — MCP server on the backlog. Worth watching.
- lsp-intelligence — symbol / LSP. TypeScript-focused LSP MCP server with 29 tools. Excellent within TS/JS; Serena wins on language breadth.
- codebase-index — hybrid (SQLite). Python, SQLite FTS5 + tree-sitter + optional embeddings. Fully offline. Good on individual repos; single-repo focus.
- sourcebot — lexical (regex over many repos). Regex-based code search MCP powered by Google’s zoekt. Precise for exact names / error strings; no semantic recall yet (roadmapped).
Augment Context Engine — the strongest hosted implementation
The Augment Context Engine is the proprietary hosted counterpart to zilliztech/claude-context in the semantic paradigm — the strongest publicly-described code-retrieval architecture we have found. It gets its own section rather than a landscape bullet because the page charter is exactly “the four paradigms, the current SOTA,” and this is the current SOTA on the hosted side.
History — the founding inspiration, and its withdrawal
Augment's IDE extension is the founding inspiration for this platform. The operator used it daily as their primary code-context tool; then the vendor withdrew it. Two dates from Augment's own changelog and marketplace listing:
- 2026-03-31 — Next Edit and Code Completions sunset for Indie / Standard / Max / Legacy plans (Enterprise retained). The changelog rationale reads verbatim: “global usage of Next Edit and Completions decline as forward-leaning developers shift toward agent-centric workflows.”
- 2026-07-01 — the entire
augment.vscode-augmentextension sunset. The marketplace listing header reads verbatim: “Augment Code for Visual Studio Code Sunset notice — July 1, 2026. This extension is being sunset. After this date it will only be maintained for existing enterprise contracts. Everyone else: try Cosmos, our new AI coding platform.” Stated replacements: Auggie CLI (terminal agent, GA 2025-08-28), Cosmos (the web-based successor product), and the Context Engine MCP that any MCP-capable host can call.
The extension surface that went away — and that the CLI + MCP replacements do not give back inside the editor — is our requirements list: in-editor codebase Q&A and retrieval on
a real-time index, chat with persisted Memories as first-class UI, native
inline Code Completions trained on edit events (+45% of edits typed by the
model at rollout, per Augment's context-modeling post), multi-line cross-file Next Edit suggestions, Smart Apply of chat code, and multi-workspace
source-folder indexing — all without wiring MCP into a separate host. Independent commentary
(r/AugmentCodeAI, augment.vim#12) confirms the extension was the product for most
users; the CLI is a different surface.
A closed, server-side, credit-priced dependency can be withdrawn on the vendor's schedule. The capability we valued survived exactly as long as the vendor's product strategy did — and no longer. That is the concrete argument for a local-first stack behind generic seams: integrate protocols, not vendors. The seam principle itself lives on Harness Interoperability; the point here is that this page — the one that justifies our chosen memory stack — exists because the founding inspiration was taken away, and we decided to rebuild it in a way that could not be.
Techniques worth reproducing, ranked
From the sunset extension and its published architecture, the pieces worth reproducing on our
stack, ordered by leverage. Reclaim targets and performance numbers live on MoE Search Router §reclaim-targets; not
duplicated here.
- Context Lineage — commit-diff summaries embedded alongside code chunks — buys: answers "when and why did this land" from the same index; we have `git log -S` for literals and nothing semantic over history. The highest-value, most reproducible piece of the Augment stack for us. Cost to us: cheap-LLM (Gemini 2.0 Flash class) pass over `git log -p`, embed the summaries next to the file chunks they touch; hours of engineering, small ongoing token cost.
- Quantized ANN + full-embedding rerank, with a hot-set fallback — buys: ~40% latency and ~8× RAM at ≥99.9% parity with exact NN; graceful behaviour on just-embedded chunks that have not been quantized yet. Cost to us: binary quantization on the shortlist, full-precision rerank on top-K, exact-space fallback for the hot set — Qdrant/Zilliz already ship the primitives, so this is assembly work not research.
- Code-relationship-trained embeddings — buys: recall on relationship queries (call-site↔definition, doc↔code, cross-language same-feature) that generic embeddings miss by matching textual similarity. Cost to us: labeled pair mining plus a fine-tune budget; Voyage `voyage-code-3` narrows this gap materially off-the-shelf, so this is a moat play, not table stakes.
- Per-developer real-time index (branch-agnostic) — buys: seconds-latency incremental updates on save and correct results across branch switches without a reindex step. Cost to us: fs-watcher → local WAL → embedding worker keyed by working-copy state, not branch; the multi-tenant RAM-sharing story collapses to nothing on-device.
- Proof-of-possession — buys: zero-trust content boundary — the server only returns chunk text when the client can prove it already has the file bytes; the enabling primitive for any future shared index. Cost to us: trivial on-device where server == client (already implicit); the primitive matters when hosted mode arrives.
Architecture
- Real-time index on Google Cloud — PubSub, BigTable, AI Hypercomputer. Personal per-developer indices; branch switches reflected within seconds.
- Custom code-embedding models — trained on code and on relationship pairs (callsite↔definition, doc↔code, cross-language same-feature) because generic embeddings degrade at scale by matching on textual similarity. Not OpenAI or Pinecone off-the-shelf; self-hosted embedding search on GCP. Augment cites embedding-inversion attack literature (arXiv 2305.03010, arXiv 2004.00053) as their reason not to send code embeddings through third-party APIs.
- Proof-of-Possession — the client must send a cryptographic hash of the file bytes before the backend will return any embedding-derived content. This is what lets Augment hold overlapping tenant indices in shared RAM without ACL bugs leaking bytes across tenants. Why this matters to us: it is the enabling primitive for any shared / multi-tenant index, which is the direction ADR-011 / ADR-012 points.
- Quantized ANN with graceful fallback at 100M-LOC scale — memory 2 GB → 250 MB (8×), latency 2 s → <200 ms, ≥99.9% result parity, automatic fallback to full-embedding search when the quantized index is cold or the codebase is small.
- Context Lineage (2025-07-29) — commit diffs are summarized by a cheap model
(Gemini 2.0 Flash tier) into a few sentences — goal, touched functions, technical terms — and
those summaries are embedded alongside file chunks. Adds “when and why did this change” to
retrieval at file-chunk cost. Directly borrowable: we have
git log -S(literal) and nothing semantic over history. - Security / tenancy posture — the index is server-side by design. No self-host, no air-gap, no index export, no embedding export. SOC 2 Type II at all tiers.
Public API surface (as of 2026-07-27)
- Context Engine MCP — went live 2026-02-06. Local:
auggie --mcp [--mcp-auto-workspace]over stdio, indexes the working directory in real time,--wait-for-indexingavailable. Remote:https://api.augmentcode.com/mcp, GitHub App onboarding, indexes only the default branches of selected repos, updates automatically on push. - Context Engine SDK — TypeScript
@augmentcode/auggie-sdk, Pythonauggie-sdk. Marked Experimental — subject to breaking changes in Augment's own docs. SurfacesDirectContext/FileSystemContext.
The supported retrieval contract is async search(query, options?): Promise<string>. Augment's API reference
says verbatim “Formatted string containing the search results, ready for LLM consumption” and “The format includes file paths, line numbers, and code content”, with maxOutputLength default 20 000 / max 80 000 chars. There is no documented ranked chunks[] array and no per-item relevance score. searchAndAsk() returns an LLM answer. The Context Connectors CLI ctxc search --raw returns the pre-summarization text, still not JSON.
An undocumented endpoint agents/codebase-retrieval-raw does
return chunks[{text, path, charStart, charEnd, lineStart, lengthInLines, blobName, score,
origin}], but the CLI discards everything but the formatted string. Unsupported and liable to silent change; not an integration we would depend on.
Pricing and plan availability
- Pricing: roughly $0.03–$0.06 per query — LLM tokens at provider list price plus a 40% service fee. No separate SKU for the Context Engine.
- Legacy individual plan availability is undocumented and unverified; several adjacent Auggie features are server-side feature-flagged off for such plans.
Augment publishes no retrieval-only IR numbers. Their headline claim — that adding Context Engine to Claude Code / Cursor / Codex improved agent performance “70%+” (Cursor + Opus 4.5 +71%, Claude Code + Opus 4.5 +80%, Cursor + Composer-1 +30%) — comes from a downstream agent-quality benchmark: 300 Elasticsearch PRs × 3 prompts = 900 attempts, scored on five subjective dimensions (correctness, completeness, best practices, code reuse, unsolicited documentation). Vendor-run, no independent replication, and not nDCG / MRR / Recall over graded relevance judgments.
There is no published retrieval number to compare our stack against. Any head-to-head we run is original work.
The benchmark arm design lives on MoE Search Router; the adopt / reject decision lives on Memory Tooling — Open Decisions (D19). Cross-referenced, not duplicated.
Open questions
- Rerankers — Voyage Rerank-2 or Cohere Rerank 3 add ~150 ms and lift relevance ~30% on code Q&A. Worth adopting once we have baseline numbers to compare against.
- Multimodal code embeddings — Jina v4 supports text + code + diagrams. When it
matures, architecture-diagram-aware retrieval becomes real, and the
docs/PRODUCT_ARCHITECTURE.mdmermaid diagrams become queryable directly. - Framework-aware typed edges — route → handler → service → model traversal, on the codixing roadmap. For our stack (SvelteKit routes, Cubicle adapters, ABI Chat providers), this is exactly the graph shape we want.
- KYM as an MCP surface — Ozzy Dev already consumes KYM as an MCP tool for agent discovery. Could KYM also serve agent-authored code-context indices as a shared team resource? An open architectural question worth prototyping.
How we keep this paper current
This is a living document. When a new tool emerges, when we swap a catalog entry, or when the benchmark harness surfaces a result that changes our recommendation, we update this page in place and bump the version at the top.
Publication cadence for Nexartis thought-leadership derivatives (blog posts, conference talks, case studies) uses this page as the source of truth.
References
- arXiv:2506.15655 (CMU, 2026) — cAST — Chunk AST for RAG on code. +4.3 recall on RepoEval and +2.67 pass@1 on SWE-bench vs. naive fixed-window chunking.
- Voyage AI blog (2024) — Voyage Code-3. +13.8% over OpenAI text-embedding-3-large on 32 code retrieval datasets.
- LLMversus (2026) — RAG for codebase — reference architecture. Voyage Code-3 + tree-sitter AST chunking + Qdrant with metadata filters + Claude Sonnet 4 for cited answers. Symbol-level chunking is the biggest quality lever, not the LLM.
- Andrey Kumanyaev, zzet.org (2026-05-28) — Local code-graph MCP comparison. The four-paradigm framing that this paper adopts: graph, embeddings, LSP, hosted docs.
- arXiv:2603.27277 (2026) — Codebase-Memory: Tree-Sitter knowledge graphs via MCP. Persistent Tree-Sitter knowledge graph for LLM code exploration through MCP.
- Modal blog (2025) — Codebase RAG model comparison. Head-to-head benchmarks of six code-embedding models on code retrieval.
- Model Context Protocol — the substrate every tool in this paper speaks.
- Nomic Embed Code — model card.
- SFR-Embedding-Code-400M — Salesforce CodeXEmbed model card.
- Augment — Rethinking LLM Context: the Augment Context Engine — real-time GCP index, custom code embeddings, Proof-of-Possession, quantized ANN with fallback.
- Augment — Context Lineage (2025-07-29) — commit-diff summaries embedded alongside file chunks for semantic history retrieval.
- Augment docs — Context Engine MCP (local + remote) —
auggie --mcp,https://api.augmentcode.com/mcp, default-branch indexing. - Augment docs — Context Engine SDK (Experimental) —
@augmentcode/auggie-sdk,DirectContext/FileSystemContext,search()returns a formatted string; no rankedchunks[]. - arXiv 2305.03010 and arXiv 2004.00053 — embedding-inversion attack literature cited by Augment as the reason not to use third-party embedding APIs.
- Augment — VS Code extension sunset notice (July 1, 2026) — marketplace listing header, captured 2026-07-28. The founding-inspiration primary source.
- Augment changelog — Next Edit and Completions sunset (2026-03-31) — dated 2026-03-05; plan-tier scope and stated rationale.
- Augment docs — feature availability matrix — per-plan capability surface of the extension, captured 2026-07-28.
- Augment — Context Modeling (2025-08-06) — edit-event-aware completions model; +45% of edits typed by the model at rollout.