State Management & Memory
SQLite-backed persistence with in-memory working memory, semantic search via embeddings, and tri-hybrid retrieval.
v0.9.x update
Canonical conversation persistence is now the
events table. Legacy messages data is migrated into events during upgrade.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 |
macros table
| Key | Type | Default | Description |
|---|---|---|---|
id | INTEGER PK | auto | Auto-incrementing primary key |
trigger_tool | TEXT | — | Tool that triggers the macro |
trigger_args_pattern | TEXT | null | Arguments pattern to match |
next_tool | TEXT | — | Tool to chain next |
next_args | TEXT | — | Arguments for the chained tool |
confidence | REAL | 0.0 | Confidence score for the macro |
used_count | INTEGER | 0 | Number of times the macro has been used |
created_at | TEXT | — | RFC3339 timestamp |
updated_at | TEXT | — | RFC3339 timestamp |
scheduled_tasks table
| Key | Type | Default | Description |
|---|---|---|---|
id | TEXT PK | — | UUID primary key |
name | TEXT | — | Human-readable task label |
cron_expr | TEXT | — | Computed 5-field cron expression |
original_schedule | TEXT | — | User input (natural language or cron) |
prompt | TEXT | — | Agent prompt to execute on schedule |
source | TEXT | — | "tool" (created via tool) or "config" (from config.toml) |
is_oneshot | INTEGER | 0 | Fire once then auto-delete |
is_paused | INTEGER | 0 | Paused tasks do not fire |
is_trusted | INTEGER | 0 | Trusted tasks skip terminal approval |
next_run_at | TEXT | — | RFC3339 timestamp of next scheduled run |
last_run_at | TEXT | null | RFC3339 timestamp of last execution |
created_at | TEXT | — | RFC3339 timestamp |
updated_at | TEXT | — | RFC3339 timestamp |
terminal_allowed_prefixes table
| Key | Type | Default | Description |
|---|---|---|---|
prefix | TEXT PK | — | Command prefix persisted from "Allow Always" approvals |
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