Code Intelligence & Engines
Trelix
Offline code intelligence engine — Tree-sitter indexing, hybrid BM25+vector+grep search
3 min read · 565 words
trelix is a production-ready code indexing and retrieval engine that transforms any repository into a queryable knowledge base. Where grep finds exact strings, trelix finds relevant code — via a hybrid retrieval pipeline, call-graph traversal, and LLM synthesis that answers "how does auth work?" with actual code paths, not a keyword hit list.
The engine combines three parallel retrieval legs — semantic embeddings (voyage/OpenAI/Bedrock Titan), BM25 keyword search (SQLite FTS5), and exact grep — fused via Reciprocal Rank Fusion. A 3-tier adaptive query planner routes direct lookups to tier 1 (zero retrieval), single-intent queries to tier 2 (8 intent types), and complex decomposition to tier 3 (LLM parallel planning). For large result sets, GraphRAG map-reduce scales synthesis beyond context limits.
- Contextual chunking — opt-in (
TRELIX_CHUNKER_CONTEXTUAL, off by default): LLM-generated per-chunk summaries; the repo takes the 67% retrieval-failure cut from Anthropic's research rather than measuring it - Call-graph expansion — PageRank-weighted traversal with
callee_type_hintprecision (40% fewer false edges) - Universal LLM client factory — 5 provider backends (OpenAI, Azure, Anthropic, Bedrock, Vertex) via one env var
- Zero-infra default — single
.trelix/index.dbSQLite file with a sqlite-vec flat-scan vector table + FTS5; no external services - Real-time watcher — debounced 500ms incremental re-indexing on file save, respects
.gitignore - MCP server — integrates natively with Claude Code, Cursor, Windsurf, LangChain, LlamaIndex
As of 2026-10-21, v3.4.3 (2026-10-04) is the latest release on PyPI and GitHub.
mainholds 4,435 unit and 98 integration test functions, a static count ofdef test_that does not expand parametrized cases and was not re-run, and CI enforces a 79% coverage gate on the unit suite.
Architecture
trelix runs as a single Python service around one SQLite file, in four layers:
- Indexer — tree-sitter parses each file; with contextual chunking on (off by default) an LLM summarizes each chunk before embedding; a call-graph builder tags edges with
callee_type_hint. - Storage —
.trelix/index.dbholds a sqlite-vec flat-scan vector table (a dead HNSW path was removed in v3.3.2), FTS5 BM25, and the call-graph table in one file; Qdrant/LanceDB are optional swaps. - Retrieval fan-out — up to 7 legs (vector, BM25, grep, file-summary, graph-search, SPLADE sparse, sub-chunk) merge via RRF (
k=60), deduplicated on file path + symbol ID + chunk ID. By default only vector, BM25 and grep run, and the README says to leave graph-search off: it was measured harmful on the project's own golden set (nDCG@10 -0.208 and -0.232 over two plan draws). - Planner + synthesizer — the 3-tier planner decides how much fan-out a query needs; GraphRAG map-reduce handles oversized results.
How It Works
- A save triggers the watcher (500ms debounce); tree-sitter re-parses the file.
- With contextual chunking on (it is off by default), each chunk gets an LLM summary before embedding — the technique behind the 67% retrieval-failure figure the repo cites.
- Chunk, embedding, FTS5 tokens, and call edges land in
.trelix/index.db. - A query hits the 3-tier planner: tier 1 answers direct lookups with no retrieval; tier 2 routes single-intent queries into 1 of 8 intent types; tier 3 has an LLM decompose first.
- Tiers 2 and 3 trigger up to 7 legs of fan-out (by default only vector, BM25 and grep; the other legs are config-gated), fused by RRF and deduplicated on file path + symbol ID + chunk ID.
- Call-graph expansion walks 1 hop for most single-intent types —
feature_flowis the exception, walking 2 hops despite the architecture doc's warning against it. - Oversized results synthesize in batches via GraphRAG map-reduce; the LLM answers from real code paths, not a keyword list.