Mnemosyne per Hermes Agent: Guida rapida alla memoria locale

Mnemosyne è un provider di memoria locale-first per Hermes Agent, che archivia memoria operativa, fatti strutturati, dati temporali e cronologia episodica in SQLite locale — nessun servizio gestito, nessuna chiamata di rete obbligatoria e un controllo delle scritture insolitamente granulare.

La sua proprietà più utile non è la qualità della richiamo grezza. È la quantità di controllo che espone sul percorso di scrittura: il salvataggio automatico delle conversazioni può essere limitato per ruolo o disattivato del tutto, la registrazione dei risultati degli strumenti è disattivata di default, le operazioni esplicite di ricordare e dimenticare rimangono disponibili indipendentemente da tutto, e le release più recenti aggiungono la soppressione opzionale dell’eco di sé nei pressi dei confini di compressione del contesto. Questa combinazione lo rende una scelta ragionevole quando si desidera una memoria persistente senza trasformare automaticamente ogni conversazione in conoscenza permanente.

Questa disciplina del percorso di scrittura è importante perché la memoria degli agenti ha un fallimento ben documentato: il ragionamento di un modello può essere catturato, recuperato in seguito come se fosse un’osservazione e usato per giustificare una versione ancora più forte di se stesso. Cicli di Memoria Autorinforzanti negli Agenti IA copre questo fallimento in profondità; questa guida si concentra sulla configurazione concreta di Mnemosyne che lo limita nella pratica. Per capire dove si posiziona Mnemosyne rispetto agli altri backend di memoria di Hermes, consulta Confronto dei Provider di Memoria per Agenti.

Mnemosyne in un minuto

Un provider di memoria tipico esegue una versione di acquisizione, estrazione, archiviazione, recupero, per poi iniettarla in un prompt futuro. Mnemosyne aggiunge diversi livelli distinti attorno a questo ciclo di base: memoria operativa, richiamo semantico e lessicale, fatti strutturati, informazioni temporali, collegamenti tra entità, memoria episodica, consolidamento, fatti canonici e validazione della memoria. L’archiviazione è in SQLite locale con FTS5 e un recupero vettoriale opzionale, il che lo rende considerevolmente più ispezionabile di un prodotto di memoria solo cloud e più capace di un semplice file MEMORY.md.

Molto brevemente, rispetto al resto dell’ecosistema dei provider di Hermes: Holographic è più semplice e deliberatamente orientato allo store di fatti; Hindsight enfatizza il recupero ibrido, i grafi di conoscenza e la riflessione; Honcho enfatizza la modellazione dei pari e degli utenti con ragionamento dialettico; Mem0 enfatizza l’estrazione automatica di fatti basata su LLM; e Mnemosyne combina archiviazione SQLite locale, richiamo ibrido, consolidamento, fatti strutturati e controlli di ritenzione insolitamente granulari. Il dettaglio completo, inclusi i requisiti infrastrutturali e le note sul self-hosting per ogni provider, è in Confronto dei Provider di Memoria per Agenti.

Versioni attuali

Al settembre 2026, la release stabile su PyPI è mnemosyne-memory 3.15.1, con il ramo 4.0 disponibile come pre-release. Per un’installazione di Hermes di produzione, si consiglia di iniziare con la versione stabile, a meno che non si necessiti specificamente di una modifica o funzione della 4.0 e si sia preparati a testare la migrazione del database e il cambiamento di comportamento. Verificare la versione installata con:

hermes mnemosyne version

Installare Mnemosyne in Hermes

Attivare prima l’ambiente virtuale di Hermes stesso se si è utilizzato l’installazione locale standard:

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

Per il supporto all’embed locale, installare il pacchetto principale con l’extra embeddings e il wrapper plugin di Hermes:

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

Poi registrare il plugin:

mnemosyne-hermes install

Se si sta sostituendo una registrazione di plugin esistente:

mnemosyne-hermes install --force

Attivare il provider e riavviare il gateway:

hermes config set memory.provider mnemosyne
hermes gateway restart

Verificare con:

hermes memory status

L’output atteso è simile a:

Provider: mnemosyne

Plugin: installato
Stato: disponibile

Installazioni Docker e server persistenti

Se Hermes gira all’interno di una distribuzione Docker persistente o basata su immagini, installare in un ambiente virtuale secondario (side venv) sulla home di Hermes montata, anziché nell’ambiente Python ricostruibile del container, in modo che il plugin sopravviva alle ricostruzioni dell’immagine:

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

Il side venv deve usare la stessa versione principale/minore di Python del gateway Hermes in esecuzione — non puntarlo a un python3 non correlato presente nella PATH. Riavviare successivamente il container o il servizio reale e verificare con "$VENV/bin/mnemosyne-hermes" status accanto a hermes memory status.

Non disattivare l’intero set di strumenti di memoria di Hermes

Mantenere separati due concetti: la memoria integrata di Hermes stesso (MEMORY.md / USER.md, coperta a fondo in Sistema di Memoria di Hermes Agent) e il provider esterno (Mnemosyne). Non eseguire casualmente hermes tools disable memory quando si configura un provider esterno — a seconda della versione di Hermes, quel comando può anche nascondere gli strumenti dei provider di memoria esterni. Utilizzare la configurazione del provider invece, come mostrato di seguito.

Stato e ispezione di base

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

Esportare un backup portabile:

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

Il database di supporto si trova normalmente sotto ~/.hermes/mnemosyne/data/mnemosyne.db. Poiché è SQLite, ispezione e backup sono diretti con strumenti standard. Per il resto dei comandi di gateway, sessione e diagnostica menzionati in questa guida, la Scheda Rapida CLI di Hermes Agent è un riferimento più veloce che scavare nell’output di --help.

La politica di ritenzione di default merita attenzione

Il primo controllo da comprendere è sync_roles. Gli standard attuali di Mnemosyne sono già più conservativi rispetto alle prime release — la sincronizzazione automatica di Hermes predefinita si basa sui turni dell’utente anziché su entrambi i turni utente e assistente — ma per una ritenzione esplicita rigorosa, disattivare completamente l’autosalvataggio dei turni vale il passo extra. Modificare ~/.hermes/config.yaml:

memory:
  provider: mnemosyne

  mnemosyne:
    sync_roles: []

Un elenco vuoto significa che i turni di conversazione ordinari non vengono salvati automaticamente da sync_turn(). Le operazioni esplicite mnemosyne_remember continuano a funzionare indipendentemente — la conversazione normale smette di fluire automaticamente nella memoria, mentre un esplicito “ricorda questo” raggiunge ancora Mnemosyne.

Disattivare la registrazione automatica dei risultati degli strumenti

Mnemosyne può anche registrare le esecuzioni degli strumenti come memoria. Per una configurazione conservativa, lasciare disattivata questa opzione in ~/.hermes/.env:

MNEMOSYNE_LOG_TOOLS=0

Questo è già lo standard, ma impostarlo esplicitamente documenta la politica anziché fare affidamento su un presupposto sugli standard. Riavviare Hermes successivamente:

hermes gateway restart

Con sync_roles: [] e MNEMOSYNE_LOG_TOOLS=0 insieme, entrambi i principali percorsi di scrittura automatica — l’autosalvataggio della conversazione e l’autosalvataggio dei risultati degli strumenti — sono disattivati.

Mantenere il richiamo automatico

Disattivare le scritture automatiche non richiede di disattivare il richiamo. Una politica utile mantiene la ritenzione automatica off mentre il richiamo automatico, il ricordare esplicito e il dimenticare esplicito restano accesi — la memoria dovrebbe essere facile da leggere e difficile da scrivere, che è quasi l’opposto di uno standard “captura tutto e riordina in seguito”.

Aggiungere un’istruzione persistente all’agente

La configurazione del provider blocca l’acquisizione a livello di provider, ma il modello può ancora decidere di chiamare uno strumento di scrittura esplicito di sua iniziativa. Aggiungere una politica esplicita a SOUL.md:

## Politica della memoria a lungo termine

Mnemosyne è il provider di memoria a lungo termine.

Non scrivere nulla in Mnemosyne a meno che l'utente non chiedi esplicitamente di
ricordare, salvare, ritenere o archiviare quell'informazione.

Se un'informazione sembra utile per sessioni future ma l'utente non ha
richiesto esplicitamente che venga ricordata, chiedere il permesso prima di chiamare
mnemosyne_remember o un altro strumento di scrittura di Mnemosyne.

Non creare memorie durevoli dal proprio ragionamento, presupposti,
riassunti, interpretazioni, conclusioni o preferenze inferite.

Non creare memorie durevoli dall'output degli strumenti a meno che l'utente non
chieda esplicitamente che quel risultato venga ricordato.

Quando si archivia una memoria approvata, preservare ciò che l'utente ha realmente dichiarato.
Non abbellirlo con contesti o conclusioni inferite.

La lettura e il richiamo delle memorie di Mnemosyne sono consentiti senza chiedere
il permesso.

Riavviare il gateway e avviare una nuova sessione successivamente:

hermes gateway restart

/new

Questa è una politica applicata dal modello, non un confine di permessi rigido — integra la configurazione a livello di provider sopra descritta anziché sostituirla.

E memory.write_approval?

Hermes supporta memory.write_approval: true per le scritture in MEMORY.md / USER.md integrate, e Mnemosyne implementa la propria staging specifica del provider per le scritture esplicite nelle release più recenti. Questo è promettente, ma c’è un’osservazione architetturale da prendere sul serio: Hermes non espone ancora un contratto di approvazione uniforme e neutrale rispetto al provider per tutti i provider di memoria esterni, e l’implementazione pending/apply di Mnemosyne è specifica del provider anziché parte di uno standard condiviso. Non dare per scontato che l’approvazione funzioni correttamente solo perché la chiave di configurazione è presente — testarla contro le proprie versioni esatte di Hermes e Mnemosyne. Fino a quando l’approvazione indipendente dal provider non matura, combinare sync_roles: [], MNEMOSYNE_LOG_TOOLS=0 e la politica di scrittura esplicita in SOUL.md descritta sopra offre una base affidabile, con il percorso di approvazione testato separatamente se si intende farci affidamento.

Attivare la soppressione dell’eco di sé

Mnemosyne attuale offre anche la soppressione opzionale dell’eco di sé:

MNEMOSYNE_SELF_ECHO_ENABLED=1

Mettere questo in ~/.hermes/.env, poi riavviare:

hermes gateway restart

La soppressione dell’eco di sé mira specificamente ai confini di compressione del contesto — il suo scopo è ridurre i casi in cui una memoria appena creata dal provider viene immediatamente riiniettata nell’agente come se fosse contesto indipendente. È deliberatamente best-effort e non sostituisce il filtraggio delle scritture: i controlli di scrittura impediscono alle memorie dubbi di entrare in primo luogo, mentre i controlli dell’eco di sé impediscono all’output recente del provider di rimbalzare immediatamente indietro. Entrambi contano, e nessuno sostituisce l’altro.

Una configurazione Mnemosyne conservativa

Mettendo insieme i pezzi, una configurazione iniziale per un agente di ingegneria personale self-hosted è questa. In ~/.hermes/config.yaml:

memory:
  provider: mnemosyne

  mnemosyne:
    sync_roles: []

In ~/.hermes/.env:

MNEMOSYNE_LOG_TOOLS=0
MNEMOSYNE_SELF_ECHO_ENABLED=1

E in SOUL.md, almeno:

Archiviare memoria a lungo termine solo quando l'utente lo richiede esplicitamente.
Non promuovere conclusioni generate dal modello o output di strumenti in memoria durevole
senza permesso esplicito.

Testare che la conversazione ordinaria non sia ritenuta

Verificare prima il conteggio di base:

hermes mnemosyne stats

Avviare una nuova sessione di Hermes e dire una dichiarazione fattuale semplice senza chiedere all’agente di ricordarla, ad esempio:

PurpleOtter usa la porta 48123.

Successivamente, cercarla:

hermes mnemosyne inspect "PurpleOtter"

Atteso: Results for 'PurpleOtter': 0. Verificare di nuovo anche hermes mnemosyne stats — il conteggio della memoria operativa non dovrebbe essere aumentato a causa di quel turno ordinario.

Testare la memoria esplicita

Ora dire lo stesso tipo di dichiarazione, ma richiedere esplicitamente la ritenzione:

Ricorda che BlueKoala usa la porta 17321.

Ispezionarla, poi avviare una nuova sessione e chiederla di nuovo:

hermes mnemosyne inspect "BlueKoala"

/new

Che porta usa BlueKoala?

Hermes dovrebbe recuperare il valore correttamente — questa coppia di test isola la politica del percorso di scrittura (niente entra senza chiedere) dal meccanismo di recupero (ciò che entra viene fuori in modo affidabile).

Testare la registrazione degli strumenti

Con MNEMOSYNE_LOG_TOOLS=0 impostato, chiedere a Hermes di eseguire un comando distintivo e unico:

Usa lo strumento terminale per eseguire:
echo tool-canary-834729

Poi cercare la stringa canary:

hermes mnemosyne inspect "tool-canary-834729"

Atteso: 0 results. Questo è un test molto più forte che fidarsi semplicemente che la variabile d’ambiente sia onorata ovunque.

Ispezione del database

Poiché l’archiviazione è SQLite, lo schema interno è direttamente ispezionabile:

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

A seconda della versione, si possono vedere tabelle come working_memory, episodic_memory, facts, consolidated_facts, gists, graph_edges, memoria_facts e memory_embeddings. Questo è importante quando si testa l’eliminazione — un sistema di memoria può eliminare correttamente una riga della memoria operativa lasciando dietro un fatto derivato, un gist o un oggetto del grafo. Mnemosyne ha avuto bug reali in quest’area riguardanti record derivati orfani, e le release più recenti hanno rafforzato sia l’eliminazione che la diagnostica di conseguenza. Preferire i percorsi di eliminazione e riparazione (doctor) supportati dal provider alla cancellazione manuale delle righe SQLite a meno che non si comprenda completamente lo schema attuale.

Eliminazione della memoria operativa con ambito di sessione

Una sottigliezza: le memorie operative di Mnemosyne possono essere con ambito di sessione, quindi una riga con scope = session potrebbe non essere visibile a un’eliminazione standalone operante nella sessione default. Quando si debugga, ispezionare l’ambito direttamente:

SELECT id, session_id, scope, content
FROM working_memory;

Il provider o l’API ha bisogno dell’ambito di sessione corretto per mutare i record locali alla sessione — un altro motivo per preferire gli strumenti di amministrazione supportati alle edizioni SQL grezze.

Consolidamento: non affrettarsi con sleep()

Mnemosyne può consolidare la memoria operativa in rappresentazioni di vita più lunga, il che è utile ma è un’operazione mutante. Prima di abilitare un consolidamento automatico aggressivo, ispezionare cosa sta effettivamente venendo acquisito, verificare che i turni ordinari non stiano entrando in memoria inaspettatamente, verificare l’eliminazione dall’inizio alla fine e fare un backup del database. Poi sperimentare con:

hermes mnemosyne sleep

I recenti cambiamenti di Mnemosyne hanno reso il trattamento dei conflitti più conservativo — la somiglianza semantica da sola non dimostra più che una memoria debba invalidare un’altra, che è esattamente la direzione in cui un sistema di memoria agente durevole dovrebbe muoversi, come coperto in Cicli di Memoria Autorinforzanti negli Agenti IA.

Backup prima degli upgrade

Creare un’esportazione portabile prima di qualsiasi cambiamento significativo:

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

Per installazioni importanti, copiare anche il database locale o la directory dati prima degli upgrade maggiori. Mnemosyne 4.x è attualmente una linea pre-release, quindi un upgrade di versione maggiore merita più cautela di un aggiornamento patch di routine.

Configurazione finale consigliata

Per un’installazione di Hermes di lunga durata in cui l’accuratezza della memoria conta più del ricordare tutto, la configurazione durevole è: archiviazione locale Mnemosyne accesa, richiamo automatico acceso, autosalvataggio conversazione spento, autosalvataggio messaggi assistente spento, registrazione risultati strumenti spenta, ricordare e dimenticare espliciti accesi, soppressione eco di sé accesa, ricerca di sessione accesa, e revisione umana per scritture sensibili desiderabile una volta testato il percorso di approvazione. Questo fa funzionare Mnemosyne principalmente come uno store di memoria a lungo termine curato anziché come un archivio di trascrizioni — l’obiettivo non è far ricordare a Hermes tutto ciò che ha mai detto, ma farlo ricordare le cose che saranno ancora vere quando inizierà la prossima sessione. Se si eseguono diversi profili con provider o politiche di ritenzione diversi, Configurazione di produzione di Hermes Agent copre l’interrazione a livello di profilo per mantenerli coerenti.