Trelix

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 — LLM-generated per-chunk summaries; 67% retrieval failure reduction vs. naive chunking
• Call-graph expansion — PageRank-weighted traversal with callee_type_hint precision (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.db SQLite file with HNSW vector index + 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

929 unit tests + 16 integration tests, 75% coverage gate enforced. First stable release v1.0.0.

Architecture

trelix runs as a single Python service around one SQLite file, in four layers:

• Indexer — tree-sitter parses each file; an LLM summarizes each chunk (contextual chunking) before embedding; a call-graph builder tags edges with callee_type_hint.
• Storage — .trelix/index.db holds sqlite-vec's HNSW index, 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-Code sparse, sub-chunk) merge via RRF (k=60), deduplicated on file path + symbol ID.
• Planner + synthesizer — the 3-tier planner decides how much fan-out a query needs; GraphRAG map-reduce handles oversized results.

How It Works

1. A save triggers the watcher (500ms debounce); tree-sitter re-parses the file.
2. Each chunk gets an LLM summary before embedding — the 67% retrieval-failure cut behind contextual chunking.
3. Chunk, embedding, FTS5 tokens, and call edges land in .trelix/index.db.
4. 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.
5. Tiers 2 and 3 trigger up to 7 legs of fan-out (fewer by default — the extra legs are config-gated), fused by RRF and deduplicated on file path + symbol ID.
6. Call-graph expansion walks 1 hop for most single-intent types — feature_flow is the exception, walking 2 hops despite the traversal code's own warning against it.
7. Oversized results synthesize in batches via GraphRAG map-reduce; the LLM answers from real code paths, not a keyword list.

A note on the numbers above: the frontmatter's 1,467 unit tests and the pull-quote's 929 unit + 16 integration disagree, and neither matches the repo today. 1,467 is CHANGELOG.md's exact v2.4.0 figure; 929/16 appears nowhere in the CHANGELOG, git history, or CI config. Live against HEAD (v3.2.5): 4,353 unit tests, 81 integration, up from 1,643 at v2.9.0. The coverage gate moved too, from 75% (v1.0.0) to 79% today.