Memória Honcho

O Honcho é um backend de memória nativo de IA que acrescenta raciocínio dialético e modelagem profunda do usuário em cima do sistema de memória embutido do Hermes. Em vez de um armazenamento simples de chave-valor, o Honcho mantém um modelo vivo de quem é o usuário — preferências, estilo de comunicação, objetivos e padrões — raciocinando sobre as conversas depois que elas acontecem.

O Honcho é um plugin de provedor de memória

O Honcho está integrado ao sistema de provedores de memória. Todos os recursos abaixo ficam disponíveis pela interface unificada de provedor de memória.

O que o Honcho acrescenta

Recurso	Memória embutida	Honcho
Persistência entre sessões	✔ Arquivos MEMORY.md/USER.md	✔ No servidor, com API
Perfil do usuário	✔ Curadoria manual do agente	✔ Raciocínio dialético automático
Resumo da sessão	—	✔ Injeção de contexto no escopo da sessão
Isolamento entre vários agentes	—	✔ Perfil separado por peer
Modos de observação	—	✔ Observação unificada ou direcional
Conclusões (insights derivados)	—	✔ Raciocínio sobre padrões no servidor
Busca em todo o histórico	✔ Busca FTS5 nas sessões	✔ Busca semântica sobre conclusões

Raciocínio dialético: depois de cada turno de conversa (limitado por dialecticCadence), o Honcho analisa a troca e deriva insights sobre as preferências, os hábitos e os objetivos do usuário. Eles se acumulam com o tempo e dão ao agente um entendimento cada vez mais profundo, que vai além do que o usuário disse explicitamente. A dialética aceita profundidade de várias passadas (1–3) com seleção automática de prompt frio/quente — consultas de partida a frio focam em fatos gerais sobre o usuário, enquanto consultas quentes priorizam o contexto da sessão.

Contexto no escopo da sessão: o contexto base agora inclui o resumo da sessão junto com a representação do usuário e o cartão do peer. Isso dá ao agente consciência do que já foi discutido na sessão atual, reduzindo repetição e permitindo continuidade.

Perfis para vários agentes: quando várias instâncias do Hermes falam com o mesmo usuário (por exemplo, um assistente de programação e um assistente pessoal), o Honcho mantém perfis de "peer" separados. Cada peer enxerga só as próprias observações e conclusões, o que evita contaminação cruzada de contexto.

Instalação

hermes memory setup    # escolha "honcho" na lista de provedores

Ou configure na mão:

# ~/.hermes/config.yaml
memory:
  provider: honcho

echo 'HONCHO_API_KEY=***' >> ~/.hermes/.env

Pegue uma chave de API em honcho.dev.

Arquitetura

Injeção de contexto em duas camadas

A cada turno (nos modos hybrid ou context), o Honcho monta duas camadas de contexto injetadas no prompt de sistema:

1. Contexto base — resumo da sessão, representação do usuário, cartão do peer do usuário, auto-representação da IA e cartão de identidade da IA. Atualizado conforme contextCadence. É a camada do "quem é este usuário".
2. Suplemento dialético — raciocínio sintetizado por LLM sobre o estado e as necessidades atuais do usuário. Atualizado conforme dialecticCadence. É a camada do "o que importa agora".

As duas camadas são concatenadas e truncadas para o orçamento de contextTokens (se definido).

Seleção de prompt frio/quente

A dialética escolhe automaticamente entre duas estratégias de prompt:

• Partida a frio (ainda não há contexto base): consulta geral — "Quem é esta pessoa? Quais são suas preferências, objetivos e estilo de trabalho?"
• Sessão quente (já existe contexto base): consulta no escopo da sessão — "Dado o que já foi discutido nesta sessão, qual contexto sobre este usuário é mais relevante?"

Isso acontece automaticamente, conforme o contexto base já tenha sido preenchido ou não.

Três botões de configuração ortogonais

Custo e profundidade são controlados por três botões independentes:

Botão	Controla	Padrão
contextCadence	Turnos entre chamadas à API context() (atualização da camada base)	1
dialecticCadence	Turnos entre chamadas de LLM peer.chat() (atualização da camada dialética)	2 (recomendado 1–5)
dialecticDepth	Número de passadas de .chat() por invocação dialética (1–3)	1

Eles são ortogonais — dá para ter atualizações frequentes de contexto com dialética esporádica, ou dialética profunda de várias passadas em baixa frequência. Exemplo: contextCadence: 1, dialecticCadence: 5, dialecticDepth: 2 atualiza o contexto base a cada turno, roda a dialética a cada 5 turnos e cada execução dialética faz 2 passadas.

Profundidade dialética (várias passadas)

Quando dialecticDepth > 1, cada invocação dialética roda várias passadas de .chat():

• Passada 0: prompt frio ou quente (veja acima)
• Passada 1: autoauditoria — identifica lacunas na avaliação inicial e sintetiza evidências das sessões recentes
• Passada 2: reconciliação — procura contradições entre as passadas anteriores e produz uma síntese final

Cada passada usa um nível de raciocínio proporcional (passadas iniciais mais leves, nível base na passada principal). Sobrescreva os níveis por passada com dialecticDepthLevels — por exemplo, ["minimal", "medium", "high"] para uma execução de profundidade 3.

As passadas param cedo se a anterior devolveu sinal forte (saída longa e estruturada), então profundidade 3 nem sempre significa 3 chamadas de LLM.

Preaquecimento no início da sessão

Na inicialização da sessão, o Honcho dispara uma chamada dialética em segundo plano com a dialecticDepth configurada inteira e entrega o resultado direto para a montagem de contexto do turno 1. Um preaquecimento de passada única num peer frio costuma devolver pouca coisa — a profundidade de várias passadas roda o ciclo de auditoria e reconciliação antes de o usuário falar. Se o preaquecimento não chegar a tempo do turno 1, o turno 1 recorre a uma chamada síncrona com tempo limite.

Nível de raciocínio adaptado à consulta

A dialética injetada automaticamente escala o dialecticReasoningLevel conforme o tamanho da consulta: +1 nível a partir de 120 caracteres, +2 a partir de 400, limitado por reasoningLevelCap (padrão "high"). Desative com reasoningHeuristic: false para fixar toda chamada automática em dialecticReasoningLevel. Níveis disponíveis: minimal, low, medium, high, max.

Opções de configuração

O Honcho é configurado em ~/.honcho/config.json (global) ou $HERMES_HOME/honcho.json (local do perfil). O assistente de instalação cuida disso para você.

Honcho auto-hospedado com autenticação

Ao apontar o Hermes para um servidor Honcho auto-hospedado, o hermes honcho setup (e o hermes memory setup) pedem um JWT / token bearer local depois da URL base. Cole um JWT assinado com o AUTH_JWT_SECRET do servidor (a variável de ambiente do compose do Honcho) para habilitar acesso autenticado; deixe em branco para servidores rodando com AUTH_USE_AUTH=false. O token local é guardado no bloco do host (hosts.<host>.apiKey no honcho.json), separado de qualquer apiKey da nuvem, então você pode voltar a pergunta Cloud or local? para cloud depois sem perder nenhuma das duas credenciais.

Referência completa de configuração

Chave	Padrão	Descrição
contextTokens	null (sem limite)	Orçamento de tokens do contexto injetado automaticamente por turno. Defina um inteiro (por exemplo, 1200) para limitar. Trunca em fronteira de palavra
contextCadence	1	Mínimo de turnos entre chamadas à API context() (atualização da camada base)
dialecticCadence	2	Mínimo de turnos entre chamadas de LLM peer.chat() (camada dialética). Recomendado 1–5. No modo tools, irrelevante — o modelo chama explicitamente
dialecticDepth	1	Número de passadas de .chat() por invocação dialética. Limitado a 1–3
dialecticDepthLevels	null	Array opcional de níveis de raciocínio por passada, por exemplo ["minimal", "low", "medium"]. Sobrescreve os padrões proporcionais
dialecticReasoningLevel	'low'	Nível base de raciocínio: minimal, low, medium, high, max
dialecticDynamic	true	Quando true, o modelo pode sobrescrever o nível de raciocínio a cada chamada por parâmetro da ferramenta
dialecticMaxChars	600	Máximo de caracteres do resultado dialético injetado no prompt de sistema
recallMode	'hybrid'	hybrid (injeção automática + ferramentas), context (só injeção), tools (só ferramentas)
writeFrequency	'async'	Quando descarregar as mensagens: async (thread em segundo plano), turn (síncrono), session (lote no fim) ou um inteiro N
saveMessages	true	Se persiste as mensagens na API do Honcho
observationMode	'directional'	directional (tudo ligado) ou unified (pool compartilhado). Sobrescreva com o objeto observation para controle granular
messageMaxChars	25000	Máximo de caracteres por mensagem enviada via add_messages(). Divide em pedaços se exceder
dialecticMaxInputChars	10000	Máximo de caracteres da consulta dialética enviada a peer.chat()
sessionStrategy	'per-directory'	per-directory, per-repo, per-session ou global
pinUserPeer	false	Só no gateway. Quando true, todo usuário de plataforma colapsa em peerName
userPeerAliases	{}	Só no gateway. Mapa de IDs de runtime para peers ({"7654321": "alice"}). Muitos para um
runtimePeerPrefix	""	Só no gateway. Coloca IDs de runtime desconhecidos num namespace (telegram_7654321) quando nenhum alias casa

A estratégia de sessão controla como as sessões do Honcho se mapeiam ao seu trabalho:

• per-session — cada execução do hermes ganha uma sessão nova. Começos limpos, memória via ferramentas. Recomendado para quem está começando.
• per-directory — uma sessão do Honcho por diretório de trabalho. O contexto se acumula entre execuções.
• per-repo — uma sessão por repositório git.
• global — uma única sessão para todos os diretórios.

O modo de recuperação controla como a memória entra nas conversas:

• hybrid — contexto injetado automaticamente no prompt de sistema E ferramentas disponíveis (o modelo decide quando consultar).
• context — só injeção automática, ferramentas escondidas.
• tools — só ferramentas, sem injeção automática. O agente precisa chamar honcho_reasoning, honcho_search etc. explicitamente.

Ajustes por modo de recuperação:

Ajuste	hybrid	context	tools
writeFrequency	descarrega mensagens	descarrega mensagens	descarrega mensagens
contextCadence	limita a atualização do contexto base	limita a atualização do contexto base	irrelevante — não há injeção
dialecticCadence	limita as chamadas automáticas de LLM	limita as chamadas automáticas de LLM	irrelevante — o modelo chama explicitamente
dialecticDepth	várias passadas por invocação	várias passadas por invocação	irrelevante — o modelo chama explicitamente
contextTokens	limita a injeção	limita a injeção	irrelevante — não há injeção
dialecticDynamic	permite o modelo sobrescrever	N/A (sem ferramentas)	permite o modelo sobrescrever

No modo tools, o modelo tem controle total — ele chama honcho_reasoning quando quiser, no reasoning_level que escolher. Os ajustes de cadência e de orçamento só valem nos modos com injeção automática (hybrid e context).

Mapeamento de identidade no gateway

Estes ajustes só importam quando você roda o gateway do Hermes — o único ponto de entrada em que os usuários chegam com IDs de runtime nativos da plataforma (UID do Telegram, snowflake do Discord, usuário do Slack). Sessões de CLI, TUI e desktop não têm ID de runtime e sempre resolvem para peerName, então fora do gateway estas chaves não fazem nada.

O assistente de instalação detecta se há uma plataforma de gateway conectada e pula esta etapa inteira se não houver. Quando ela roda, faz uma pergunta — quem fala com este gateway? — e deriva as chaves:

Resposta	Resultado
só eu	pinUserPeer: true — todo usuário de gateway que não seja agente colapsa no seu peer. A fixação vence todos os aliases, então escolha isso só quando nenhuma identidade do lado do usuário precisar de peer próprio. Se agentes distintos chegam ao gateway e cada um precisa de um peer distinto, não fixe — deixe pinUserPeer: false e mapeie-os por userPeerAliases (o editor [e])
eu + outras pessoas (pool)	pinUserPeer: false + userPeerAliases mapeando os seus IDs de runtime para peerName — você fica no seu histórico compartilhado, os outros ganham peers próprios
só outras pessoas	pinUserPeer: false, runtimePeerPrefix opcional — cada usuário ganha o próprio peer

Escolha [e] na pergunta para definir as três chaves diretamente.

O resolvedor tenta as chaves de cima para baixo, e o primeiro acerto vence: pinUserPeer → userPeerAliases[id] → runtimePeerPrefix + id → ID de runtime cru → peerName → sessão como último recurso.

Desfixar deixa a memória do pool órfã

Virar o pinUserPeer de true para false não migra dados — a memória acumulada sob peerName fica lá, e os usuários da plataforma resolvem para peers novos e vazios. Para manter a sua continuidade, escolha o caminho do pool, para que os seus IDs de runtime voltem por alias a peerName. O assistente sugere isso sozinho quando detecta a transição.

Chave descontinuada

pinPeerName é um alias antigo de pinUserPeer — ainda é lido por compatibilidade (pinUserPeer vence onde os dois estão definidos), mas nunca é escrito. Rodar a instalação de novo migra para a chave canônica.

Observação (direcional x unificada)

O Honcho modela uma conversa como peers trocando mensagens. Cada peer tem dois interruptores de observação que mapeiam 1:1 para o SessionPeerConfig do Honcho:

Interruptor	Efeito
observeMe	O Honcho constrói uma representação deste peer a partir das mensagens dele
observeOthers	Este peer observa as mensagens do outro peer (alimenta o raciocínio entre peers)

Dois peers × dois interruptores = quatro flags. observationMode é um preset de atalho:

Preset	Flags do usuário	Flags da IA	Semântica
"directional" (padrão)	me: on, others: on	me: on, others: on	Observação mútua completa. Habilita a dialética entre peers — "o que a IA sabe sobre o usuário, com base no que o usuário disse e no que a IA respondeu".
"unified"	me: on, others: off	me: off, others: on	Semântica de pool compartilhado — a IA observa só as mensagens do usuário, e o peer do usuário só se automodela. Pool com um único observador.

Sobrescreva o preset com um bloco observation explícito para controle por peer:

"observation": {
  "user": { "observeMe": true,  "observeOthers": true },
  "ai":   { "observeMe": true,  "observeOthers": false }
}

Padrões comuns:

Intenção	Configuração
Observação completa (maioria dos usuários)	"observationMode": "directional"
A IA não deve remodelar o usuário a partir das próprias respostas	"ai": {"observeMe": true, "observeOthers": false}
Persona forte que o peer da IA não deve atualizar por autoobservação	"ai": {"observeMe": false, "observeOthers": true}

Os interruptores do lado do servidor definidos pelo painel do Honcho vencem os padrões locais — o Hermes sincroniza de volta na inicialização da sessão.

Ferramentas

Quando o Honcho está ativo como provedor de memória, cinco ferramentas ficam disponíveis:

Ferramenta	Para que serve
honcho_profile	Lê ou atualiza o cartão do peer — passe card (lista de fatos) para atualizar, omita para ler
honcho_search	Busca semântica sobre o contexto — trechos crus, sem síntese por LLM
honcho_context	Contexto completo da sessão — resumo, representação, cartão e mensagens recentes
honcho_reasoning	Resposta sintetizada pela LLM do Honcho — passe reasoning_level (minimal/low/medium/high/max) para controlar a profundidade
honcho_conclude	Cria ou apaga conclusões — passe conclusion para criar, delete_id para remover (só PII)

Comandos da CLI

O subcomando hermes honcho só é registrado quando o Honcho é o provedor de memória ativo (memory.provider: honcho no config.yaml). Numa instalação nova, configure o Honcho direto com hermes memory setup honcho (ou rode hermes memory setup e escolha ele na lista); o subcomando hermes honcho aparece na invocação seguinte.

hermes memory setup honcho    # Configura o Honcho direto (funciona antes da ativação)
hermes honcho status          # Estado da conexão, configuração e ajustes principais
hermes honcho setup           # Redireciona para `hermes memory setup` (alias pós-ativação)
hermes honcho strategy        # Mostra ou define a estratégia de sessão (per-session/per-directory/per-repo/global)
hermes honcho peer            # Mostra ou atualiza os nomes de peer + o nível de raciocínio dialético
hermes honcho mode            # Mostra ou define o modo de recuperação (hybrid/context/tools)
hermes honcho tokens          # Mostra ou define o orçamento de tokens de contexto e dialética
hermes honcho identity        # Semeia ou mostra a identidade Honcho do peer da IA
hermes honcho sync            # Sincroniza a configuração do Honcho com todos os perfis existentes
hermes honcho peers           # Mostra as identidades de peer em todos os perfis
hermes honcho sessions        # Lista os mapeamentos de sessão Honcho conhecidos
hermes honcho map             # Mapeia o diretório atual para um nome de sessão do Honcho
hermes honcho enable          # Habilita o Honcho no perfil ativo
hermes honcho disable         # Desabilita o Honcho no perfil ativo
hermes honcho migrate         # Guia de migração passo a passo a partir do openclaw-honcho

Migrar do hermes honcho

Se você já usava o hermes honcho setup avulso:

1. Sua configuração atual (honcho.json ou ~/.honcho/config.json) é preservada
2. Seus dados no servidor (memórias, conclusões, perfis de usuário) ficam intactos
3. Defina memory.provider: honcho no config.yaml para reativar

Não precisa entrar de novo nem refazer a configuração. Rode hermes memory setup e escolha "honcho" — o assistente detecta a configuração que você já tem.

Documentação completa

Veja Provedores de memória — Honcho para a referência completa.

---