Architecture Overview

The end-to-end pipeline of ContextOS, from raw source files to compressed LLM prompts.

Implementation Sourcesrc/core/indexer/index.ts

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 Phase
1
Repository Scanner // Traverses workspace, dirty-checks hash
2
Tree-sitter Parser // Generates AST, extracts symbols & chunks
3
Graph Builder // Extracts internal symbol relations and file imports
4
Background Embedding // Non-blocking generation of dense vectors
5
SQLite Storage // Atomic commit to local .contextos DB
Runtime Phase
6
RRF Hybrid Retriever // BM25 + Vector Search + Intent Multipliers
7
Graph Expansion // BFS traversal through dependency edges
8
Compression Engine // Aggressive token reduction (stripping docs/imports)

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.

  • pLimit
    File watcher events are queued through a concurrency limiter (pLimit(5)). This provides crucial DOS protection during massive workspace changes (like a git checkout that touches thousands of files), preventing CPU starvation.
  • Sandbox Guards
    Strict 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.