System Design

High-level system architecture and component interactions.

Component Diagram

graph LR
subgraph Client["Client Layer"]
A[Agent Application]
H[Hermes Framework]
end
subgraph API["API Layer"]
P[Python SDK]
T[Tool Schema]
end
subgraph Core["Core Engine"]
M[Mnemosyne class]
R1[BeamMemory]
S[Sleep]
I[SQLite + sqlite-vec + FTS5]
end
subgraph Storage["Storage Layer"]
SQLite[(SQLite DB)]
V[Vector Index]
F[FTS5 Index]
end
A --> P
H --> T
P --> M
T --> M
M --> R1
M --> S
R1 --> I
S --> I
I --> SQLite
I --> V
I --> F
style Core fill:#e0f2fe,stroke:#0284c7
style Storage fill:#f0fdf4,stroke:#16a34a

Core Components

Mnemosyne class

Central orchestrator handling all CRUD operations. Routes operations to appropriate memory tiers and manages cross-tier consistency.

BeamMemory

Hybrid search coordinator. Dispatches queries to vector and text indices, then fuses results using configurable scoring weights.

Sleep

On-demand consolidator triggered by calling sleep(). Groups older Working Memory entries by source, summarizes via LLM or AAAK, promotes to Episodic Memory, and evicts the originals.

SQLite + sqlite-vec + FTS5

Maintains all database indices: vector embeddings (via sqlite-vec, int8 quantized 384-dim vectors) and FTS5 full-text search tables.

Technology Stack

Scaling Considerations

Mnemosyne is designed for single-node deployments:

• Working Memory: SQLite-backed with configurable max (default 10,000 items, 24h TTL)
• Episodic Memory: SQLite with sqlite-vec extension for vector search
• TripleStore (Knowledge Graph): Subject-predicate-object triples stored in SQLite (via separate TripleStore class)

For multi-agent deployments, each agent maintains its own database instance. There is no built-in synchronization or shared-memory mechanism between instances.