Architecture

MoltBrain uses a hybrid memory architecture combining structured storage (SQLite) and semantic search (ChromaDB) to provide persistent, intelligent memory for AI agents. This dual-storage approach gives you both fast queries and context-aware retrieval.

System Overview

MoltBrain follows a layered architecture where agent platforms connect through various integration methods (extensions, MCP servers, plugins) to a central worker service that manages all memory operations.

MoltBrain Architecture

┌─────────────────────────────────────────────────────────┐
│              AGENT (Platform)                           │
│    OpenClaw | MoltBook | Claude Code                    │
└──────────────────┬──────────────────────────────────────┘
                   │
                   │ MCP / Extension / Plugin
                   │
    ┌──────────────┼──────────────┐
    │              │              │
    ▼              ▼              ▼
┌─────────┐   ┌──────────┐   ┌──────────┐
│OpenClaw │   │ MoltBook │   │  Claude  │
│Extension│   │   MCP    │   │  Plugin  │
└────┬────┘   └────┬─────┘   └────┬─────┘
     │             │              │
     └─────────────┼──────────────┘
                   │
                   │ HTTP/REST
                   │
         ┌─────────▼─────────┐
         │  WORKER SERVICE   │
         │  localhost:37777  │
         │                   │
         │  • Memory Storage  │
         │  • Context Recall  │
         │  • Semantic Search │
         └─────────┬─────────┘
                   │
     ┌─────────────┼─────────────┐
     │             │             │
     ▼             ▼             ▼
┌─────────┐   ┌──────────┐   ┌──────────┐
│ SQLite  │   │ ChromaDB │   │   Web   │
│Database │   │  Vector  │   │ Viewer  │
│         │   │  Search  │   │   UI    │
└─────────┘   └──────────┘   └──────────┘

Integration Layer

Platform-specific integrations (extensions, MCP, plugins) handle communication between agents and MoltBrain.

Worker Service

Central service that processes memory operations, handles API requests, and manages storage.

Storage Layer

Hybrid storage combining SQLite for structured data and ChromaDB for semantic search.

Hybrid Memory System

MoltBrain's hybrid architecture combines two complementary storage systems, each optimized for different use cases. This dual approach gives you both the speed of structured queries and the intelligence of semantic search.

Structured Memory (SQLite)

Optimized for fast queries, relationships, and analytics. Perfect for retrieving specific observations, filtering by metadata, and generating reports.

  • ACID transactions - Data integrity guaranteed
  • Indexed queries - Sub-millisecond lookups
  • Relational data - Complex filtering and joins
  • Stores - Observations, sessions, tags, favorites, analytics

Schema: observations, sessions, tags, favorites, analytics

Semantic Memory (ChromaDB)

Vector database for context-aware retrieval. Finds relevant memories by meaning, not just keywords. Handles paraphrasing and conceptual similarity.

  • Vector embeddings - Semantic representations of content
  • Similarity search - Find by meaning, not exact match
  • Context matching - Match current context to past experiences
  • Fuzzy matching - Handles variations and paraphrasing

Embedding model: OpenAI text-embedding-3-small

Why Both?

SQLite gives you speed and precision for structured queries like "get all observations from last week" or "find sessions with tag 'authentication'". ChromaDB gives you intelligence and context for queries like "find memories about user authentication" even if the exact words differ. Together, they provide comprehensive memory capabilities.

Memory Lifecycle

Every agent interaction goes through a complete memory lifecycle, from context injection to observation capture to storage. Understanding this flow helps you optimize how MoltBrain works with your agents.

Memory Lifecycle Flow

SESSION START
    │
    ├─► Query SQLite for recent observations
    ├─► Search ChromaDB for relevant context
    ├─► Rank and combine results
    └─► Inject top N memories into agent context
    │
    ▼
AGENT INTERACTION
    │
    ├─► Capture Observations
    │   ├─► Extract facts, decisions, code
    │   ├─► Generate embeddings
    │   └─► Identify metadata (files, tools, etc.)
    │
    ▼
MEMORY STORAGE
    │
    ├─► SQLite: Store structured data
    │   └─► Observations, sessions, metadata
    │
    └─► ChromaDB: Store semantic vectors
        └─► Embeddings for similarity search
    │
    ▼
SESSION END
    │
    └─► Generate Summary
        ├─► Aggregate key learnings
        ├─► Extract decisions
        └─► Store session metadata
1

Session Start

When a new session begins, MoltBrain queries both storage systems to find relevant memories:

  • SQLite: Recent observations, sessions with same project path
  • ChromaDB: Semantically similar memories based on current context

Results are ranked, combined, and the top N (default: 50) are injected into the agent's context window.

2

Agent Interaction

During the session, MoltBrain automatically captures observations from agent responses:

  • Facts - Information learned or stated
  • Decisions - Architecture choices, tool selections
  • Code - Code patterns, implementations
  • Learnings - Insights and discoveries
3

Memory Storage

Each observation is stored in both systems:

SQLite

Structured data with metadata, timestamps, relationships

ChromaDB

Vector embeddings for semantic search

4

Session End

When the session ends, MoltBrain generates a summary that aggregates key learnings, decisions, and patterns. This summary becomes a high-level memory that can be quickly retrieved in future sessions.

Data Flow & Query Process

Understanding how data flows through MoltBrain helps you optimize memory usage and retrieval performance.

Observation Capture

When an agent makes a response, MoltBrain extracts observations:

// Example observation extraction
{
  "type": "decision",
  "content": "Use JWT tokens for authentication",
  "metadata": {
    "files": ["auth.ts", "middleware.ts"],
    "tools": ["write_file"],
    "projectPath": "/Users/dev/my-app"
  },
  "tags": ["authentication", "security"]
}

This observation is then stored in both SQLite (with all metadata) and ChromaDB (as a vector embedding).

Context Retrieval

When retrieving context, MoltBrain performs a dual query:

SQLite Query

SELECT * FROM observations 
WHERE projectPath = '/Users/dev/my-app'
  AND createdAt > datetime('now', '-7 days')
ORDER BY createdAt DESC
LIMIT 50;

ChromaDB Query

// Semantic search
query = "authentication setup"
results = chromadb.query(
  query_texts=[query],
  n_results=50,
  where={"projectPath": "/Users/dev/my-app"}
)

Results are combined, ranked by relevance, and the top N are selected for context injection.

Performance Characteristics

Storage

  • • SQLite: ~1KB per observation
  • • ChromaDB: ~1.5KB per embedding
  • • Typical project: 1000 observations ≈ 2.5MB

Query Performance

  • • SQLite queries: <10ms for 10K observations
  • • ChromaDB search: <50ms for semantic search
  • • Context injection: <100ms total

Integration Points

MoltBrain integrates with agent platforms through different mechanisms, each optimized for the platform's architecture.

OpenClaw: Extension Hooks

Full lifecycle integration with onSessionStart, onMessage, onResponse, and onSessionEnd hooks.

MoltBook: MCP Server

Model Context Protocol server exposing tools for memory sharing and cross-agent learning.

Claude Code: Plugin System

Plugin hooks into SessionStart, PostToolUse, and Stop events for automatic memory capture.