nanobot — Documentacao Tecnica

Importante: a fila e in-memory

A fila do MessageBus e uma asyncio.Queue — ela existe apenas na memoria RAM. Se o processo morrer, tudo que esta na fila desaparece. Quando a fila enche (1000 mensagens), as novas sao descartadas (dropped), nao salvas. Nao ha persistencia.

A fila e o "corredor" entre channels e agent. Mensagens passam por ela rapidamente. Se estiver acumulando 1000, significa que o agent esta muito lento ou parado.

Por que 1000 no disco mas so 50 para o LLM?

O arquivo .jsonl guarda 1000 mensagens como backup completo da conversa. Mas o LLM recebe apenas as ultimas 50 porque: (a) modelos tem limite de tokens, (b) mensagens muito antigas raramente sao relevantes, e (c) menos mensagens = resposta mais rapida e mais barata.

Vantagem do Token Bucket

Com uma janela fixa (ex: "10 por minuto"), um usuario pode mandar 10 mensagens no segundo 59 e mais 10 no segundo 61 — totalizando 20 em 2 segundos. O Token Bucket evita isso porque as fichas gastam e demoram para reabastecer, distribuindo o uso de forma mais uniforme ao longo do tempo.

Resumo dos limites no caminho

A fila e unica para todos os canais

Nao importa se a mensagem veio do Telegram, Discord, WhatsApp ou Feishu — todas vao para a mesma fila (inbound). O MessageBus tem exatamente duas filas:

Funciona como um funil: varios canais despejam mensagens na mesma entrada, e o agente puxa uma por uma.

O processamento e sequencial (uma mensagem por vez)

O AgentLoop funciona com um loop simples:

while self._running:
    msg = await bus.consume_inbound()       # 1. Pega UMA mensagem da fila
    response = await _process_message(msg)  # 2. Processa ATE O FIM (inclui tools)
    await bus.publish_outbound(response)    # 3. Coloca resposta na fila de saida
    # so agora volta ao passo 1

Enquanto o agente esta processando a mensagem A (chamando LLM, executando tools, esperando APIs), as mensagens B, C e D ficam esperando na fila. Nao ha processamento paralelo de mensagens.

Consequencias praticas

Por que nao e paralelo?

O nanobot e um assistente pessoal, projetado para poucos usuarios (normalmente so voce). Processamento paralelo traria complexidade desnecessaria:

• Cada sessao compartilha o mesmo workspace — tools paralelos poderiam conflitar (dois escrevendo no mesmo arquivo)
• O contexto do LLM depende do historico — processar em paralelo poderia misturar conversas
• O rate limiter e por sessao — concorrencia exigiria locks extras
• Para 1-5 usuarios, a fila sequencial funciona bem. Cada mensagem leva segundos, nao minutos

A unica forma de paralelismo real e o subagente (spawn), que roda em background com seu proprio loop de tools (max 5 simultaneos).

Como funciona a escrita atomica

Para evitar corrupcao de dados (ex: queda de energia no meio de uma escrita), o nanobot usa o padrao temp + rename:

1. Escreve o conteudo em um arquivo temporario (.tmp)
2. Faz fsync() para garantir que esta no disco
3. Renomeia o .tmp para o arquivo final (operacao atomica no filesystem)

Se der erro no passo 1 ou 2, o arquivo original nao e afetado.
O rename (passo 3) e atomico no Linux/macOS — ou o arquivo
antigo existe ou o novo, nunca um estado intermediario.

Isso e usado em: sessoes (.jsonl), config, cron jobs, e qualquer escrita do tool write_file.

Formato JSONL

Cada arquivo de sessao usa o formato JSONL (JSON Lines) — uma linha JSON por mensagem. Isso permite append eficiente (adicionar sem reescrever o arquivo todo) e leitura linha por linha (sem carregar tudo na memoria).

{"_type":"metadata","created_at":"2026-02-10T05:30:00","session_key":"telegram:123456789"}
{"role":"user","content":"Oi!","timestamp":"2026-02-10T05:31:00"}
{"role":"assistant","content":"Ola! Como posso ajudar?","timestamp":"2026-02-10T05:31:05"}
{"role":"user","content":"Qual o clima em SP?","timestamp":"2026-02-10T05:32:00"}
{"role":"assistant","content":"28C, parcialmente nublado","timestamp":"2026-02-10T05:32:15"}

• Max 1000 mensagens por arquivo
• Max 100KB por mensagem individual
• Escrita atomica (temp + rename)
• Auto-deletado apos 30 dias sem acesso
• 100 sessoes em cache LRU na memoria

Schema Pydantic

O arquivo de configuracao e validado pelo Pydantic v2 (config/schema.py). Se tiver campo errado, tipo errado, ou valor invalido, o nanobot recusa iniciar e mostra o erro exato.

{
  "model": "openrouter/qwen/qwen3-coder-next",
  "channels": {
    "telegram": {
      "token": "BOT_TOKEN_AQUI",
      "allowFrom": ["123456789"]
    }
  },
  "restrictToWorkspace": true
}

Arquivos de bootstrap

Os arquivos na raiz do workspace sao os "bootstrap files" — carregados automaticamente no contexto do agente a cada mensagem. Sao eles que definem a personalidade, conhecimento e comportamento:

Limite: cada arquivo de bootstrap tem max 500KB. Arquivos maiores sao ignorados.

Tarefas agendadas

Os jobs do cron sao salvos em jobs.json e persistidos no disco. O servico de cron (cron/service.py, 346 linhas) verifica a cada 10-30 segundos se ha tarefas para executar. Suporta tres tipos: every (intervalo), cron (expressao cron), e at (data/hora unica).

Log de operacao

Registra eventos do gateway: startup, shutdown, erros de channels, erros de provider, rate limits ativados, etc. Util para debug. Nao tem rotacao automatica — o usuario precisa gerenciar o tamanho.

Memoria persistente do agente

O agente pode gravar informacoes que quer lembrar entre sessoes:

• MEMORY.md — Memoria permanente. O agente pode ler e editar livremente. Ideal para informacoes que nunca mudam (nome do usuario, preferencias, etc.)
• YYYY-MM-DD.md — Notas diarias. O contexto builder inclui automaticamente as notas dos ultimos 7 dias. Ideal para anotacoes temporarias, TODOs, lembretes.

O agente acessa a memoria via tools (read_file, write_file). Na proxima conversa, o context builder carrega a memoria automaticamente no prompt do sistema.

Por que so arquivos?

O nanobot e um assistente pessoal, nao um servidor de producao com milhares de usuarios. Para um unico usuario (ou um punhado), arquivos no disco sao:

• Simples: nao precisa instalar/configurar nada
• Transparentes: voce pode abrir e ler qualquer arquivo num editor de texto
• Portaveis: copiar ~/.nanobot/ para outra maquina e voce tem tudo
• Confiaveis: escrita atomica previne corrupcao
• Leves: sem dependencia externa, sem processo separado