# Hermes

Conecte o Hermes Agent por meio de seu plug-in de memória nativo no PyPI com pontos de verificação de sessão, captura automática e memória de projeto durável.

- Canonical: https://docs.xmemo.dev/pt-br/docs/connect/hermes
- Locale: pt-BR
- Content-Locale: pt-BR
- Canonical-Content-Digest: bc9df4e1a62a317f42328c5fb35b354a1666ef85ea9f18ff6c96dbf5dccbdd9f
- Edition-Digest: 8c7843db0dd9976f3e27709c7f6a03e5ed71cb6bd6f32cbe2190e62301e52470
- Source-Revision: sha256:c1c2001f12dcea28dab430debe91620cc57ef3d7fced5162a27e2afa3fe87072

## Público-alvo e interface concreta

Este guia conecta o Hermes Agent à memória persistente do XMemo. O Hermes se integra por meio do pacote de plug-in de memória nativo e mantido hermes-xmemo (versão 1.1.3) no PyPI, vinculado ao repositório ativo yonro/hermes-xmemo-plugin @ 30fe1bc20a (https://github.com/yonro/hermes-xmemo-plugin/blob/30fe1bc20a/README.md). Observe que o repositório arquivado yonro/xmemo-hermes-plugin @ eb47797a08 é apenas uma referência de migração legada; todas as novas instalações usam o hermes-xmemo.

## Pré-requisitos

Certifique-se de que as seguintes dependências de tempo de execução e ferramentas estejam presentes antes de conectar:

- CLI e ambiente de execução do Hermes Agent instalados (Python 3.10+).
- Instalador de pacotes Python (pip).
- Conta válida do XMemo em https://xmemo.dev.
- Acesso de rede a https://xmemo.dev/mcp via HTTPS.

## Instalação

Instale o provedor XMemo para Hermes a partir do mercado oficial de plug-ins do Hermes. Se sua versão do Hermes não expuser o comando de mercado de plug-ins, use o fallback fixado do PyPI.

```bash
hermes plugins install xmemo

# Fallback for older Hermes versions
pip install hermes-xmemo
hermes memory setup xmemo
```

## Autorização e configuração de credenciais

Configure a autenticação usando uma variável de ambiente ou a configuração do Hermes. Nunca confirme tokens de portador simples no controle de versão:

- Variável de ambiente (recomendado): Defina XMEMO_KEY no shell ou ambiente que inicializa o Hermes (export XMEMO_KEY='<your-xmemo-token>').
- Assistente de configuração do Hermes: A execução de hermes memory setup xmemo solicita credenciais e configura ~/.hermes/config.yaml.
- Verificação de configuração: Verifique se ~/.hermes/config.yaml contém memory.provider definido como xmemo.

## Comportamento de carregamento e reinicialização

Os procedimentos de reinicialização do daemon ou recarregamento de sessão não estão explicitamente documentados no README do plug-in hermes-xmemo (https://github.com/yonro/hermes-xmemo-plugin/blob/30fe1bc20a/README.md); consulte a documentação do host do Hermes Agent ou reinicie sua sessão ativa de terminal do Hermes.

## Verificação de conexão (somente leitura)

Verifique a conectividade com uma solicitação de recall somente para leitura antes de gravar dados duráveis. Esta verificação não modifica o estado da memória:

- Verificação: Inicie uma sessão de teste do Hermes e emita uma consulta de recall ativo somente para leitura para o contexto de projeto existente.
- Sinal de sucesso: O Hermes retorna resultados de memória estruturados com campos Reference e Location válidos do espaço de trabalho autorizado.

## Primeira tarefa útil: Ciclo de vida de memória sintética

Verifique a persistência de memória, a transição de sessão sem estado, o recall com atribuição de fonte e a correção:

- 1. Salvar fato sintético: Armazene uma convenção de projeto ("Hermes demo conventions: UTC logging with ISO 8601 timestamps.") em "projects/demo-hermes/conventions".
- 2. Transição sem estado: Encerre a conversa atual do Hermes e inicie uma nova sessão.
- 3. Recall com atribuição de fonte: Consulte "demo conventions timestamp format". Confirme os campos Reference e Location retornados.
- 4. Corrigir memória: Atualize a convenção lembrada usando update_memory com regras de formatação atualizadas.
- 5. Limpeza opcional: Exclua temporariamente (forget) a convenção de demonstração quando a verificação de integração for concluída.

## Captura automática e prevenção de duplicatas

O Hermes Agent fornece captura automática de contexto entre os limites de execução:

- Pontos de verificação de sessão: Quando habilitado em ~/.hermes/config.yaml, o Hermes captura resumos de sessão e decisões importantes nos marcos de limite da sessão.
- Prevenção de duplicatas: A desduplicação integrada por hash de conteúdo garante que fatos e decisões idênticos não sejam gravados repetidamente durante loops de execução iterativos.
- Limite de escopo: Cada memória capturada fica estritamente isolada no espaço de trabalho do usuário autenticado e no escopo do projeto ativo.

## Conflitos de provedor e limites de armazenamento

Compreenda o isolamento de tempo de execução e a propriedade de armazenamento:

- Conflitos de provedor: Não habilite vários provedores de memória simultaneamente em ~/.hermes/config.yaml. Executar provedores sobrepostos causa problemas de split-brain no recall.
- Propriedade de armazenamento: Todas as memórias duráveis residem no back-end em nuvem do XMemo de propriedade do usuário. O Hermes mantém apenas um cache local de curta duração para capacidade de resposta da sessão.
- Limites off-line e de repetição: Interrupções transitórias de rede são gerenciadas por um buffer de gravação local delimitado; gravações off-line falham quando o limite do buffer ou a expiração do token é atingida, e ações não confirmadas não são replicadas para outros agentes até a reconexão.

## Recuperação, atualização e remoção

Procedimentos de solução de problemas, atualização e remoção para o Hermes:

- Recuperação (401 invalid_token): Verifique se XMEMO_KEY está definida no ambiente de shell atual ou na configuração do Hermes.
- Atualização: Os comandos de atualização do plug-in não estão documentados no README do plug-in hermes-xmemo (https://github.com/yonro/hermes-xmemo-plugin/blob/30fe1bc20a/README.md); execute pip install --upgrade hermes-xmemo ou consulte a documentação do host do Hermes.
- Remoção (README linha 292): Para desativar o provedor de memória no Hermes, execute o comando de remoção documentado: hermes config set memory.provider "".
- Remoção vs Exclusão remota: A desativação do provedor local não exclui memórias remotas armazenadas nem revoga credenciais de API; exclua memórias ou revogue chaves em https://xmemo.dev/me.

```bash
hermes config set memory.provider ""
```