MÓDULO 3.1

💬 Comandos e conversa

Tudo que o bot entende: os comandos de barra por grupo, a fila que executa os agentes, tarefas com lembrete, o cron que roda sozinho e o jeito certo de pedir trabalho a um agente e acompanhar até o resultado.

6
Tópicos
75
Minutos
Prático
Nível
Mão na massa
Tipo
Progresso do módulo 3.1 0%
0 de 0
1

🗺️ Mapa dos comandos por grupo

Toda mensagem que começa com / é comando. O orquestrador responde na hora, sem roteador, sem modelo, sem custo, e o texto nunca vira memória. O que não começa com / é conversa: passa pelo roteador em llama3.2 e vira resposta direta no Ollama ou job de agente. Os comandos se organizam em sete grupos, e é assim que o /ajuda os mostra.

/comando responde na hora, custo 0 fila: /status [id] · /cancelar · /prioridade custo: /usage saúde: /health · /ollama status|preflight|descarregar memória: /memoria … · /consolidar · /fontes tarefas: /tarefa add|lista|feita · /daily cron: /cron lista|on|off controle: /parar · /retomar · /fila · /personality · /context · /novo · /compress

Legenda: o caminho da esquerda para a direita é sempre o mesmo. O grupo só diz o que você está operando. Controle da conversa é a Trilha 4; os outros seis são deste módulo e do próximo.

GrupoComandos (sintaxe exata)O que devolve
Fila/status [id] · /cancelar <id> · /prioridade <id> <n>rodando/pendente por lane; detalhe de um job com resultado ou erro
Custo/usagehoje, semana, mês; por tier e por agente (30 dias); orçamento
Saúde/health · /ollama status|preflight <m>|descarregar <m>Ollama, RAM/swap, RSS, fila, heartbeat, canais
Memória/memoria lista|buscar <t>|salvar <t>|esquecer <id>|propostas|aprovar <id>|descartar <id> · /consolidar · /fontescérebro, vault e conectores (módulo 3.2)
Tarefas/tarefa add [quando] <texto> · /tarefa lista · /tarefa feita <id> · /dailysuas tarefas, lembretes, resumo do dia
Cron/cron lista|on <nome>|off <nome>tarefas agendadas, ativo/inativo, próxima execução
Controle/parar · /retomar · /fila · /personality · /context · /novo · /compressinterruptores, modo de fila, persona, custo do prompt, sessão
Utilidade/chatid · /versao · /ajuda · /ajuda <comando>id do chat e canal; versão e instância; lista e detalhe

Dica prática

Na dúvida de sintaxe, não pergunte em prosa (isso vira rota de conversa e gasta o roteador). Mande /ajuda. Para os comandos de controle (/parar, /retomar, /fila, /personality, /context) existe detalhe: /ajuda parar, /ajuda fila. Para os demais, /ajuda <x> responde que não há detalhe e lista os que têm.

2

📋 Fila na prática

Tudo que demora vira job numa fila em SQLite, separada em cinco lanes com concorrência própria. Jobs nunca são apagados: são o histórico. Quando um pedido "não responde", quase sempre ele está enfileirado atrás de outro na lane agente, que roda um por vez porque cada claude -p consome cerca de 500 MB de RAM.

LaneConcorrênciaO que roda nela
chat2resposta direta que chegou durante outra em curso
agente1claude -p (lead e especialistas)
ollama1consolidação, ingestão, embeddings
cron1tarefas agendadas
io4rede/arquivo, junção de especialistas, probe do doctor

Legenda: a coluna do meio é o que explica a espera. Duas respostas diretas em paralelo cabem; dois agentes, não.

/status (recriação ilustrativa, não é captura real)
Fila chat: 0 rodando · 0 na fila agente: 1 rodando · 2 na fila ollama: 0 rodando · 0 na fila cron: 0 rodando · 0 na fila io: 0 rodando · 0 na fila Recentes #131 agente/agente:lead running #130 cron/lembretes done #129 agente/agente:research queued

Legenda: a primeira parte é o retrato por lane; a segunda, os 5 jobs mais recentes com #id lane/tarefa status. O #id é o que você usa em /status, /cancelar e /prioridade.

✓ O que FAZER

  • /status antes de mandar o mesmo pedido de novo: ele pode já estar na fila.
  • /status <id> para ler o resultado (até 1.500 caracteres) ou o erro (até 300) de um job.
  • /prioridade <id> <n> para furar fila em algo que ainda está queued.
  • /cancelar <id> no que ficou obsoleto; o cancelamento é sem corrida.

✗ O que NÃO fazer

  • Reiniciar o serviço porque "travou": o drain gracioso espera até 110 s e o job volta na fila do mesmo jeito.
  • Tentar /prioridade em job que já está running ou done: só queued muda de prioridade.
  • Esperar que /cancelar mate o processo na hora: um claude -p em execução morre na batida seguinte do worker, até 30 s.
  • Procurar o job no dashboard para agir: quem opera a fila são os comandos de barra (/status, /cancelar, /prioridade).

Copiar e rodar: ler a fila e um job

Objetivo: ver o que está rodando e abrir o detalhe de um job específico, no chat do Telegram com o bot.

/status
/status <id-do-job>
/prioridade <id-do-job> 10
/cancelar <id-do-job>

Como verificar: a resposta do primeiro comando lista as cinco lanes e os recentes; o segundo devolve status, tentativas x/y, duração e o resultado se estiver done. Se o id não existir, o bot responde "Job #N não existe.". Troque <id-do-job> por um número da lista de recentes.

3

⏰ Tarefas, lembretes e /daily

Tarefas aqui são suas, não do bot: ficam na tabela tarefas_usuario, por chat. /tarefa add [quando] <texto> cria; se o começo do texto for uma data que o bot reconhece, ela vira lembrete e o resto vira o texto da tarefa. Sem data reconhecida, a frase inteira é a tarefa e não há lembrete.

Formato de quandoExemplos aceitosComo o bot interpreta
Relativoem 30 min · em 2h · em 3 diasagora + intervalo (min, m, h, hora(s), d, dia(s))
Dia + horahoje 18:30 · amanhã 9h · sex 10h · seg 8:15hoje, amanhã ou o próximo dia da semana (dom, seg, ter, qua, qui, sex, sáb), na hora dada
Data + hora15/09 14:30 · 15/09 14hdia/mês deste ano; se já passou, ano que vem
Nenhum/tarefa add pagar o domíniotarefa sem lembrete; aparece só em /tarefa lista e no /daily

Legenda: a data precisa vir no início, logo depois de add. "pagar o domínio amanhã 9h" não vira lembrete; "amanhã 9h pagar o domínio" vira. O fuso é o do processo (a máquina).

1

Você anota

/tarefa add amanhã 9h ligar pro contador. O bot confirma com o id da tarefa e a data do lembrete em pt-BR.

2

O cron lembretes cobra

Roda a cada minuto (* * * * *) na lane cron, em sessão isolada. Quando a hora chega, a mensagem vem no Telegram. Se você mandar /cron off lembretes, nenhum lembrete dispara.

3

Você fecha

/tarefa feita <id> marca concluída (só pendente do seu chat). Ela sai da lista e entra na contagem "feitas nas últimas 24 h" do /daily.

4

Às 8h, o resumo

O cron daily-8h (0 8 * * *, sessão principal, só se houver ALLOWED_CHAT_ID) manda o mesmo que /daily: até 8 tarefas pendentes, feitas em 24 h, custo do dia, jobs pendentes, resumo do Ollama e os primeiros 500 caracteres do MEMORY.md.

Copiar e rodar: uma tarefa com lembrete

Objetivo: criar uma tarefa que o bot cobra daqui a poucos minutos, conferir a lista e fechar.

/tarefa add em 2 min <texto-da-sua-tarefa>
/tarefa lista
/tarefa feita <id-que-o-bot-devolveu>
/daily

Como verificar: a primeira resposta é "Tarefa #N criada · lembrete <data>". Em até 2 minutos (mais o tick do cron) chega a mensagem de lembrete. Depois de feita, ela some de /tarefa lista e "feitas nas últimas 24 h" sobe 1 no /daily. Se o lembrete não vier, /cron lista tem que mostrar lembretes com o círculo verde.

Dica prática

Tarefa e memória são coisas diferentes. "Lembra que eu prefiro reunião de manhã" é memória (cérebro, módulo 3.2). "Me lembra amanhã 9h de ligar" é tarefa. Uma frase enviada como conversa pode virar memória semântica por causa do "lembra", mas não cria lembrete: lembrete só com /tarefa add.

4

🔁 Cron: o que roda sozinho

Cron no v3 não é um processo à parte: cada ocorrência vira um job na fila com idem_key = nome@ocorrência. Se o serviço reiniciar no meio, a mesma ocorrência não dispara duas vezes. Cada cron declara a sessão: isolada (contexto limpo) ou principal (continua a conversa do chat, como o daily-8h). Os padrão são criados no boot, uma vez por nome; o que você desligar fica desligado.

NomeQuandoFazEstado inicial
lembretesa cada minutodispara os lembretes vencidos de /tarefaligado
indexar-memoriaa cada 15 mingera vetor bge-m3 das memórias sem vetorligado
ingestao-observadosa cada 30 minextrai fatos dos chats observados do Telegramligado
gmail-ingestaoa cada 2 hlê as últimas 3 h de e-mail em todas as contasdesligado até autenticar
agenda-ingestao7h05próximos 14 dias de todas as agendasdesligado até autenticar
decaimento3h30reduz salience por dia sem uso; apaga o que ficou abaixo de 0.05 sem acesso há 30 diasligado
consolidacao-noturna4hduplicatas, contradições, insights (módulo 3.2)ligado
backup-noturno4h15VACUUM INTO + age ou gzip, retenção 14, em store/backups/ligado
daily-8h8hmanda o /daily no chat permitido (sessão principal)ligado se há ALLOWED_CHAT_ID

Legenda: a ordem da madrugada importa: 3h30 decai, 4h consolida, 4h15 copia. O backup é sempre do estado já consolidado.

✓ O que FAZER

  • /cron lista de vez em quando: cada linha traz ativo (🟢/⚪), nome, expressão, tarefa e a próxima execução.
  • /cron on gmail-ingestao e /cron on agenda-ingestao só depois do auth de cada conta Google.
  • Se um cron falha 3 vezes em 1 h, o heartbeat alerta no Telegram: leia o /status <id> do job antes de mexer.

✗ O que NÃO fazer

  • Desligar indexar-memoria para "economizar": sem vetor, a busca por significado para de achar o que a palavra-chave não pega.
  • Ligar os crons do Google sem token: cada tick falharia, e o alerta de 3 falhas ia disparar.
  • Esperar que /cron on crie um cron novo: ele só liga um que existe. Cron novo é código, não comando.

Dica prática

O heartbeat (a cada 30 min) é o vigia do cron e da fila: recupera lease vencido, cancela zumbi (job rodando há mais de 2× o timeout de 20 min) e alerta 3 falhas da mesma tarefa em 1 h. Se /health mostrar heartbeat "nunca" ou com mais de 90 min, o GET /health deixa de responder ok e é hora de olhar o journalctl (Trilha 2).

5

🧩 Agentes, skills e sessão

Dois comandos mostram o que está instalado e dois controlam o quanto o bot "carrega" da conversa anterior. /agentes lista cada agente de agents/<id>/ com o modelo e a marca "só leitura" quando for especialista; /skills lista as skills de skills/, e as de skills/_rascunhos/ aparecem com 📝 na frente. Skills entram no prompt só pela metadata (nome e descrição), não pelo corpo: é assim que o prompt não incha.

/novo/compress
Sessão --resume do CLI (agente)apagaapaga
Histórico do chat no conversation_logapaga (o bot diz quantos turnos)mantém
Memórias (memories) e vaultmantémmantém
Próximo turnocomeça do zero, só com identidade, USER.md e memóriasessão nova de agente, mas a resposta direta ainda vê o histórico
Quando usarmudar totalmente de assunto; sessão contaminadao agente ficou lento ou "preso" no contexto antigo; quer poupar tokens

Legenda: nenhum dos dois toca a memória de longo prazo. O que se perde é conversa, não fato.

Novo aqui? Sessão retomada

Quando um agente roda, o claude -p abre uma sessão e o v3 guarda o id dela por chat. No pedido seguinte, o agente é retomado com --resume e "lembra" do que fez. Sessão com mais de 6 h não é retomada: o cache do provedor já expirou e não compensa. Trocar de personalidade (/personality) também apaga as sessões, senão o agente voltaria com a voz antiga.

Copiar e rodar: inventário e reset

Objetivo: ver quais agentes e skills o seu v3 tem, e limpar a sessão sem perder o histórico.

/agentes
/skills
/compress

Como verificar: /agentes devolve uma linha por agente no formato id (modelo, só leitura) seguido da descrição; no repo de hoje são comms, content, ops e research. /skills lista uma por linha, com 📝 nos rascunhos. /compress responde "Sessões limpas: N (histórico mantido; próximo turno começa sessão nova)".

6

🚀 Pedir trabalho a um agente

Você não escolhe a rota: o roteador escolhe. Pedido que precisa de ferramenta (arquivo, shell, repo, web, skill, calendário) vai para a rota agente. O bot responde na hora com um briefing curto: o nome do agente, o número do job, quantos estão na frente e o lembrete de que /status N acompanha. Depois o worker roda claude -p --output-format json com o prompt em camadas (identidade, agente, memória, skills, mensagem), e a resposta volta pelo bus ao mesmo chat, com o custo real registrado.

sua mensagemsem barra na frente roteadorllama3.2: rota agente job #N na filabriefing no chat claude -plane agente, 1 por vez respostano mesmo chat + custo especialista especialista só leitura, em paraleloo lead recebe as saídas

Legenda: o caminho de cima é o comum. O ramo ciano acontece quando o roteador marca consultar: até 2 especialistas só leitura (ex.: research) rodam antes e o lead escreve a resposta final. Só o lead escreve.

✓ Pedido que sai certo

  • Diz o que quer, onde (pasta, repo, arquivo) e como saber que está pronto.
  • Uma tarefa por mensagem. Duas tarefas viram dois jobs em sequência de qualquer jeito, e a segunda perde o contexto da primeira.
  • Nomeia a ferramenta quando importa ("usa a skill X", "no repo Y"): o roteador acerta o agente com mais facilidade.
  • Depois do briefing, espera. /status N quando quiser saber; o resultado chega sozinho.

✗ Pedido que vira job ruim

  • "Dá uma olhada nisso" sem dizer o quê nem onde: o agente gasta tokens descobrindo o que você quis.
  • Mandar a mesma coisa de novo porque demorou: no modo collect as duas juntam; nos outros modos vira segundo job.
  • Pedir mídia paga (HeyGen, render) esperando que rode: a identidade proíbe sem confirmação explícita no momento.
  • Esperar resposta de agente com /parar agentes ligado: o bot avisa que o agente está parado e responde só pelo modelo local.

Copiar e rodar: um pedido de agente de ponta a ponta

Objetivo: disparar um job de agente com um pedido bem formado, acompanhar pela fila e ler o resultado e o custo.

Lê o README.md do repo ~/projetos/<nome-do-seu-repo> e me devolve, em 5 linhas, o que o projeto faz e como se roda. Não altera nada.
/status <numero-do-job-que-veio-no-briefing>
/usage

Como verificar: a primeira resposta é o briefing com 🧠, o nome do agente e job #N. Enquanto roda, /status N mostra status: running; ao terminar, o resumo chega no chat e /status N passa a done com o texto. No /usage, o agente aparece em "Por agente (30 d)" com custo em US$. Se a saída do CLI não puder ser interpretada, o erro do job aponta o arquivo bruto em store/saidas/job-N.txt.

Dica prática

Toda resposta que sai passa pela guarda de exfiltração: token, chave de API, JWT e os valores das variáveis sensíveis do .env viram [REDIGIDO]. Se um agente "devolveu" uma chave e você vê [REDIGIDO], está funcionando. Não peça para o bot imprimir segredos; ele não vai, e é assim que deve ser.

Resumo do módulo

Comando começa com / - responde na hora, custo zero, sete grupos; /ajuda e /ajuda <comando>
Fila em cinco lanes - agente roda 1 por vez; /status, /status <id>, /cancelar, /prioridade só em queued
Tarefas suas - /tarefa add [quando] <texto>, data no início; cron lembretes cobra; /daily às 8h
Cron é job com idem_key - nunca dispara duas vezes; /cron lista|on|off; Google desligado até autenticar
/novo vs /compress - os dois apagam a sessão; só /novo apaga o histórico; memória fica
Pedido de agente - o quê, onde, critério de pronto; briefing com job #N; resultado no chat; custo no /usage

Próximo módulo:

3.2 - Cérebro e conectores: o que o bot guarda, como buscar e corrigir, e como ligar Gmail, agendas e grupos do Telegram à memória.