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. When you query within a project, it heavily boosts (or exclusively restricts) results to that specific workspace layer, guaranteeing perfect isolation.

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 Claude Desktop, Cursor, and any future AI agents without requiring any custom UI development.