Architecture Overview
The end-to-end pipeline of ContextOS, from raw source files to compressed LLM prompts.
The Pipeline
ContextOS operates in two distinct phases: Compile-Time (indexing) and Runtime (retrieval). Parsing, graph building, and embedding generation happen during indexing; query latency depends on repository size, storage, and the selected pipelines.
Compile-Time Subsystems
Parser (Tree-sitter) & Chunking
The parser converts raw string buffers into a structured AST. We use tree-sitter because it guarantees incremental parsing and fault tolerance. During extraction, the AST is shredded into independent Chunk objects (representing functions, interfaces, or classes), retaining exact byte offsets and parent symbol mappings.
Graph Builder
Once chunks are generated, the system maps internal and external dependencies. extractImportRelationships walks the import statements, mapping logical connections between file stems. These generate edges with specific traversal weights.
SQLite Storage & Foreign Keys
ContextOS uses SQLite WAL mode and transactions for local writes. Deleting a file removes its chunks and relationship rows through the relational schema; vector rows are cleaned explicitly because the sqlite-vec table does not provide a foreign-key cascade. The entire schema is defined locally in .contextos/index.db, which keeps the normal path offline.
Background Daemon & Concurrency
The contextos serve daemon manages all long-running indexing tasks without blocking the active developer workflow.
- pLimitFile watcher events are queued through a concurrency limiter (
pLimit(5)). This provides crucial DOS protection during massive workspace changes (like agit checkoutthat touches thousands of files), preventing CPU starvation. - Sandbox GuardsStrict path traversal guards ensure the Daemon never indexes files outside the approved workspace root, protecting sensitive system directories.
Runtime Subsystems
RRF Hybrid Retrieval
During a query, ContextOS does not rely solely on dense vectors. It runs a Reciprocal Rank Fusion (RRF) algorithm combining exact keyword matches from FTS5, semantic matches from the embedding store, and feedback_signals multipliers.
Compression Engine
After the graph expander collects the relevant nodes, the Compression Engine ensures the payload fits within the LLM's token budget. It utilizes hierarchical dropping—purging imports, docstrings, and low-priority chunks before it resorts to truncating business logic.