Memory System

ContextBrain provides three types of memory for AI agents:

Memory Types

Semantic Memory

Long-term knowledge stored as vector embeddings. This is the main knowledge store — documents, articles, product descriptions, etc. Queried via QueryMemory.

Episodic Memory

Conversation history. Each turn is stored as an episode linked to a session:

from contextunity.core import ContextUnit, contextunit_pb2

# Add a conversation turn
unit = ContextUnit(payload={
    "tenant_id": "my_project",
    "session_id": "conv_abc123",
    "role": "user",
    "content": "What is RAG?",
})
stub.AddEpisode(unit.to_protobuf(contextunit_pb2))

unit = ContextUnit(payload={
    "tenant_id": "my_project",
    "session_id": "conv_abc123",
    "role": "assistant",
    "content": "RAG stands for Retrieval-Augmented Generation...",
})
stub.AddEpisode(unit.to_protobuf(contextunit_pb2))

Episodic memory is scoped by session_id and tenant_id, enabling agents to recall previous conversation context.

BrainCells

Persistent facts, preferences, summaries, and entity memory are stored as canonical BrainCells in cells:

# Store a user preference
unit = ContextUnit(payload={
    "tenant_id": "my_project",
    "user_id": "user_123",
    "cell_kind": "fact",
    "content": "language=Ukrainian",
    "metadata": {"key": "language", "value": "Ukrainian"},
    "source_type": "manual",
})
stub.UpsertCell(unit.to_protobuf(contextunit_pb2))

BrainCells persist across sessions and are queried through QueryCells when relevant.

Memory in the Agent Loop