Design Decisions
The rationale behind the core architectural choices in ContextOS.
Why SQLite? (Instead of a Vector Database)
Vector databases (Pinecone, Milvus, Chroma) are designed for global semantic search. They map words into high-dimensional space to find "conceptual" similarities.
ContextOS is designed for exact syntactic resolution. If you query DatabaseConnection, you don't want "something conceptually similar to a database", you want the exact class definition. SQLite's FTS5 (Full Text Search) provides instant, exact substring and token matching with zero overhead. Furthermore, SQLite is a single local file, requiring no Docker containers, no cloud accounts, and no network latency.
Why AST-based Chunking?
Most RAG (Retrieval-Augmented Generation) pipelines chunk text using naive sliding windows (e.g., every 500 words). In code, a sliding window might cut a function in half, stranding the return statement in chunk B while the parameters are in chunk A.
ContextOS parses the raw code using tree-sitter into an Abstract Syntax Tree (AST). It chunks code exactly by its logical boundaries: classes, interfaces, and functions. This ensures the LLM receives syntactically valid blocks of code.
Why Project-Local Databases?
Global indexing tools dump all your repositories into a single massive index. If you have five different projects using a User class, asking an LLM to "fix the User authentication" will retrieve User files from all five projects, destroying the context window with irrelevant noise.
ContextOS uses .contextos/index.db files stored directly inside each repository. A normal query opens the local project database and may also open the shared ~/.contextos/index.db for global memory, with configured layer boosts and foreign-workspace demotion. Use the layers option when a query must be restricted to a particular layer; local project state is isolated by its database path, while global context is intentionally shared.
Why BM25 over Embeddings?
Embeddings suffer from the "Semantic Collision" problem in codebases. A StripePaymentService and a PayPalPaymentService embed very closely together because they share semantic concepts, but syntactically they share no code.
BM25 (using SQLite FTS5) ranks by term frequency. It guarantees that searching for StripePaymentService will return exactly that file, completely ignoring PayPalPaymentService. It is also completely local and requires no GPU inference.
Why MCP? (Model Context Protocol)
Instead of building a bespoke VSCode extension, a JetBrains plugin, and a standalone chat UI, ContextOS exposes its retrieval engine via the open Model Context Protocol. This allows it to natively hook into any AI Agent without requiring any custom UI development.