Code intelligence
Code intelligence is the half of the circuit that grounds memory in verifiable
structure. It owns the six retrieval tiers, the query router that plans across
them, per-plane freshness, structural and boundary extraction, and impact
analysis with declared blind spots. Rule lifecycle belongs to governance;
cross-domain ranking to Retrieval; memory
semantics to Memory. The spec's State: notes
are the source of truth for what ships versus what is designed; this page
mirrors them.
Availability
| Surface | Tier | Residency | Notes |
|---|---|---|---|
zephr_grep (MCP) | search | deferred | T0 exact literal search (gitignore-aware) |
zephr_lsp (MCP) | search | deferred | Structural LSP navigation — def/refs, hover, diagnostics |
zephr_search (MCP) | search | resident | Unified search across admitted worktrees |
zephr_recall (MCP) | core | resident | Hybrid lexical + semantic recall (see Memory) |
zephr_graph_query (MCP) | search | deferred | T4 graph queries |
zephr search, grep (CLI) | — | — | See the CLI reference |
Two optional external binaries back local tiers: ug (ugrep) for T0 lexical
search and typescript-language-server for structural LSP search. Missing
binaries do not skip to "the remaining tiers": when ug is absent, T0
serves from a built-in pure-JS (Node fs + regex) engine, still
gitignore-aware; when typescript-language-server is absent, structural
requests return a structured lsp_unavailable error naming the missing server
(ZEP-2254).
The six tiers
| Tier | Name | Mechanism | Shipped? |
|---|---|---|---|
| T0 | Exact | ugrep over the worktree, pure-JS fallback | Yes as a live worktree search — the designed trigram/blob-sharded index is not built |
| T1 | Structural | WASM tree-sitter queries | Partial — TypeScript, JavaScript, Python only; ast-grep patterns not shipped |
| T2 | Symbolic | SCIP batch index + live LSP | Not shipped as designed — no SCIP serving path; symbol lookup ships via LSP structural search |
| T3 | Semantic | Embeddings over AST-derived function-boundary chunks | Partial — chunker and provider exist; demoted for identifier queries |
| T4 | Graph | Calls/imports/extends/implements/references edges | Partial — query tool registry-visible; answers absent_unindexed until a corpus is built |
| T5 | Behavioral | Git-derived churn, co-change, authorship | Unverified as a shipped surface |
T2 and T5 are honest gaps: the SCIP ingestion library has no shipped serving path and behavioral signals are unverified, so treat symbolic and behavioral results as unavailable until a serving surface lands.
Query routing and freshness
A query is routed deterministically, not compiled into a full plan:
zephr_search classifies from lexical features with zero model calls —
prefixed directives (def:, refs:, grep:), regex metacharacters,
identifier shape, prose length — then dispatches to lexical (ugrep),
structural (LSP), semantic (recall), or hybrid. When a symbol index is bound,
a unique normalized symbol hit short-circuits the router to structural search.
Results carry the mode and the backends that served them, and failures are
explicit (search_timeout, lsp_unavailable, per-backend errors), never
silent. The designed artifacts beyond this — an inspectable QueryPlan with
per-step budgets, an escalation ladder as a first-class output, and tier-pin
refusals — are specified, not shipped.
Freshness states (exact | overlay_current | commit_behind | plane_partial | provider_lag | unknown) and mode satisfaction (exact, bounded_stale,
best_effort; refuse rather than downgrade) are implemented at the
computation level, but not as an end-to-end serving contract: the plane builds
that would move a repository out of unknown are not enqueued from any
production code path, so live results will honestly report unknown for the
planes that were never built.
Persistence, security, observability
There is no prebuilt index to persist. The designed generation-manifest
pipeline (blob-sharded planes, atomic visibility, content-diff rebuilds) is
not built: worker loops for structural/semantic/graph builds exist but are
inert — nothing in production enqueues them. T0 searches the admitted worktree
live via ugrep (or the JS fallback), which is why exact search is always
current but never index-fast. Queries run only against admitted worktrees
(see Concepts: Trust for the admission boundary).
Lexical and structural serving stay on the machine; the semantic tier's
embedding provider is pluggable — local ONNX on-box, or a remote model via the
litellm proxy when configured — so a remote embedding provider does send chunk
content off-machine (egress). Graph queries read an indexed-corpus layer whose
builds are not enqueued today, so the honest answer is usually the typed
absent_unindexed.
Limits and failures
- T1 structural parsing is limited to TypeScript, JavaScript, and Python today.
- Identifier-shaped queries route to structural first and demote the semantic tier by design.
- Missing plane data yields
unknown, notexact;exactmode refuses a stale plane and names the lagging plane (freshness module level). - Missing
ugdegrades to the pure-JS engine; missingtypescript-language-serverreturnslsp_unavailable— neither pretends the tier ran. - Durable symbol identity and refactoring-aware blame are specified, not yet shipped; today a line range is only a hint, not an anchor.
Index staleness and search-quality symptoms are covered in Troubleshooting.