Memory Model

The memory model in ContextOS is designed to treat every piece of information as a first-class ContextItem. Whether it is a system prompt, a user message, or a retrieved document, it all follows the same schema.

ContextItem

A ContextItem is the fundamental unit of memory. It contains:

• id: UUID of the memory.
• session_id: UUID grouping memories into a conversational session or namespace.
• role: Enum (SYSTEM, USER, ASSISTANT) indicating who generated the item.
• source: Enum indicating where it came from (e.g., USER vs SYSTEM).
• content: The actual text content.
• token_count: Pre-calculated token length to accelerate planning.
• created_at: Timestamp used for chronological sorting and recency scoring.

ContextEmbedding

Each ContextItem typically has a corresponding ContextEmbedding. This decoupling allows you to regenerate embeddings or use different models without altering the underlying text data.

Embeddings are stored natively in PostgreSQL using the pgvector extension.