Copy as MD MD

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

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 . --watch
ctxe index .
ctxe index . --force

Use --watch for the primary initial-index workflow. Plain ctxe index . remains available for a one-shot, catalog-only index.

Background indexing

ctxe index PATH --watch is an ordered composition. It first runs the foreground indexing pipeline and activates accepted catalog membership from a durable complete or incomplete report. Only after that activation does it perform the existing durable Watch Registry transition for the same admitted workspace.

This flag is not an in-process filesystem watcher, does not couple the catalog and Watch Registry schemas, and does not enable or start the operating-system-supervised daemon. Installation creates the service definition disabled and stopped, so users still enable it explicitly:

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

Watch persistence becomes durable before CtxE asks a running daemon to reconcile it. If that notification is unavailable, the next daemon start or periodic reconciliation applies the saved intent; the flag does not promise immediate live attachment.

Accepted catalog membership and daemon watch intent remain independent. After a durable report, ctxe index /path/to/project followed by ctxe daemon watch /path/to/project is equivalent in intent to choosing --watch. 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.