🎯 Estratégias de Uso

O OpenHuman fala com pessoas através de provedores externos (Slack, Discord, WhatsApp, Telegram, iMessage, Gmail, Google Meet, LinkedIn). Cada provedor é uma conta de webview hospedada dentro da própria desktop app.

Saber quais canais existem e como eles se autenticam é o ponto de partida para qualquer fluxo de comunicação. Não há "adapter remoto" — tudo roda na sua máquina.

Webview account, CEF, provedor migrado vs legacy, OAuth vs cookie-auth.

Você faz login dentro da janela embarcada exatamente como faria no navegador. A sessão (cookies, storage) fica isolada por provedor em um perfil CEF persistente.

Esse modelo elimina API tokens manuais e funciona com provedores que não têm API pública (web.whatsapp.com, web.telegram.org).

CEF profile, perfil isolado por conta, persistência de sessão, re-login só quando o provedor expira.

Provedores migrados (whatsapp, telegram, slack, discord) são lidos via Chrome DevTools Protocol — Network.*, Page.*, Emulation.* — sem injetar nenhum JavaScript dentro da página de terceiro.

Reduz superfície de ataque, evita quebra silenciosa quando o provedor atualiza, e mantém o código host fora de origens que não controlamos.

CDP, scanner por provedor (src/*_scanner/), regra "nenhum init script novo", scraping observável a partir do Rust.

Antes da migração CDP, alguns provedores usavam um pequeno runtime.js injetado para fazer scraping. Esses ficaram "grandfathered" — funcionam, mas não devem crescer.

Você vai encontrar código legacy ao depurar Gmail/LinkedIn. Saber o limite ("não adicione JS novo") evita PRs rejeitados.

Init script, recipe files, política "shrink, not grow", risco de injetar em origem de terceiro.

Mensagens entram via scanner CDP → domínio channels → event bus (DomainEvent::Channel) → ChannelInboundSubscriber → memória / agente / regras.

Sem entender o pipeline você fica adivinhando onde uma mensagem "se perdeu". Saber o caminho permite logar no ponto certo.

Event bus tipado, publish_global, subscriber por domínio, ingest fan-out.

Falhas comuns: cookies expirados, 2FA novo, QR do WhatsApp expirou, perfil CEF corrompido. Diagnóstico vai do log do scanner até reset do perfil.

A maior parte do "OpenHuman não me responde no Slack" é pareamento, não bug no agente.

Logs com prefixo [scanner]/[channels], reset de perfil, re-login forçado, status no painel de Channels.

A memória é um pipeline: ingest → tokenjuice → tree summarizer → embeddings → store. Vários domínios Rust (memory, memory_tree, memory_store, memory_archivist, embeddings) cooperam.

Ver as etapas torna óbvio onde otimizar custo (TokenJuice) e onde melhorar recall (embeddings).

Memory tree, chunks, sources, fila de processamento.

Loop de fundo (heartbeat) que avalia tasks de sistema e usuário a cada tick (5+ min). Cada tarefa recebe decisão Skip/Act/Escalate via modelo local.

É o que faz o OpenHuman se mexer sem você. Saber como funciona separa "tarefa esquecida" de "tarefa decidiu não agir".

Heartbeat, system tasks, user tasks, write-intent vs read-only, approval gate.

Estrutura hierárquica de resumos: chunks folha → resumos intermediários → resumo de fonte → resumo global. Permite recall barato no nível certo de granularidade.

Sem essa árvore, recuperar contexto vira "dump tudo no prompt". Com ela, o agente puxa só o galho que importa.

Chunk, summary node, top-down recall, entity index.

Cada chunk vira um vetor. memory.recall busca por similaridade, memory.search faz keyword. Ambos expostos via MCP e JSON-RPC.

Saber quando usar recall (conceito difuso) vs search (termo exato) muda a qualidade do contexto recuperado.

Vetor, similaridade cosseno, top-k, recall vs search.

Threads são a unidade canônica de conversa no OpenHuman pós-unificação (`/chat`). Conversations legadas foram absorvidas. Cada thread tem mensagens, participantes e contexto vinculado.

Entender o modelo evita confusão entre "rota antiga" e "rota nova" e ajuda a depurar quando uma mensagem cai na thread errada.

Thread store, participantes, canal de origem, unificação `/chat`.

Overlay de regras JSON (builtin → user → project) que comprime saída verbosa de ferramentas (git, cargo, emails) antes de entrar no contexto do LLM.

É o que faz processar 6 meses de e-mail custar dólares em vez de centenas. Saber escrever uma regra é alto ROI.

3 camadas, classify→match→reduce, regra JSON, debug com RUST_LOG.

O runtime QuickJS que executava skills foi removido. Hoje src/openhuman/skills/ guarda só metadados — descobrir, instalar, parsear e injetar referências.

Evita expectativa errada de "vou rodar meu JS dentro do core". O caminho atual é tools nativos + MCP.

Metadata-only, ops_install, ops_discover, injeção via prompt.

Catálogo dinâmico de ferramentas disponíveis para o agente, montado a partir do controller registry, MCP, e integrações ativas. Documentado em gitbooks/developing/architecture/agent-harness.md.

Entender o harness mostra por que uma tool aparece (ou não) para o agente em determinado contexto.

Tool registry, allowed agents, schema input/output, tags.

openhuman-core mcp roda o core como servidor MCP read-only — expõe memory.search, memory.recall, tree.browse, etc. via stdin/stdout.

Permite usar a memória do OpenHuman dentro de Claude Desktop, Cursor, Zed — sem dependência de cloud.

stdio, clientInfo provenance, read gate, ferramentas curadas.

Cada domínio Rust registra controllers (em schemas.rs) e cada controller pode virar tool exposta no harness com tool_id estável.

Esse é o caminho oficial para estender o agente. Você escreve Rust, ganha CLI + JSON-RPC + tool de uma vez.

Controller registry, ControllerSchema, tool_registry_list, naming openhuman.<ns>_<fn>.

Os domínios cron e webhooks publicam DomainEvent no event bus. Subscribers (CronDeliverySubscriber, WebhookRequestSubscriber) disparam fluxos do agente.

É a maneira nativa de fazer automação recorrente ("toda segunda às 8h…") ou reativa ("quando o Linear criar issue…").

Cron schedule, webhook trigger, settings page /settings/webhooks-triggers, event bus.

Combinações comuns: cron diário + recall de memória + post no Slack; webhook do GitHub + summarizer + e-mail; subconscious task + tool nativa de busca.

Padrões prontos cortam horas. Você adapta em vez de partir do zero.

Receita = trigger + tool + memória + canal. Compor é a competência.