Provedores de Memória Externa

O que Provedores de Memória Externa faz?

Instale, configure e verifique provedores de memória de terceiros para o Agente Hermes. Trate "instalado" e "ativo no Hermes" como critérios de aceitação separados.

Princípios

1. Comece pela documentação oficial atual. Carregue a skill hermes-agent e obtenha tanto a página de instalação do provedor quanto sua página completa de integração com o Hermes. Siga o caminho recomendado documentado; use um fallback documentado apenas quando uma restrição real de compatibilidade o exigir.
2. Mantenha as dependências fora do venv gerenciado do Hermes. As atualizações do Hermes podem reconstruir esse venv. Prefira pipx ou um venv persistente dedicado.
3. Combine as ABIs do Python no limite da ponte. Um ambiente pipx pode usar um Python mais novo que o Hermes. Adicionar seus site-packages ao sys.path do Hermes não é seguro quando wheels nativos estão envolvidos. Use um venv dedicado criado com o Python do Hermes quando um wrapper executar importações in-process.
4. Use a CLI do Hermes para configuração. Nunca edite manualmente o config.yaml; aplique as configurações com hermes config set.
5. Não desabilite o conjunto de ferramentas de memória compartilhada. Ao substituir a memória de arquivo legada, desabilite apenas os sinalizadores internos de arquivo/perfil documentados para o provedor. Uma desabilitação genérica hermes tools disable memory também pode ocultar ferramentas do provedor.
6. Considere o caching de prompt. Alterações de provedor/ferramenta se aplicam a sessões recém-inicializadas. Não mude o prompt do sistema ou o schema de ferramentas de uma conversa existente; reinicie o gateway e indique claramente que uma sessão TUI já em execução deve ser substituída.

Workflow de Instalação

1. Audite antes de alterar o estado

Registre:

• hermes --version e a versão/caminho do Python do Hermes
• versões dos pacotes do provedor e ambientes de instalação
• saída do instalador/status do provedor
• hermes plugins list --plain --no-bundled
• hermes config get memory.provider
• hermes memory status
• status do gateway

Não infira [all] ou extras equivalentes da versão base do pacote. Importe ou inspecione todas as dependências de capacidade nomeadas pela documentação do provedor.

2. Escolha uma topologia de isolamento

• Use pipx quando o provedor se comunicar fora do processo ou quando o Hermes descobrir um ponto de entrada de pacote seguro.
• Use um venv dedicado criado a partir do Python do Hermes quando o Hermes importar código do provedor in-process e o pacote incluir extensões nativas.
• Nunca trate importlib.util.find_spec() como prova de compatibilidade. Ele localiza módulos sem carregar código nativo. Realize importações reais sob o interpretador que executará o provedor.

3. Instale o provedor e a ponte

Instale o perfil de funcionalidade completo solicitado e seu wrapper do Hermes. Se o wrapper fornecer um comando de instalador/status, use-o para criar a ponte de plugin persistente sob $HERMES_HOME/plugins/ e verifique sua importação.

Habilite plugins de usuário explicitamente quando o Hermes os listar como opt-in:

hermes plugins enable <nome-do-manifest>

A seleção do provedor e a habilitação geral de plugins podem ser mecanismos separados. Verifique ambos.

4. Configure sem duplicação

Defina o provedor externo e, se instruído pela documentação do provedor, desabilite a memória de arquivo legada mantendo o conjunto de ferramentas de memória:

hermes config set memory.provider <provedor>
hermes config set memory.memory_enabled false
hermes config set memory.user_profile_enabled false

Use as chaves documentadas atuais do provedor em vez de assumir que são universais.

5. Reinicie e verifique

Reinicie o gateway somente após a instalação, habilitação e configuração estarem completas. Em seguida, verifique:

• O gateway está ativo.
• A ponte de plugin/status indica instalado e importável.
• A lista geral de plugins indica habilitado quando hooks/ferramentas dependerem dele.
• hermes memory status indica que o provedor selecionado está instalado, disponível e ativo.
• Os diagnósticos do provedor não possuem registros reais de erro/falha. Não interprete contadores, medições, verificações ignoradas ou sobrescritas opcionais não definidas como falhas.

6. Exercite o caminho do agente Hermes

Um teste de fumaça SDK independente é necessário, mas insuficiente. Carregue o provedor através do carregador de provedor de memória do próprio Hermes ou inicie um novo agente Hermes, e então verifique:

1. construção e inicialização do provedor;
2. bloco de prompt do sistema do provedor está ativo;
3. schemas de ferramentas do provedor estão expostos;
4. escreva uma memória de teste com tag única;
5. recupere essa tag exata;
6. exclua a memória de teste;
7. confirme que o banco de dados/caminho do provedor é o armazenamento Hermes pretendido.

Use asserções e falhe no comando de verificação se qualquer etapa falhar. Relate versões/status observados exatos, não expectativas plausíveis.

Armadilhas Comuns

• Venvs pipx separados não estão "ao lado" para importações in-process. O núcleo e o wrapper podem funcionar isoladamente enquanto o Hermes não consegue importar ambos com segurança.
• Plugin descoberto não significa plugin habilitado. A descoberta do provedor pode ser bem-sucedida enquanto o registro de hook/ferramenta permanece opt-in.
• Comando CLI ausente não prova falha do provedor. O Hermes pode carregar o provedor enquanto um instalador omitiu o cli.py irmão usado para descoberta argparse. Diagnostique provedor e CLI independentemente, depois repare apenas com uma ponte testada.
• Reinicialização do gateway não retroage na conversa atual. Novas sessões de gateway e CLI usam o provedor; um processo TUI antigo retém sua superfície de prompt/ferramenta congelada.
• Um comando de instalação bem-sucedido não é conclusão. Exija configuração de leitura, status de provedor ativo e um ciclo real de escrita/recuperação/limpeza.

Referências do Provedor

• Mnemosyne + integração Hermes, tratamento de ABI Python, ponte CLI e teste de fumaça determinístico: references/mnemosyne-hermes.md