State Management & Memory

SQLite-backed persistence with in-memory working memory, semantic search via embeddings, and tri-hybrid retrieval.

Database Schema

messages table

Key	Type	Default	Description
id	TEXT PK	—	UUID primary key
session_id	TEXT	—	Session identifier (indexed)
role	TEXT	—	user, assistant, or tool
content	TEXT	null	Message text content
tool_call_id	TEXT	null	ID for tool result messages
tool_name	TEXT	null	Tool name for tool messages
tool_calls_json	TEXT	null	JSON array of tool calls
created_at	TEXT	—	RFC3339 timestamp
importance	REAL	0.5	Importance score (0.0–1.0)
embedding	BLOB	null	JSON-encoded Vec<f32> embedding
embedding_error	TEXT	null	Error message if embedding failed
consolidated_at	TEXT	null	Memory consolidation timestamp

facts table

Key	Type	Default	Description
id	INTEGER PK	auto	Auto-incrementing primary key
category	TEXT	—	Grouping category
key	TEXT	—	Fact key (unique per category)
value	TEXT	—	Fact content
source	TEXT	""	Who stored it: "agent" or "user"
created_at	TEXT	—	RFC3339 timestamp
updated_at	TEXT	—	RFC3339 timestamp

Working Memory

An in-memory HashMap<String, VecDeque<Message>> per session, capped at working_memory_cap (default 50). Avoids database hits for recent conversation history.

Tri-Hybrid Retrieval

The get_context method combines three retrieval strategies:

Strategy	Source	Limit	Purpose
Recency	Last N messages	10	Conversational continuity
Salience	importance ≥ 0.8	5	Critical flagged memories
Relevance	Vector similarity > 0.65	5	Semantic search via embeddings

Results are deduplicated by message ID before being included in context.

Embedding Service

• Model: AllMiniLML6V2 (via fastembed)
• Runs in background — embeds new messages after they are appended
• Enables the relevance leg of tri-hybrid retrieval

Memory Consolidation

A background task runs every consolidation_interval_hours (default 6). It compresses old conversations into summaries using the fast model, reducing storage and context window usage.

Importance Scoring

Role	Default Score
User message	0.5
Assistant response	0.5
Tool output	0.3
System message	0.1

Connection Pool

• SQLite pool: max 5 connections
• Journal mode: WAL (Write-Ahead Logging) for concurrent reads
• Auto-creates database and tables if missing