research · v0.10 · published — current stack reference; +Augment Context Engine landscape entry (2026-07-27); +history / reclaim-techniques subsection (2026-07-28)

Working with Large Codebases

Code-context tooling for agentic development in 2026 — the four paradigms, the current SOTA, our chosen stack.

published 2026-07-08 · updated 2026-07-28
authors: Nexartis
tags: agents · code-context · mcp · retrieval

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.

Bottom line

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.

  1. cAST — Chunk AST for RAG on codearXiv:2506.15655 (CMU, 2026). +4.3 recall on RepoEval and +2.67 pass@1 on SWE-bench vs. naive fixed-window chunking.
  2. Voyage Code-3Voyage AI blog (2024). +13.8% over OpenAI text-embedding-3-large on 32 code retrieval datasets.
  3. RAG for codebase — reference architectureLLMversus (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.
  4. Local code-graph MCP comparisonAndrey Kumanyaev, zzet.org (2026-05-28). The four-paradigm framing that this paper adopts: graph, embeddings, LSP, hosted docs.
  5. Codebase-Memory: Tree-Sitter knowledge graphs via MCParXiv:2603.27277 (2026). Persistent Tree-Sitter knowledge graph for LLM code exploration through MCP.
  6. Codebase RAG model comparisonModal 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

MIT · Python

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

MIT · Python

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

github.com/oraios/serena

codesearch — structural / hybrid

Apache-2.0 · Rust

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

MIT · TypeScript

The only category-appropriate tool for “current API for React / SvelteKit / Cloudflare Workers.” Not indexing our repo — indexing the world.

github.com/upstash/context7

How we validate the pick

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 ÷ chunks as 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.json while 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/chunkhound tab for machines that can hold a model — it is no longer installed by mcp/install.sh. Status 2026-07: ChunkHound is re-enabled read-only by default in kilo.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.db to 225 GB for 2.3 GB of actual data (interrupted large transactions never reclaim pages, and DuckDB files never shrink). A dependency-ordered INSERT INTO…SELECT copy 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 mandatory database.max_disk_usage_mb cap and absolute database.path ship in the current mcp/install.sh scaffold.
  • 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/db points 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.db files, grouped (projectnexartisall), 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-assistant and no --project; agents activate_project the repo being edited. The fix ships in mcp/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 chunkhound regex or codesearch 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-augment extension 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.

What this means for us

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.

  1. Context Lineage — commit-diff summaries embedded alongside code chunksbuys: 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.
  2. Quantized ANN + full-embedding rerank, with a hot-set fallbackbuys: ~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.
  3. Code-relationship-trained embeddingsbuys: 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.
  4. 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.
  5. Proof-of-possessionbuys: 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-indexing available. 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, Python auggie-sdk. Marked Experimental — subject to breaking changes in Augment's own docs. Surfaces DirectContext / FileSystemContext.
Critical shape finding — no ranked chunks in the supported API

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.
Evidence hygiene — no retrieval-only IR numbers published

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.md mermaid 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

  1. 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.
  2. Voyage AI blog (2024) — Voyage Code-3. +13.8% over OpenAI text-embedding-3-large on 32 code retrieval datasets.
  3. 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.
  4. 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.
  5. arXiv:2603.27277 (2026) — Codebase-Memory: Tree-Sitter knowledge graphs via MCP. Persistent Tree-Sitter knowledge graph for LLM code exploration through MCP.
  6. Modal blog (2025) — Codebase RAG model comparison. Head-to-head benchmarks of six code-embedding models on code retrieval.
  7. Model Context Protocol — the substrate every tool in this paper speaks.
  8. Nomic Embed Code — model card.
  9. SFR-Embedding-Code-400M — Salesforce CodeXEmbed model card.
  10. Augment — Rethinking LLM Context: the Augment Context Engine — real-time GCP index, custom code embeddings, Proof-of-Possession, quantized ANN with fallback.
  11. Augment — Context Lineage (2025-07-29) — commit-diff summaries embedded alongside file chunks for semantic history retrieval.
  12. Augment docs — Context Engine MCP (local + remote)auggie --mcp, https://api.augmentcode.com/mcp, default-branch indexing.
  13. Augment docs — Context Engine SDK (Experimental)@augmentcode/auggie-sdk, DirectContext / FileSystemContext, search() returns a formatted string; no ranked chunks[].
  14. arXiv 2305.03010 and arXiv 2004.00053 — embedding-inversion attack literature cited by Augment as the reason not to use third-party embedding APIs.
  15. Augment — VS Code extension sunset notice (July 1, 2026) — marketplace listing header, captured 2026-07-28. The founding-inspiration primary source.
  16. Augment changelog — Next Edit and Completions sunset (2026-03-31) — dated 2026-03-05; plan-tier scope and stated rationale.
  17. Augment docs — feature availability matrix — per-plan capability surface of the extension, captured 2026-07-28.
  18. Augment — Context Modeling (2025-08-06) — edit-event-aware completions model; +45% of edits typed by the model at rollout.