# Sessoes e Memoria ## Sessoes ### Como as Sessoes Funcionam Toda conversa com um agente acontece em uma **sessao**. Sessoes sao identificadas por chaves que codificam o contexto -- qual agente, qual canal, qual chat. Sessoes mantem uma transcricao completa (JSONL append-only) de todas as mensagens, chamadas de ferramentas e resultados. Esta transcricao e o que da contexto aos agentes sobre a conversa em andamento. ### Chaves de Sessao Sessoes sao roteadas automaticamente com base no contexto: | Padrao | Significado | |--------|-------------| | `agent:main:main` | Conversa direta principal | | `agent:::group:` | Chat de grupo em um canal especifico | | `agent:::channel:` | Conversa de canal/sala | | `cron:` | Execucao de job agendado | | `hook:` | Execucao acionada por webhook | ### Ciclo de Vida da Sessao - **Reset diario** -- Sessoes resetam automaticamente em um horario configuravel (padrao 4h local). Isso cria um contexto de conversa novo a cada dia, preservando o historico. - **Expiracao por inatividade** -- Sessoes que nao estiveram ativas por um periodo configuravel podem auto-resetar. - **Reset manual** -- Comece do zero a qualquer momento com um comando `/new` ou `/reset`. ### Rastreamento de Tokens Sessoes rastreiam uso acumulado de tokens (entrada, saida, leitura de cache, escrita de cache) para monitoramento de custos e gestao de janela de contexto. --- ## Compactacao ### O Que E Compactacao? Quando uma conversa se aproxima do limite da janela de contexto do modelo, Neotask a **compacta** -- resumindo mensagens antigas em uma visao geral condensada e iniciando uma nova sessao com esse resumo mais mensagens recentes. ### Como Funciona 1. **Deteccao** -- Monitora uso de contexto (gatilho padrao: 80% da janela de contexto) 2. **Sumarizacao** -- Mensagens antigas sao resumidas em uma entrada de compactacao 3. **Nova sessao** -- Uma sessao nova comeca com o resumo injetado no topo 4. **Preservacao** -- Transcricoes antigas sao preservadas para historico mas nao mais carregadas no contexto ### Configuracao - **Habilitado/desabilitado** -- Ative/desative auto-compactacao - **Limiar** -- Porcentagem da janela de contexto que aciona compactacao (padrao 80%) - **Minimo de mensagens** -- Nao compacte se houver menos de N mensagens ### Compactacao Manual Voce pode acionar compactacao manualmente a qualquer momento com o comando `/compact`. Isso e util quando voce quer resetar o contexto sem perder informacoes importantes. --- ## Memoria ### Memoria do Agente Cada agente tem um sistema de memoria para persistir informacoes importantes entre sessoes: - **MEMORY.md** -- Um arquivo markdown no workspace do agente onde fatos, preferencias e contexto importantes sao armazenados - **Diretorio de memoria** -- Arquivos adicionais em `memory/` para conhecimento estruturado ### Busca Vetorial Neotask suporta busca por similaridade vetorial sobre a memoria do agente: 1. **Indexacao** -- Arquivos de memoria sao indexados usando embeddings 2. **Busca** -- Agentes consultam a memoria com linguagem natural ("O que o usuario disse sobre suas preferencias de API?") 3. **Recuperacao** -- Memorias relevantes sao retornadas classificadas por similaridade ### Plugin de Memoria (LanceDB) O plugin de memoria LanceDB fornece armazenamento vetorial avancado: - Banco de dados vetorial persistente - Tamanho de chunk e sobreposicao configuraveis - Busca por similaridade eficiente - Re-indexacao automatica quando arquivos de memoria mudam ### Recuperacao Automatica No inicio da sessao, memorias relevantes podem ser automaticamente recuperadas e injetadas no contexto do agente. Isso da continuidade aos agentes entre sessoes sem carregar historicos inteiros de conversa. --- ## Persistencia de Sessao Todos os dados de sessao sao armazenados localmente: - **Metadados de sessao** -- `sessions.json` rastreia sessoes ativas, ultima atividade, contagens de tokens e configuracao - **Transcricoes** -- Transcricoes de sessao individuais armazenadas como arquivos `.jsonl` - **Recuperacao** -- Sessoes sobrevivem a reinicializacoes do Gateway sem perda de dados ### Limpeza - Sessoes nao acessadas por um periodo configuravel (padrao 30 dias) sao elegiveis para limpeza - Gestao manual de sessoes esta disponivel pela UI ou API - Transcricoes compactadas sao arquivadas mas podem ser revisadas