Gerenciamento de Estado & Memória
Persistência em SQLite com memória de trabalho em memória, busca semântica via embeddings e recuperação tri-híbrida.
Atualização v0.9.x
A persistência principal das conversas agora usa a tabela
events. Os dados antigos de messages são migrados para events durante a atualização.Esquema do Banco de Dados
Tabela messages
| Key | Type | Default | Description |
|---|---|---|---|
id | TEXT PK | — | Chave primária UUID |
session_id | TEXT | — | Identificador da sessão (indexado) |
role | TEXT | — | user, assistant ou tool |
content | TEXT | null | Conteúdo textual da mensagem |
tool_call_id | TEXT | null | ID para mensagens de resultado de ferramenta |
tool_name | TEXT | null | Nome da ferramenta para mensagens de ferramenta |
tool_calls_json | TEXT | null | Array JSON de chamadas de ferramentas |
created_at | TEXT | — | Timestamp RFC3339 |
importance | REAL | 0.5 | Pontuação de importância (0.0–1.0) |
embedding | BLOB | null | Embedding codificado em JSON Vec |
embedding_error | TEXT | null | Mensagem de erro se o embedding falhou |
consolidated_at | TEXT | null | Timestamp de consolidação de memória |
Tabela facts
| Key | Type | Default | Description |
|---|---|---|---|
id | INTEGER PK | auto | Chave primária auto-incrementável |
category | TEXT | — | Categoria de agrupamento |
key | TEXT | — | Chave do fato (única por categoria) |
value | TEXT | — | Conteúdo do fato |
source | TEXT | "" | Quem armazenou: "agent" ou "user" |
created_at | TEXT | — | Timestamp RFC3339 |
updated_at | TEXT | — | Timestamp RFC3339 |
Tabela macros
| Key | Type | Default | Description |
|---|---|---|---|
id | INTEGER PK | auto | Chave primária auto-incrementável |
trigger_tool | TEXT | — | Ferramenta que aciona a macro |
trigger_args_pattern | TEXT | null | Padrão de argumentos para correspondência |
next_tool | TEXT | — | Ferramenta a encadear em seguida |
next_args | TEXT | — | Argumentos para a ferramenta encadeada |
confidence | REAL | 0.0 | Pontuação de confiança da macro |
used_count | INTEGER | 0 | Número de vezes que a macro foi usada |
created_at | TEXT | — | Timestamp RFC3339 |
updated_at | TEXT | — | Timestamp RFC3339 |
Tabela scheduled_tasks
| Key | Type | Default | Description |
|---|---|---|---|
id | TEXT PK | — | Chave primária UUID |
name | TEXT | — | Rótulo legível da tarefa |
cron_expr | TEXT | — | Expressão cron de 5 campos calculada |
original_schedule | TEXT | — | Entrada do usuário (linguagem natural ou cron) |
prompt | TEXT | — | Prompt do agente para executar no agendamento |
source | TEXT | — | "tool" (criada via ferramenta) ou "config" (do config.toml) |
is_oneshot | INTEGER | 0 | Disparar uma vez e depois auto-excluir |
is_paused | INTEGER | 0 | Tarefas pausadas não disparam |
is_trusted | INTEGER | 0 | Tarefas trusted ignoram aprovação do terminal |
next_run_at | TEXT | — | Timestamp RFC3339 da próxima execução agendada |
last_run_at | TEXT | null | Timestamp RFC3339 da última execução |
created_at | TEXT | — | Timestamp RFC3339 |
updated_at | TEXT | — | Timestamp RFC3339 |
Tabela terminal_allowed_prefixes
| Key | Type | Default | Description |
|---|---|---|---|
prefix | TEXT PK | — | Prefixo de comando persistido a partir de aprovações "Permitir Sempre" |
Memória de Trabalho
Um HashMap em memória por sessão, limitado a working_memory_cap (padrão 50). Evita acessos ao banco de dados para o histórico recente da conversa.
Recuperação Tri-Híbrida
O método get_context combina três estratégias de recuperação:
| Estratégia | Fonte | Limite | Propósito |
|---|---|---|---|
| Recência | Últimas N mensagens | 10 | Continuidade conversacional |
| Saliência | importance ≥ 0.8 | 5 | Memórias críticas sinalizadas |
| Relevância | Similaridade vetorial > 0.65 | 5 | Busca semântica via embeddings |
Os resultados são deduplicados por ID da mensagem antes de serem incluídos no contexto.
Serviço de Embedding
- Modelo: AllMiniLML6V2 (via fastembed)
- Roda em segundo plano — gera embeddings de novas mensagens após serem adicionadas
- Habilita a etapa de relevância da recuperação tri-híbrida
Consolidação de Memória
Uma tarefa em segundo plano roda a cada consolidation_interval_hours (padrão 6). Ela comprime conversas antigas em resumos usando o modelo fast, reduzindo armazenamento e uso da janela de contexto.
Pontuação de Importância
| Papel | Pontuação Padrão |
|---|---|
| Mensagem do usuário | 0.5 |
| Resposta do assistente | 0.5 |
| Saída de ferramenta | 0.3 |
| Mensagem do sistema | 0.1 |
Pool de Conexões
- Pool SQLite: máximo de 5 conexões
- Modo de journal: WAL (Write-Ahead Logging) para leituras concorrentes
- Cria automaticamente o banco de dados e tabelas se ausentes