AkurAI-Notes / docs/adr/003-zoekt-adopt-vs-build.md

Latest change b5edafd099fbb715485f63f0c36354159da099e2 - OLI-114: ADRs 002-005 (FTS vs ParadeDB, zoekt, chunking/embedding versioning, memory schema) by Dev Lead

# ADR 003: zoekt sidecar (adopt) vs building trigram/regex search

Status: Proposed (Dev Lead, 2026-09-30) · Epic OLI-112 · Task OLI-114

## Context
Agents need exact-string and regex search across repos and branches (`grep` semantics, at scale). FTS/dense do not give this. Building a trigram index is well understood but is a maintenance burden outside our core value.

## Decision
Adopt **zoekt** (`zoekt-webserver` + `zoekt-git-index`) as a loopback-only sidecar systemd unit, indexing the same bare mirrors `indexd` reads (`AKURAI_REPOS_DIR`). The push webhook triggers `zoekt-git-index` for the pushed repo/branch after `indexd` ingest; zoekt failure never fails ingest. `code_search mode=lexical` with `regex:` prefix routes to zoekt; other modes use the hybrid path. Results are mapped to the same `Hit` shape (path, line range, snippet).

## Status of implementation
Not installed yet: no `zoekt` binary on AkurAI-Build and the Go toolchain is not provisioned. A per-user install (`go install`, pinned version) needs a Platform-owned systemd unit; tracked as a follow-up for Platform. Interface is fixed here so it can land without changing MCP.

## Consequences
Extra Go binary and memory (~index size). Branch coverage limited to zoekt's configured branches (default + listed). Build-our-own is revisited only if zoekt cannot be kept on a pinned release.