Open to Backend, GenAI & Full-Stack roles · remote or Hyderabad

Projects

Code Intelligence & Engines

Trelix

Offline code intelligence engine — Tree-sitter indexing, hybrid BM25+vector+grep search

3 min read · 565 words

View repo 1,556 commits updated today
Python tree-sitter sqlite-vec SQLite BM25 FastAPI LiteLLM networkx Qdrant LanceDB PyInstaller Pydantic

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_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 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. main holds 4,435 unit and 98 integration test functions, a static count of def 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.db holds 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

  1. A save triggers the watcher (500ms debounce); tree-sitter re-parses the file.
  2. 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.
  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 (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.
  6. Call-graph expansion walks 1 hop for most single-intent types — feature_flow is the exception, walking 2 hops despite the architecture doc's warning against it.
  7. Oversized results synthesize in batches via GraphRAG map-reduce; the LLM answers from real code paths, not a keyword list.