Mnemosyne para Hermes Agent: Guia Rápido de Memória Local
Memória local do Hermes com gravações controladas.
Mnemosyne é um provedor de memória local-first para o Hermes Agent, armazenando memória de trabalho, fatos estruturados, dados temporais e história episódica em SQLite local — sem serviço hospedado, sem chamadas de rede obrigatórias e com controle de gravação excepcionalmente granular.
Sua propriedade mais útil não é a qualidade bruta da lembrança. É a quantidade de controle que ele expõe sobre o caminho de gravação: o salvamento automático de conversas pode ser restrito por papel ou desativado por completo, o registro de resultados de ferramentas é desativado por padrão, as operações explícitas de lembrar e esquecer permanecem disponíveis independentemente disso, e as versões mais recentes adicionam supressão opt-in de auto-eco nas fronteiras de compressão de contexto. Essa combinação o torna uma escolha razoável quando se deseja memória persistente sem transformar automaticamente cada conversa em conhecimento permanente.
Essa disciplina no caminho de gravação é importante porque a memória de agentes tem um modo de falha bem documentado: a inferência própria de um modelo pode ser capturada, recuperada posteriormente como se fosse uma observação e usada para justificar uma versão ainda mais forte de si mesma. Lapsos de Memória Auto-Reforçantes em Agentes de IA aborda 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 backends 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 em torno desse loop básico: memória de trabalho, recuperaçã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 é SQLite local com FTS5 e recuperação vetorial opcional, o que o torna consideravelmente mais inspecionável do que um produto de memória apenas na nuvem e mais capaz do que um arquivo simples MEMORY.md.
Muito brevemente, em relação ao resto do ecossistema de provedores do Hermes: Holographic é mais simples e deliberadamente orientado a 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 o Mnemosyne combina armazenamento SQLite local, recuperação híbrida, consolidação, fatos estruturados e controles de retenção excepcionalmente granulares. A análise completa, incluindo requisitos de infraestrutura e notas de auto-hospedagem para todos os provedores, está em Provedores de Memória de Agentes Comparados.
Versões atuais
A partir de setembro de 2026, a release estável no PyPI é mnemosyne-memory 3.15.1, com o ramo 4.0 disponível como pré-release. Para uma instalação de produção do Hermes, comece com a versão estável, a menos que você precise 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 a 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 embedding local, instale o pacote principal com o extra de embeddings mais o plugin wrapper 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 um Docker persistente ou de uma implantação baseada em imagem, instale em um ambiente virtual lateral no home do Hermes montado, em vez do ambiente Python reconstruível do contêiner, para que o plugin sobreviva às 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 lateral deve usar a mesma versão principal/secundária de Python que o gateway Hermes em execução — não o aponte para um python3 não relacionado do PATH. Reinicie o contêiner ou serviço real em seguida e verifique com "$VENV/bin/mnemosyne-hermes" status ao lado de hermes memory status.
Não desative 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 completamente em Sistema de Memória do Hermes Agent) e o provedor externo (Mnemosyne). Não execute hermes tools disable memory casualmente ao configurar um provedor externo — dependendo da versão do Hermes, esse comando também pode ocultar as ferramentas de provedores de memória externos. Use a configuração do provedor em vez disso, como mostrado abaixo.
Status 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 de suporte 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óstico referenciados ao longo deste guia, a [folha de dicas da CLI do Hermes Agent](https://www.glukhov.org/pt/ai-systems/hermes/hermes-agent-cli-cheatsheet/ “Referência rápida para a CLI do Hermes Agent — instalação, hermes chat, gateway, skills, memória, diagnóstico e comandos de barra.”}) é uma referência mais rápida do que vasculhar a 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 as releases iniciais — a sincronização automática do Hermes padrão é para turnos do usuário, em vez de ambos os turnos do usuário e assistente — mas, para uma retenção estritamente explícita, desativar o salvamento automático 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 de conversa comuns 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 “lembrar disso” explícito ainda chega ao Mnemosyne.
Desative 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 desativado em ~/.hermes/.env:
MNEMOSYNE_LOG_TOOLS=0
Este já é o padrão, mas definir explicitamente documenta a política em vez de confiar em uma premissa 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 gravação automáticos — salvamento automático de conversas e salvamento automático de resultados de ferramentas — estão desligados.
Mantenha a recuperação automática
Desativar gravações automáticas não requer desativar a recuperação. Uma política útil mantém a retenção automática desligada, enquanto a recuperação automática, lembrar explícito e esquecer explícito permanecem ligados — a memória deve ser fácil de ler e difícil de gravar, o que é quase o oposto de um padrão de “capture tudo e organize depois”.
Adicione uma instrução de agente durável
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 gravação explícita por iniciativa própria. Adicione uma política explícita a SOUL.md:
## Política de memória de longo prazo
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
lembrar, salvar, reter ou armazenar aquela informação.
Se uma informação parecer útil para sessões futuras, mas o usuário não
explicitamente pediu que ela fosse lembrada, peça permissão antes de chamar
mnemosyne_remember ou outra ferramenta de gravação do Mnemosyne.
Não crie memórias duráveis a partir do seu próprio raciocínio, premissas,
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 a 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
Isto é uma política aplicada pelo modelo, não uma fronteira de permissão rígida — ela complementa a configuração de nível de provedor acima, em vez de substituí-la.
O que há com memory.write_approval?
O Hermes suporta memory.write_approval: true para gravações em MEMORY.md / USER.md embutidos, e o Mnemosyne implementa seu próprio staging específico do provedor para gravações explícitas em releases 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 ao provedor para todos os provedores de memória externos, e a implementação pendente/aplicável do Mnemosyne é específica do provedor, em vez de ser 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-a 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 SOUL.md de gravação explícita 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 opcional de auto-eco:
MNEMOSYNE_SELF_ECHO_ENABLED=1
Coloque isso em ~/.hermes/.env, então reinicie:
hermes gateway restart
A supressão de auto-eco visa 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 de melhor esforço e não substitui a filtragem de gravação: os controles de gravação impedem memórias questionáveis de entrar em primeiro lugar, enquanto os controles de auto-eco impedem a saída recente do provedor de rebater diretamente de volta. 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 isso. 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 a 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 comum não é retida
Verifique primeiro a contagem da linha de base:
hermes mnemosyne stats
Inicie uma nova sessão do Hermes e diga uma declaração factual simples sem pedir ao agente para lembrá-la, por exemplo:
PurpleOtter uses port 48123.
Em seguida, busque por ela:
hermes mnemosyne inspect "PurpleOtter"
Esperado: Results for 'PurpleOtter': 0. Também reconfirme hermes mnemosyne stats — a contagem da memória de trabalho não deve ter aumentado por causa daquele turno comum.
Teste memória explícita
Agora diga o mesmo tipo de declaração, mas peça explicitamente a retenção:
Remember that BlueKoala uses port 17321.
Inspecione-a, depois 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 — esse par de testes isola a política do caminho de gravação (nada entra sem pedir) do mecanismo de recuperação (o que entra volta confiavelmente).
Teste registro de ferramentas
Com MNEMOSYNE_LOG_TOOLS=0 definido, peça ao Hermes para executar um comando distinto e único:
Use the terminal tool to run:
echo tool-canary-834729
Em seguida, busque pela string de 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 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 releases mais recentes apertaram tanto a exclusão quanto o diagnóstico de acordo. Prefira os caminhos de exclusão e doctor/repair suportados pelo provedor em vez de excluir linhas SQLite manualmente, a menos que você entenda completamente o esquema atual.
Excluindo memória de trabalho com escopo de sessão
Uma sutileza: as memórias de trabalho do Mnemosyne podem ter escopo de 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 — mais uma 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 a memória de trabalho em representações de vida mais longa, o que é útil, mas é uma operação mutável. Antes de habilitar a consolidação automática agressiva, inspecione o que está sendo capturado, verifique que os turnos comuns 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. Depois experimente com:
hermes mnemosyne sleep
Mudanças recentes no Mnemosyne tornaram o tratamento de conflito mais conservador — semelhança semântica sozinha não prova mais que uma memória deve invalidar outra, o que é exatamente a direção para a qual um sistema de memória de agente durável deve se mover, como coberto em Lapsos 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 atualizações maiores. O Mnemosyne 4.x é atualmente uma linha de pré-release, portanto, uma atualização de versão principal merece mais cautela do que uma atualização de patch de rotina.
Configuração final recomendada
Para uma instalação do Hermes de longo prazo onde a precisão da memória importa mais do que lembrar de tudo, a configuração durável é: armazenamento local do Mnemosyne ligado, recuperação automática ligada, salvamento automático de conversas desligado, salvamento automático de mensagens do assistente desligado, registro de resultados de ferramentas desligado, lembrar e esquecer explícitos ligados, supressão de auto-eco ligada, busca de sessão ligada e revisão humana para gravações 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 que já disse, mas fazer com que ele lembre das coisas que ainda serão verdadeiras quando a próxima sessão começar. Se você executa vários perfis com diferentes provedores ou políticas de retenção, [Configuração de produção do Hermes Agent](https://www.glukhov.org/pt/ai-systems/hermes/production-setup/ “Configuração Hermes first-profile para engenheiros, pesquisadores e operadores.”}) cobre a fiação de nível de perfil para mantê-los consistentes.
