System Architecture

ContextOS is built on a modular architecture that separates storage, embedding generation, retrieval, and decision-making logic.

PostgreSQL & pgvector

Unlike systems that require a separate, specialized vector database (like Pinecone or Milvus), ContextOS stores everything in standard PostgreSQL. By using the pgvector extension with HNSW indexes, ContextOS achieves high-performance vector similarity search while maintaining ACID guarantees and transactional consistency between memories, states, and their embeddings.

The ContextOrchestrator

The ContextOrchestrator is the central conductor of the system. It owns and wires together the following subsystems:

• MemoryManager: Handles CRUD operations for ContextItems and their embeddings. It encapsulates all direct database interactions.
• Retriever: The Retrieval Engine Coordinator. It orchestrates parallel calls to the SemanticRetriever and Bm25Retriever, merges their results using RRF, hydrates the top candidates, and passes them to the CrossEncoderReranker.
• MemoryPlanner: The pure-function intelligence of ContextOS. It takes the retrieved candidates and a budget constraint, applies hybrid scoring, and returns an Execution Plan detailing which memories survive.
• BudgetManager: A stateless mathematical component that calculates token availability.
• PromptBuilder: Assembles the final selected memories into a single, cohesive context payload string.
• EmbeddingService: An abstraction layer over embedding models (e.g., local BGE, OpenAI).

Application Boundary

ContextOS explicitly does NOT manage LLM generation. It sits strictly between your application logic and your memory storage.

Your application calls ContextOS to get a ContextResult, and then passes the resulting string to an LLM client of your choice.

Application Logic
       │
       │ (1. "Build context for session X")
       ▼
  ContextOS ◄────────► PostgreSQL / pgvector
       │
       │ (2. ContextResult containing budgeted payload)
       ▼
Application Logic
       │
       │ (3. Send payload to LLM API)
       ▼
    OpenAI / Anthropic / vLLM