Code Search for Agents — Zoekt over EFS

DRAFT — pending Harsh's verification and employer sign-off.

This page documents the agent-facing code-search capability on Memex — Auction.com's internal AI coding-agent platform on EKS. It is the tool that gives an LLM coding agent whole-org code awareness: one query, every repo, only the matching lines, cheaply.

1. The problem

An LLM coding agent working across a large multi-repo org can't reason about code it can't see. Grepping one cloned repo at a time is slow, misses every repo not on disk, and burns tokens shuttling whole file contents back into context. What the agent needs is one tool that searches every repo in the org and returns only the matching lines, with context, affordably — without cloning everything locally.

2. System shape

The index is Zoekt, Sourcegraph's trigram code-search engine, running over mirrored git repos. The mirrors live on a shared EFS volume (/mnt/efs/<org>/…) that is mounted identically across the EC2 and Kubernetes hosts that serve and query the index, so a path that resolves on one host resolves on all of them — no per-host remapping.

A small connector exposes two tools to the agent: codesearch (search) and codesearch_repos (list the indexed repos). Both POST to the Zoekt webserver's JSON API (/api/search and /api/list) via curl. Results are decoded and reformatted into compact, line-numbered blocks grouped by repo and file, with > marking the actual matched lines versus context lines.

flowchart LR
  agent[Agent] -->|"codesearch / codesearch_repos"| connector[Connector]
  connector -->|curl| zoekt[Zoekt webserver]
  repos["EFS-mirrored repos\n(shared mount, same path everywhere)"] -->|trigram index| zoekt

A separate sync process keeps the mirrors fresh; the connector itself only reads the already-built index.

3. Trigram index over grep-the-clones

Zoekt gives sub-second regex search across the whole org without cloning everything locally or paying grep's linear scan. The agent gets org-wide recall — "where in the company is this symbol defined?" — that a per-repo tool structurally cannot provide. The rejected alternative, a hosted SaaS code-search product, would have moved proprietary source outside the perimeter; self-hosted Zoekt over EFS mirrors keeps the index and the source inside it.

This is the same instinct as the build-triage tool's "structured data before raw logs": reach for the index that names the location directly, and only go deeper once you know where to look.

4. Translate human globs into Zoekt regex at the boundary

Users — and the model — naturally write file:*.yaml. Zoekt wants a regex. Rather than make the caller learn Zoekt query syntax, the tool rewrites glob file-filters into anchored regex at the boundary (*→.*, ?→., escape ., anchor at $) before querying, so the ergonomic syntax "just works."

repo: and file: filters are first-class optional tool params that get prepended to the raw query, so the model can pin a search to one repo or one file glob without knowing anything about Zoekt's query language.

Reusable pattern: accept the syntax humans reach for; translate to the engine's syntax inside the tool, not in the user's head. Push the impedance matching into the boundary, and the model never has to learn the underlying DSL.

5. Return matches, not files

The formatter emits only the matched chunks with a couple of context lines each — never whole files. Line numbers are preserved and matched lines are marked, so the output stays precise enough to act on while remaining affordable in tokens on a broad search. This is the exact same discipline as the build-triage connector's bounded-log access: tools over large corpora return the smallest useful slice, and the model asks for more only if it needs to.

Two more details make the formatter robust:

• Tolerant response parsing. Zoekt's JSON shape varies — Files versus FileMatches, ChunkMatches versus LineMatches — and match content is base64-encoded. The formatter handles both shapes and decodes safely (a bad base64 falls back to raw), so a schema quirk never crashes a search.
• Strip the mirror prefix. Indexed repos carry a github.com/<org>/… prefix internally; the repo-list tool strips it, so the model and the user see plain repo names.

6. Deployment, freshness, and the perimeter

The index is rebuilt by a nightly indexing CronJob that runs against the org's mirrored repos — the same 120+ repos that were migrated from Bitbucket to GitHub — and stores the trigram index on the shared EFS volume so it persists across pod restarts and is shared between the indexer and the webserver. The zoekt-webserver runs as a Kubernetes Deployment on arm64 (Graviton) node pools, fronted by an nginx sidecar that handles routing and auth concerns while the webserver serves the search API. The endpoint is exposed internally and wired into agent tooling, so an agent can query the codebase the same way a human engineer would before deciding what to do next.

Keeping the stack self-hosted over EFS mirrors is a deliberate perimeter decision: proprietary source and its index never leave the environment, which matters precisely because the thing being searched is proprietary code.

7. Robust HTTP and the query budget

HTTP is defensive and actionable. The connector uses curl -s -f --max-time, captures the status code out-of-band, and returns explicit non-200 and non-JSON failures that point at the expected endpoint rather than handing the model a stack trace. If the index is unreachable, the model is told where it tried and what the default URL is. Query timeouts are bounded — 30 seconds for search, 10 seconds for the repo list — with a default of 2 context lines and a cap of 30 file matches per result, keeping any single query within a predictable token budget.

8. Honest gaps

No measured adoption or latency metrics are recorded in the source — a strong version of this story ("we gave our coding agent whole-org code search") would benefit from real numbers: repos indexed, index size, p50/p95 query latency, and searches per day. Those would need to be pulled live and are not in the material this page was distilled from. The sync pipeline — the process that keeps the EFS mirrors fresh — is referenced by the design but its implementation was not part of this extraction; a complete architecture story would document it as a follow-up.

Sources

This page was distilled from Harsh's commit history and session logs on the Memex platform — the code-search connector and its Zoekt integration — cross-checked against the in-repo PRD and resume. No internal hostnames, org names, or proprietary source code appear; the connector is described, not copied. Every architectural claim above traces to that material.