Lições Práticas da Construção de um Agente Companheiro de IA Local Permanente

Configuração e Arquitetura

Um desenvolvedor tem executado um agente de IA auto-hospedado em um Mac mini M4 por vários meses. A configuração usa um runtime Rust com qwen2.5:14b no Ollama para inferência local rápida. O sistema implementa uma escada de modelos que escala para modelos na nuvem quando as tarefas exigem mais capacidade. A memória é gerenciada com SQLite e embeddings locais usando nomic-embed-text para recuperação semântica entre sessões. O agente funciona 24/7 via launchd e executa várias tarefas incluindo monitoramento de um bot de trading, verificação de e-mail, implantação de sites e delegação de trabalho pesado de implementação para o Claude Code através de um executor de tarefas.

Principais Lições Aprendidas

A arquitetura de memória é tudo: O desenvolvedor descobriu que a recuperação híbrida combinando busca por palavras-chave BM25 com similaridade vetorial, ponderada e mesclada, foi um avanço. Um modelo de 14B com boa recuperação de memória supera um modelo de 70B que começa cada conversa do zero.

O imposto do prompt do sistema é real: Os arquivos de identidade iniciais começaram com ~10K tokens, mas foram reduzidos para ~2.800 tokens cortando qualquer coisa que o agente pudesse consultar sob demanda. A regra: se o agente precisa de algo ocasionalmente, coloque na memória; se precisa a cada mensagem, coloque no prompt do sistema.

Embeddings locais mudaram a economia: Usar nomic-embed-text no Ollama junto com o modelo de conversa torna cada operação de armazenamento e recuperação de memória gratuita, eliminando custos que antes acumulavam de solicitações de embedding da OpenAI.

A escada de modelos importa mais que o modelo padrão: O agente usa por padrão qwen local para conversação (grátis, rápido) mas pode escalar para Minimax, Kimi, Haiku, Sonnet ou Opus dependendo dos requisitos da tarefa. O insight principal: deixe humanos alternarem modelos manualmente com comandos como /model sonnet para tarefas de raciocínio e /model qwen para bate-papo, em vez de tentar detectar automaticamente.

Limites de iteração de ferramentas precisam de margem: Começar com 10 chamadas máximas de ferramentas por mensagem mostrou-se insuficiente. Tarefas simples consomem 3-5 chamadas, enquanto tarefas complexas precisam de 15-20. A configuração atual usa 25 chamadas de ferramentas com um limite de taxa de 200 ações/hora como rede de segurança.

O bug mais difícil foi memória entre sessões: Memórias armazenadas explicitamente via uma ferramenta de armazenamento inicialmente não tinham session_id, e consultas de recuperação filtravam pelo session_id atual. Isso tornava fatos memorizados deliberadamente invisíveis em sessões futuras. A correção foi adicionar OR session_id IS NULL à consulta SQL.