Mnemosyne para Hermes Agent: Guia Rápido de Memória Local

Mnemosyne é um provedor de memória local-first para o Hermes Agent, armazenando memória de trabalho, fatos estruturados, dados temporais e histórico episódico em SQLite local — sem serviço hospedado, sem chamadas de rede obrigatórias e com controle de escrita notavelmente granular.

Sua propriedade mais útil não é a qualidade bruta da recordação. É a quantidade de controle que ele expõe sobre o caminho de escrita (write path): a salvaguarda automática de conversas pode ser restrita por papel (role) ou desabilitada por completo, o registro de resultados de ferramentas (tool-result) vem desabilitado por padrão, as operações explícitas de lembrar e esquecer permanecem disponíveis independentemente, e as liberações mais recentes adicionam supressão de auto-eco opcional nas fronteiras de compressão de contexto. Essa combinação o torna uma escolha razoável quando se deseja memória persistente sem automaticamente transformar cada conversa em conhecimento permanente.

Essa disciplina no caminho de escrita é importante porque a memória de agentes tem um modo de falha bem documentado: o próprio raciocínio do modelo pode ser capturado, recuperado mais tarde como se fosse uma observação e usado para justificar uma versão ainda mais forte de si mesmo. Laços de Memória Auto-Reforçantes em Agentes de IA cobre esse modo de falha em profundidade; este guia foca na configuração concreta do Mnemosyne que o limita na prática. Para saber onde o Mnemosyne se situa em relação aos outros provedores de memória do Hermes, veja Provedores de Memória de Agentes Comparados.

Mnemosyne em um minuto

Um provedor de memória típico faz alguma versão de captura, extração, armazenamento, recuperação e, em seguida, injeção em um prompt futuro. O Mnemosyne adiciona várias camadas distintas ao redor desse loop básico: memória de trabalho, recordação semântica e lexical, fatos estruturados, informação temporal, links de entidades, memória episódica, consolidação, fatos canônicos e validação de memória. O armazenamento é em SQLite local com FTS5 e recuperação vetorial opcional, o que o torna consideravelmente mais inspecionável do que um produto de memória exclusivo em nuvem e mais capaz do que um simples arquivo MEMORY.md.

Muito brevemente, em relação ao resto do ecossistema de provedores do Hermes: Holographic é mais simples e deliberadamente orientado para armazenamento de fatos; Hindsight enfatiza recuperação híbrida, grafos de conhecimento e reflexão; Honcho enfatiza modelagem de pares e usuários com raciocínio dialético; Mem0 enfatiza extração automática de fatos baseada em LLM; e Mnemosyne combina armazenamento SQLite local, recordação híbrida, consolidação, fatos estruturados e controles de retenção notavelmente granulares. O detalhamento completo, incluindo requisitos de infraestrutura e notas de auto-hospedagem para cada provedor, está em Provedores de Memória de Agentes Comparados.

Versões atuais

Em setembro de 2026, a versão estável no PyPI é mnemosyne-memory 3.15.1, com o ramo 4.0 disponível como pré-lançamento. Para uma instalação de produção do Hermes, comece pela versão estável, a menos que você necessite especificamente de uma correção ou funcionalidade da 4.0 e esteja preparado para testar a migração do banco de dados e a mudança de comportamento. Verifique sua versão instalada com:

hermes mnemosyne version

Instalando o Mnemosyne no Hermes

Ative primeiro o próprio ambiente virtual do Hermes, se você usou a instalação local padrão:

source ~/.hermes/hermes-agent/venv/bin/activate

Para suporte a incorporação local (local embedding), instale o pacote principal com o extra de embeddings mais o wrapper de plugin do Hermes:

python -m pip install \
  "mnemosyne-memory[embeddings]" \
  mnemosyne-hermes

Em seguida, registre o plugin:

mnemosyne-hermes install

Se você estiver substituindo um registro de plugin existente:

mnemosyne-hermes install --force

Ative o provedor e reinicie o gateway:

hermes config set memory.provider mnemosyne
hermes gateway restart

Verifique com:

hermes memory status

A saída esperada se parece com:

Provider: mnemosyne

Plugin: installed
Status: available

Instalações Docker e de servidor persistente

Se o Hermes roda dentro de uma implantação Docker persistente ou baseada em imagem, instale em um ambiente virtual secundário (side venv) na casa (home) montada do Hermes, em vez do ambiente Python reconstruível do contêiner, para que o plugin sobreviva a reconstruções de imagem:

export HERMES_HOME=/opt/data
VENV="$HERMES_HOME/.mnemosyne/venv"
python3 -m venv "$VENV"
"$VENV/bin/python" -m pip install --upgrade "mnemosyne-memory[embeddings]" mnemosyne-hermes
"$VENV/bin/mnemosyne-hermes" install --mode wrapper --python "$VENV/bin/python"
hermes config set memory.provider mnemosyne

O venv secundário deve usar a mesma versão principal/secundária de Python do gateway Hermes em execução — não aponte para um python3 não relacionado da PATH. Reinicie o contêiner ou serviço real em seguida e verifique com "$VENV/bin/mnemosyne-hermes" status junto com hermes memory status.

Não desabilite todo o conjunto de ferramentas de memória do Hermes

Mantenha dois conceitos separados: a memória embutida do próprio Hermes (MEMORY.md / USER.md, coberta por completo em Sistema de Memória do Hermes Agent) e o provedor externo (Mnemosyne). Não execute casualmente hermes tools disable memory ao configurar um provedor externo — dependendo da versão do Hermes, esse comando também pode ocultar as ferramentas do provedor externo de memória. Use a configuração do provedor em vez disso, conforme mostrado abaixo.

Estado básico e inspeção

hermes memory status
hermes mnemosyne stats
hermes mnemosyne stats --global
hermes mnemosyne inspect "query"

Exporte um backup portátil:

hermes mnemosyne export \
  --output ~/mnemosyne-backup.json

O banco de dados subjacente normalmente fica sob ~/.hermes/mnemosyne/data/mnemosyne.db. Como é SQLite, a inspeção e o backup são straightforward com ferramentas padrão. Para o restante dos comandos de gateway, sessão e diagnósticos referenciados ao longo deste guia, a Folha de dicas da CLI do Hermes Agent é uma referência mais rápida do que cavar pela saída de --help.

A política de retenção padrão merece atenção

O primeiro controle que vale a pena entender é sync_roles. Os padrões atuais do Mnemosyne já são mais conservadores do que nas primeiras liberações — a sincronização automática do Hermes vem configurada para turnos de usuário em vez de ambos os turnos de usuário e assistente — mas, para uma retenção estrita e apenas explícita, desabilitar a salvaguarda automática de turnos por completo vale o passo extra. Edite ~/.hermes/config.yaml:

memory:
  provider: mnemosyne

  mnemosyne:
    sync_roles: []

Uma lista vazia significa que os turnos ordinários de conversa não são salvos automaticamente por sync_turn(). As operações explícitas de mnemosyne_remember continuam a funcionar independentemente — a conversa normal para de fluir automaticamente para a memória, enquanto um “lembre-se disso” explícito ainda atinge o Mnemosyne.

Desabilite o registro automático de resultados de ferramentas

O Mnemosyne também pode registrar execuções de ferramentas como memória. Para uma configuração conservadora, deixe isso desabilitado em ~/.hermes/.env:

MNEMOSYNE_LOG_TOOLS=0

Este já é o padrão, mas configurá-lo explicitamente documenta a política em vez de depender de uma suposição sobre os padrões. Reinicie o Hermes em seguida:

hermes gateway restart

Com sync_roles: [] e MNEMOSYNE_LOG_TOOLS=0 juntos, ambos os principais caminhos de escrita automática — a salvaguarda automática de conversas e a salvaguarda automática de resultados de ferramentas — estão desligados.

Mantenha a recordação automática

Desabilitar as escritas automáticas não requer desabilitar a recordação. Uma política útil mantém a retenção automática desligada, mas a recordação automática, o lembrar explícito e o esquecer explícito permanecem todos ligados — a memória deve ser fácil de ler e difícil de escrever, o que é próximo do oposto de um padrão de “capture tudo e ordene depois”.

Adicione uma instrução durável do agente

A configuração do provedor bloqueia a captura automática no nível do provedor, mas o modelo ainda pode decidir chamar uma ferramenta de escrita explícita por iniciativa própria. Adicione uma política explícita a SOUL.md:

## Política de memória de longo prazo

O Mnemosyne é o provedor de memória de longo prazo.

Não escreva nada no Mnemosyne a menos que o usuário explicitamente peça para você lembrar, salvar, reter ou armazenar aquela informação.

Se uma informação parecer útil para sessões futuras, mas o usuário não solicitou explicitamente que ela seja lembrada, peça permissão antes de chamar mnemosyne_remember ou outra ferramenta de escrita do Mnemosyne.

Não crie memórias duráveis a partir do seu próprio raciocínio, suposições, resumos, interpretações, conclusões ou preferências inferidas.

Não crie memórias duráveis a partir da saída de ferramentas a menos que o usuário explicitamente peça que aquele resultado seja lembrado.

Ao armazenar uma memória aprovada, preserve o que o usuário realmente afirmou. Não embeleze com contexto inferido ou conclusões.

Ler e recuperar memórias do Mnemosyne é permitido sem pedir permissão.

Reinicie o gateway e inicie uma nova sessão em seguida:

hermes gateway restart

/new

Esta é uma política aplicada pelo modelo, não uma fronteira rígida de permissão — ela complementa a configuração de nível de provedor acima em vez de substituí-la.

E quanto a memory.write_approval?

O Hermes suporta memory.write_approval: true para escritas em MEMORY.md / USER.md embutidas, e o Mnemosyne implementa seu próprio estagiamento (staging) específico do provedor para escritas explícitas em liberações mais recentes. Isso é promissor, mas há uma ressalva arquitetônica que vale a pena levar a sério: o Hermes ainda não expõe um contrato de aprovação uniforme e neutro em relação ao provedor para todos os provedores externos de memória, e a implementação de pendente/aplicar (pending/apply) do Mnemosyne é específica do provedor em vez de parte de um padrão compartilhado. Não assuma que a aprovação funciona corretamente apenas porque a chave de configuração está presente — teste contra suas versões exatas do Hermes e Mnemosyne. Até que a aprovação independente de provedor amadureça, combinar sync_roles: [], MNEMOSYNE_LOG_TOOLS=0 e a política de escrita explícita no SOUL.md acima fornece uma linha de base confiável, com o caminho de aprovação testado separadamente, se você pretende confiar nele.

Ative a supressão de auto-eco

O Mnemosyne atual também oferece supressão de auto-eco opcional:

MNEMOSYNE_SELF_ECHO_ENABLED=1

Coloque isso em ~/.hermes/.env, então reinicie:

hermes gateway restart

A supressão de auto-eco mira especificamente as fronteiras de compressão de contexto — seu propósito é reduzir casos em que a memória que o provedor acabou de criar é imediatamente devolvida ao agente como se fosse contexto independente. É intencionalmente melhor esforço (best-effort) e não substitui o filtragem de escrita: os controles de escrita impedem que memórias duvidosas entrem em primeiro lugar, enquanto os controles de auto-eco impedem que a saída recente do provedor volte direto. Ambos importam, e nenhum substitui o outro.

Uma configuração conservadora do Mnemosyne

Juntando as peças, uma configuração inicial para um agente de engenharia pessoal auto-hospedado se parece com isto. Em ~/.hermes/config.yaml:

memory:
  provider: mnemosyne

  mnemosyne:
    sync_roles: []

Em ~/.hermes/.env:

MNEMOSYNE_LOG_TOOLS=0
MNEMOSYNE_SELF_ECHO_ENABLED=1

E em SOUL.md, no mínimo:

Armazene memória de longo prazo apenas quando o usuário explicitamente solicitar.
Não promova conclusões geradas pelo modelo ou saída de ferramentas para memória durável sem permissão explícita.

Teste se a conversa ordinária não é retida

Verifique primeiro a contagem base:

hermes mnemosyne stats

Inicie uma nova sessão do Hermes e faça uma afirmação factual simples sem pedir ao agente para lembrá-la, por exemplo:

PurpleOtter uses port 48123.

Em seguida, procure por ela:

hermes mnemosyne inspect "PurpleOtter"

Esperado: Results for 'PurpleOtter': 0. Verifique novamente hermes mnemosyne stats — a contagem de memória de trabalho não deve ter aumentado por causa daquele turno ordinário.

Teste memória explícita

Agora faça o mesmo tipo de afirmação, mas peça explicitamente a retenção:

Lembre-se que BlueKoala usa a porta 17321.

Inspeção, então inicie uma nova sessão e peça para trazê-la de volta:

hermes mnemosyne inspect "BlueKoala"

/new

What port does BlueKoala use?

O Hermes deve recuperar o valor corretamente — este par de testes isola a política de caminho de escrita (nada entra sem perguntar) do mecanismo de recuperação (o que entra volta de forma confiável).

Teste registro de ferramentas

Com MNEMOSYNE_LOG_TOOLS=0 definido, peça ao Hermes para executar um comando distintivo e único:

Use a ferramenta terminal para executar:
echo tool-canary-834729

Então, procure pela string canário:

hermes mnemosyne inspect "tool-canary-834729"

Esperado: 0 results. Este é um teste muito mais forte do que simplesmente confiar que a variável de ambiente é respeitada em todos os lugares.

Inspecionando o banco de dados

Como o armazenamento é SQLite, o esquema interno é diretamente inspecionável:

sqlite3 ~/.hermes/mnemosyne/data/mnemosyne.db '.tables'

Dependendo da versão, você pode ver tabelas como working_memory, episodic_memory, facts, consolidated_facts, gists, graph_edges, memoria_facts e memory_embeddings. Isso importa ao testar a exclusão — um sistema de memória pode remover com sucesso uma linha de memória de trabalho enquanto deixa um fato derivado, gist ou objeto de grafo para trás. O Mnemosyne teve bugs reais nessa área envolvendo registros derivados órfãos, e as liberações mais recentes têm apertado tanto a exclusão quanto o diagnóstico de acordo. Prefira os caminhos de exclusão e reparo/diagnóstico suportados pelo provedor em vez de deletar manualmente linhas SQLite, a menos que você entenda totalmente o esquema atual.

Excluindo memória de trabalho escopada por sessão

Um subtileza: as memórias de trabalho do Mnemosyne podem ser escopadas por sessão, então uma linha com scope = session pode não ser visível para uma exclusão standalone operando na sessão default. Ao depurar, inspecione o escopo diretamente:

SELECT id, session_id, scope, content
FROM working_memory;

O provedor ou API precisa do escopo de sessão correto para mutar registros locais da sessão — outra razão para preferir ferramentas de administração suportadas em vez de edições SQL brutas.

Consolidação: não tenha pressa de sleep()

O Mnemosyne pode consolidar memória de trabalho em representações de vida mais longa, o que é útil, mas é uma operação mutante. Antes de ativar a consolidação automática agressiva, inspecione o que está sendo capturado de fato, verifique que turnos ordinários não estão entrando na memória inesperadamente, verifique a exclusão de ponta a ponta e faça backup do banco de dados. Então experimente com:

hermes mnemosyne sleep

As mudanças recentes do Mnemosyne tornaram o tratamento de conflitos mais conservador — semelhança semântica sozinha não prova mais que uma memória deve invalidar outra, o que é exatamente a direção em que um sistema de memória de agente durável deveria se mover, como coberto em Laços de Memória Auto-Reforçantes em Agentes de IA.

Backup antes de atualizações

Crie uma exportação portátil antes de qualquer mudança significativa:

hermes mnemosyne export \
  --output ~/mnemosyne-backup.json

Para instalações importantes, também copie o banco de dados local ou o diretório de dados antes de grandes atualizações. O Mnemosyne 4.x é atualmente uma linha de pré-lançamento, então uma atualização de versão principal merece mais cautela do que uma atualização de rotina.

Configuração recomendada final

Para uma instalação de longo prazo do Hermes onde a precisão da memória é mais importante do que lembrar tudo, a configuração durável é: armazenamento local do Mnemosyne ligado, recordação automática ligada, salvaguarda automática de conversas desligada, salvaguarda automática de mensagens de assistente desligada, registro de resultados de ferramentas desligado, lembrar e esquecer explícitos ligados, supressão de auto-eco ligada, busca por sessão ligada, e revisão humana para escritas sensíveis desejável uma vez que o caminho de aprovação seja testado. Isso faz com que o Mnemosyne funcione primariamente como um armazenamento de memória de longo prazo curado, em vez de um arquivo de transcrição — o objetivo não é fazer o Hermes lembrar de tudo o que já disse, mas fazê-lo lembrar das coisas que ainda serão verdadeiras quando a próxima sessão começar. Se você executa vários perfis com provedores ou políticas de retenção diferentes, [Configuração de produção do Hermes Agent](https://www.glukhov.org/pt/ai-systems/hermes/production-setup/ “Configuração do Hermes primeiro por perfil para engenheiros, pesquisadores e operadores.”}) cobre a fiação em nível de perfil para mantê-los consistentes. Se você preferir executar a memória como um serviço Docker separado com um grafo de conhecimento e operação de reflexão, Hindsight para Hermes Agent é o guia do provedor externo baseado em Docker.