How It Works

CtxE combines syntax-aware chunking, local retrieval indexes, a symbol knowledge graph, and server-backed reasoning.

Indexing pipeline

Running ctxe index executes an incremental two-phase pipeline:

  1. Parse and publish locally. CtxE discovers supported files, applies ignore rules, creates syntax-aware chunks, extracts symbols and relationships, and commits the local index atomically.
  2. Embed and enrich. After the database write transaction has ended, CtxE sends bounded batches to the authenticated CTXE Server and stores returned vectors and optional enrichment artifacts.

The separation is deliberate: network calls never run inside a database write transaction.

Local index

Code-aware chunks

Tree-sitter and composite language profiles preserve meaningful functions, types, modules, and neighboring context instead of arbitrary line windows.

Hybrid retrieval

SQLite FTS5 supports indexed text search, while sqlite-vec stores embeddings for semantic retrieval. Reranking can refine candidate order.

Knowledge graph

Symbol definitions and typed edges capture calls, implementations, imports, type usage, references, and other code relationships.

Workspace records

Ask and related workflows can persist structured records in a separate records database without coupling their lifecycle to index rebuilds.

Ask pipeline

ctxe ask and the MCP ask_context tool use the same goal-driven evidence pipeline:

  1. Embed the question and retrieve semantic and indexed-text candidates.
  2. Resolve definitions, usages, graph paths, impact, and relevant paths as needed.
  3. Promote bounded evidence with source locations and captured source snapshots.
  4. Compose an answer grounded in the gathered evidence and report degradation or truncation explicitly.

Effort controls the maximum planner rounds: min uses 3, medium uses 6, and high uses 48. The configured default is used when no override is supplied.

Evidence validity

Ask captures source content when evidence enters the full-content path. Responses distinguish unchanged, changed, unverifiable, missing, partial, and unavailable source states. These diagnostics describe cited evidence at capture time; they do not claim that the entire workspace is current.

When current source after the Ask capture matters, follow up with fetch_chunks or re-index the workspace.

Incremental indexing

CtxE hashes discovered files and reprocesses changed content plus pending pipeline work. Use --force only when you intentionally need to ignore cached hashes.

ctxe index . --dry-run
ctxe index .
ctxe index . --force

Background indexing

The daemon is an operating-system-supervised worker. Installation creates its definition disabled and stopped; users explicitly request workspace watch intent and enable the service.

ctxe daemon watch /path/to/project
ctxe daemon enable --now
ctxe daemon status
ctxe daemon list

Accepted catalog membership and daemon watch intent are independent. ctxe index can establish a usable cataloged index without enabling continuous watching, while ctxe daemon unwatch preserves catalog membership and derived data. Foreground Ask can read the latest committed index while a writer is active.

Graceful degradation

Runtime query paths can continue with available local capabilities when optional enrichment, reranking, graph expansion, or server composition is unavailable. Structured output reports warnings, errors, degradation, and truncation so clients can distinguish a complete answer from a partial one.