Zephr Docs

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

SurfaceTierResidencyNotes
zephr_grep (MCP)searchdeferredT0 exact literal search (gitignore-aware)
zephr_lsp (MCP)searchdeferredStructural LSP navigation — def/refs, hover, diagnostics
zephr_search (MCP)searchresidentUnified search across admitted worktrees
zephr_recall (MCP)coreresidentHybrid lexical + semantic recall (see Memory)
zephr_graph_query (MCP)searchdeferredT4 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

TierNameMechanismShipped?
T0Exactugrep over the worktree, pure-JS fallbackYes as a live worktree search — the designed trigram/blob-sharded index is not built
T1StructuralWASM tree-sitter queriesPartial — TypeScript, JavaScript, Python only; ast-grep patterns not shipped
T2SymbolicSCIP batch index + live LSPNot shipped as designed — no SCIP serving path; symbol lookup ships via LSP structural search
T3SemanticEmbeddings over AST-derived function-boundary chunksPartial — chunker and provider exist; demoted for identifier queries
T4GraphCalls/imports/extends/implements/references edgesPartial — query tool registry-visible; answers absent_unindexed until a corpus is built
T5BehavioralGit-derived churn, co-change, authorshipUnverified 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, not exact; exact mode refuses a stale plane and names the lagging plane (freshness module level).
  • Missing ug degrades to the pure-JS engine; missing typescript-language-server returns lsp_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.