Compartment: memoria offline cifrata per agenti

Cosa fa di diverso Compartment

Compartment è un archivio di memoria per agenti che mantiene ogni record crittografato sul computer che lo ha creato e non comunica mai con un servizio di rete. Due caratteristiche lo distinguono dal resto del settore della memoria per agenti. Il vault è un unico file sigillato che può essere aperto soltanto con la passphrase, mentre la fase di embedding viene eseguita localmente: il testo di una memoria non viene mai inviato altrove per essere trasformato in un vettore. La versione 4.6.0 è stata pubblicata il 10 agosto 2026, la licenza è Apache-2.0 e l'installazione avviene tramite PyPI.

Questa è un'affermazione relativa al modello di minaccia, quindi questa guida la tratta come tale. La crittografia dei dati a riposo e la progettazione offline proteggono un elenco specifico di elementi. Altri elementi restano esposti, e proprio in questa differenza si trovano i problemi del secondo giorno.

Questa guida segue la documentazione e le note di rilascio del progetto, consultate l'11 agosto 2026. Compartment include un'applicazione desktop, un elemento nella barra dei menu su macOS e un'icona nell'area di notifica su Windows, oltre al relativo strumento da riga di comando; una richiesta della passphrase non può essere gestita da un container automatizzato. Considera quanto segue come comportamento documentato, non come comportamento misurato in questa guida. Eseguilo su una macchina di prova prima di affidargli dati reali.

Cosa protegge realmente la cifratura dei dati a riposo

Il vault è protetto con XChaCha20-Poly1305, un cifrario AEAD (authenticated encryption with associated data), mentre gli slot che contengono la chiave master sono protetti tramite Argon2id, una funzione di hashing delle password progettata per essere lenta e richiedere molta memoria. Ne conseguono due aspetti. Una copia del file presente su un disco rubato, in un vecchio backup o allegata a un ticket di supporto contiene soltanto byte privi di significato. Inoltre, un singolo bit modificato fa fallire l'autenticazione all'apertura del file: la corruzione produce quindi un errore evidente, non una risposta errata.

Anche i vettori di embedding sono cifrati, e questo è più importante di quanto possa sembrare. Un embedding non è un hash. La ricerca sull'inversione degli embedding ha recuperato frammenti leggibili del testo originale partendo dal solo vettore. Di conseguenza, un indice vettoriale in chiaro accanto a un database cifrato equivale quasi a lasciare aperto il database. Compartment non scrive alcun indice in chiaro su disco.

La cancellazione è effettiva. Ogni record ha una propria chiave e compartment forget --shred distrugge quella chiave, quindi il ciphertext residuo non può essere decifrato da nessuno, nemmeno da te. È diverso da una riga eliminata da un file di database, che di norma resta leggibile nelle pagine libere finché qualcosa non la sovrascrive.

Anche l'operatività offline è essenziale. Nulla viene caricato, quindi non esiste un account del fornitore che conservi i tuoi ricordi né una API key che possa esporli.

Cosa non protegge Compartment

La protezione si interrompe al confine del vault, che si trova più vicino di quanto sembri.

L'agent legge il testo in chiaro. Recall decritta una memoria e ne passa il testo all'agent. Se l'agent è un modello ospitato, la memoria raggiunge il provider del modello nel prompt successivo, esattamente come tutto il resto del contesto. La cifratura dei dati inattivi protegge il file. Non protegge il recupero dei dati. Per questo le regole per tenere i secret fuori dagli agent AI non diventano meno importanti perché lo store è cifrato: una password salvata come memoria è una password che hai configurato per incollare automaticamente in un prompt.

Un vault sbloccato su una macchina in esecuzione è aperto. Le note di sicurezza del progetto lo dichiarano esplicitamente. Mentre il vault è sbloccato, la master key e il working set si trovano nella RAM; Python non può garantire che un buffer venga azzerato; inoltre, lo swap o un'immagine di ibernazione possono scrivere quella memoria su disco. Un malware in esecuzione con il tuo stesso utente non deve violare la cifratura, perché può interrogare il vault già sbloccato.

L'identità del chiamante è dichiarativa. I namespace possono essere limitati per chiamante, ma il nome del chiamante arriva dal processo host. Di conseguenza, un host che dichiara un nome falso riceve le autorizzazioni che afferma di avere. Le autorizzazioni dei namespace servono a organizzare l'accesso, ma non costituiscono un confine di sicurezza contro un programma locale ostile.

La cancellazione sicura non può raggiungere le copie. forget --shred distrugge la key all'interno del file corrente. Un backup creato prima della cancellazione conserva ancora quel record e continua ad aprirsi con la passphrase di quel giorno.

Una passphrase debole chiude la discussione. Argon2id rende costoso ogni tentativo. Non protegge una passphrase presente in una word list.

Installare Compartment da una release bloccata

Compartment richiede Python 3.11 o versioni successive. Il progetto evolve rapidamente: al 10 agosto 2026 erano disponibili trenta versioni su PyPI. Per questo, bloccare la versione invece di installare quella disponibile al momento.

python3 --version
pip install "compartment==4.6.0"
compartment --version
compartment init

compartment --version deve visualizzare la versione bloccata. Se la shell restituisce compartment: command not found, la directory di installazione non è inclusa in PATH. Nella maggior parte dei sistemi, questa directory è ~/.local/bin. pipx install compartment==4.6.0 e uv tool install compartment==4.6.0 evitano il problema gestendo autonomamente i propri percorsi.

compartment init richiede di inserire due volte una passphrase e non visualizza alcun carattere. Questa passphrase è l'unica chiave. Il progetto non genera password né frasi di recupero. È una scelta intenzionale: il software non conserva credenziali che non siano sotto il tuo controllo.

Verificare il risultato prima di collegarvi altri componenti.

compartment status

Un vault funzionante segnala di essere sbloccato. Se segnala di essere bloccato, eseguire compartment unlock e inserire la passphrase. Dopo un riavvio viene nuovamente bloccato, perché la credenziale che lo mantiene aperto dipende da un secret generato per ogni avvio. Su macOS, compartment unlock --keychain consente di mantenere lo sblocco dopo un riavvio memorizzando la credenziale nel portachiavi di sistema.

Dove si trovano effettivamente i dati

Il vault predefinito è ~/.compartment/memory.vault. Per indicare un percorso diverso, usa --vault PATH con qualsiasi comando oppure imposta la variabile d’ambiente COMPARTMENT_VAULT.

Quel file contiene l’intero archivio. Inizia con un’intestazione che contiene la versione del formato e gli slot di chiavi Argon2id, prosegue con il payload sigillato e termina con le voci del journal aggiunte quando arrivano nuovi ricordi. Ogni voce del journal include la propria lunghezza e un CRC (controllo di ridondanza ciclico) calcolato su tale lunghezza. In questo modo, una scrittura interrotta da un arresto anomalo viene riconosciuta come una voce troncata e non viene letta come dati. La compattazione serializza il vault, scrive un file temporaneo, esegue fsync e infine lo rinomina nella posizione corretta. Un lettore non vede quindi mai un vault scritto solo parzialmente.

La conseguenza utile è che uno script di backup deve copiare un solo percorso. La conseguenza meno pratica è che non puoi usare grep sul contenuto e non puoi ripararlo con un editor di testo. Se vuoi una memoria leggibile con cat e gestibile con commit in git, i file di memoria locali in formato testo di Memmy rappresentano il compromesso opposto. Entrambe le soluzioni sono valide, in base al rischio che vuoi ridurre: il furto del laptop oppure un malfunzionamento dello strumento.

compartment uninstall rimuove il software e conserva il vault. Passa --purge solo quando è realmente necessario.

Collegamento a un agent

Un solo comando configura un client supportato.

compartment integrate --list
compartment integrate claude

Per Claude Code, il comando scrive una voce del server MCP (model context protocol) e un hook PostToolUse in ~/.claude/settings.json, creando prima una copia di backup del file, installa una skill /compartmentalize in ~/.claude/skills/ e aggiunge un blocco gestito a ~/.claude/CLAUDE.md per indicare all'agent che Compartment ha la precedenza sulla memoria basata sui file che utilizzava. Verifica entrambe le parti:

compartment hook status
compartment recent

Per registrare manualmente il server:

claude mcp add --scope user compartment -- \
    compartment --vault ~/.compartment/memory.vault --caller claude-code serve

Qualsiasi altro host compatibile con MCP usa lo stesso server con il proprio nome del chiamante.

{ "mcpServers": { "compartment": {
    "command": "compartment",
    "args": ["--vault", "/path/to/memory.vault",
             "--caller", "your-agent-name", "serve"] } } }

Assegna a ogni host un valore --caller diverso. È l'etichetta registrata nel log di audit e la chiave associata alle concessioni dello spazio dei nomi. Usare lo stesso nome rende inutili entrambe.

Se Claude Code ha già scritto dati nei propri file di memoria, compartment import-claude --dry-run mostra cosa verrebbe trasferito prima di eseguire qualsiasi modifica. Leggi prima cosa conserva Claude Code nei propri file di memoria, perché importare un anno di note in un vault vuoto è il modo più rapido per riempire un archivio di memoria con informazioni che nessuno intendeva conservare.

Quanto è veloce un vault locale

Questi sono i valori pubblicati dal progetto per un vault di dimensioni personali. Provengono dalla documentazione del progetto, non da un test eseguito in questo ambiente.

[
  {
    "label": "Store one memory, end to end",
    "latency_ms": 40
  },
  {
    "label": "Embed one memory, bundled model",
    "latency_ms": 25
  },
  {
    "label": "Hybrid search, median",
    "latency_ms": 11.6
  },
  {
    "label": "Vector search at 20k records, p95",
    "latency_ms": 0.68
  }
]

La memorizzazione di una memoria richiede 40 ms, mentre una ricerca vettoriale su ventimila record richiede 0.68 ms al 95° percentile. Il progetto giustifica il mantenimento della memoria in locale con un semplice calcolo: un singolo round trip di rete verso un'API di memoria in hosting spesso richiede più dei 11.6 ms della mediana di una ricerca ibrida completa eseguita qui.

Due dettagli progettuali spiegano questi valori di ricerca. Al di sotto di ventimila record, Compartment confronta la query con ogni vettore, quindi il richiamo è esatto per costruzione e non approssimato. Oltre questa soglia, passa a HNSW (hierarchical navigable small world), un indice approssimato che sacrifica una parte ridotta del richiamo per aumentare la velocità. Il vault registra inoltre l'hash SHA-256 del modello di embedding e rifiuta l'apertura se viene rilevato un modello diverso, perché i vettori generati da due modelli differenti possono essere confrontati senza produrre errori visibili, mentre i punteggi restituiti non hanno alcun significato.

Backup e copia che puoi ancora aprire l’anno prossimo

Un vault bloccato è un singolo file portabile, quindi per spostarlo basta copiarlo.

compartment lock
scp ~/.compartment/memory.vault other-machine:
compartment --vault memory.vault unlock

Bloccalo prima. Se copi mentre l’agent sta scrivendo, puoi acquisire una voce del journal durante l’aggiunta. Sebbene la struttura CRC consenta al lettore di ignorare quel frammento finale, il contenuto in memoria viene perso. compartment lock --sign sigilla il file con un manifest Ed25519, così la macchina ricevente può verificare che la copia sia arrivata integra senza conoscere la passphrase.

Poiché il file è già sigillato, il normale cloud storage è una destinazione accettabile. È in questo caso che la cifratura at rest offre un vantaggio diretto: la destinazione del backup non vede mai alcun contenuto in memoria.

Due avvertenze. Lo shredding non raggiunge i backup, quindi un record sottoposto oggi a crypto shredding resta leggibile nella copia della settimana scorsa da chiunque disponga della passphrase della settimana scorsa. Inoltre, compartment export --plaintext scrive l’intero vault senza cifratura: è lo strumento corretto per migrare verso un’altra soluzione, ma il file sbagliato da lasciare in ~/Downloads.

Conserva poche copie e assegna loro una data. Un memory store diventa una responsabilità quando nessuno elimina quelle obsolete; questo è il motivo illustrato in perché le memorie obsolete dell’agent compromettono silenziosamente il retrieval.

Gestione delle chiavi, rotazione e secondo fattore

compartment rekey
compartment 2fa enable
compartment 2fa status

rekey cambia la passphrase riscrivendo la chiave master nel keyslot del file corrente. Le copie precedenti mantengono la vecchia passphrase, perché quei byte sono stati sigillati prima della modifica e nessun comando torna indietro per aggiornarli. Ruota anche le copie oppure accetta che una passphrase ritirata possa ancora aprire qualcosa.

2fa enable aggiunge un keyfile come secondo fattore. Il keyfile viene combinato con la passphrase durante la derivazione della chiave, quindi servono entrambi per aprire il vault. Questo raddoppia anche il numero di elementi che puoi perdere. Conserva il keyfile su una macchina diversa da quella che contiene il vault.

Per gli script e la CI (continuous integration), la passphrase può essere passata tramite la variabile d'ambiente COMPARTMENT_PASSPHRASE, mentre unlock --passphrase-stdin la legge da una pipe. Preferisci la pipe. Gli altri processi eseguiti dallo stesso utente possono leggere una variabile d'ambiente, che inoltre tende a finire nei log dei job.

La cronologia dell'audit usa una catena di hash e compartment audit verify la percorre segnalando il primo collegamento non valido. Eseguilo dopo ogni ripristino, perché è in quel momento che emerge un file troncato senza messaggi evidenti.

Cosa succede quando perdi la passphrase

Non succede nulla, ed è proprio questo il comportamento previsto. Non esistono reimpostazione, frase di recupero o indirizzo su cui scrivere, perché nessuna copia della chiave esiste al di fuori della memoria e dell'eventuale keyfile. Il vault resta un file composto da byte dall'aspetto casuale.

Il piano di recupero, quindi, non riguarda il vault. Riguarda la passphrase. Registrala in un password manager il giorno in cui esegui compartment init. Poi verifica che funzioni: blocca il vault, sbloccalo usando soltanto ciò che hai annotato e, dopo aver completato la verifica, consenti a un agent di iniziare a compilarlo.

Compartment o un server della memoria

Compartment è progettato per essere usato su una singola macchina. La condivisione richiede la copia del file bloccato oppure l'esportazione e l'importazione dei dati. Non esiste un writer simultaneo. Di conseguenza, un laptop e una workstation che usano lo stesso file sovrascriveranno le modifiche reciproche.

Quando più macchine devono usare la stessa memoria contemporaneamente, il problema è di tipo server. Un server Mem0 self-hosted su un VPS risolve questa esigenza: un endpoint, molti client e una memoria che rimane disponibile anche quando il laptop non lo è. È importante dichiarare chiaramente il costo. Il server esegue un processo che può leggere i dati archiviati. Il threat model include quindi il VPS e chiunque possa raggiungere la relativa API.

Scegli in base alla perdita che vuoi realmente evitare. Se temi il furto del laptop o che un vendor legga i tuoi appunti, il vault locale cifrato è la soluzione più solida. Se temi un agent che dimentica tutto non appena cambi macchina, la soluzione è il server.

FAQ

Che cosa protegge effettivamente la crittografia di Compartment?

Protegge il file. Il vault è sigillato con XChaCha20-Poly1305, i suoi keyslot sono protetti tramite Argon2id e anche i vettori di embedding sono cifrati. Un disco sottratto o un vecchio backup contiene quindi soltanto byte privi di dati leggibili. La crittografia non protegge un vault sbloccato su una macchina in esecuzione, perché la master key rimane nella RAM mentre il vault è aperto. Inoltre, non controlla ciò che un agent fa con una memoria dopo averla ricevuta in testo in chiaro.

Se Compartment è offline, le mie memorie restano private rispetto al provider del modello?

Solo finché non vengono recuperate. L'archiviazione e la ricerca avvengono senza rete, e il modello di embedding viene eseguito localmente. Al momento della scrittura, quindi, nessun dato lascia la macchina. Al momento della lettura, l'agent riceve il testo in chiaro. Se l'agent usa un modello ospitato, la memoria entra nel prompt e viene inviata al provider insieme al resto della finestra di contesto. Non memorizzare mai una credenziale come memoria.

Che cosa succede se perdo la passphrase di Compartment?

Il vault diventa irrecuperabile, intenzionalmente. Compartment non genera alcun seed né alcuna recovery phrase e non conserva credenziali che non siano già in tuo possesso. Non c'è quindi nulla da reimpostare. Inserisci la passphrase in un password manager, conserva qualsiasi keyfile 2FA fuori dalla macchina che contiene il vault e verifica di poter sbloccare una copia prima di memorizzare nel vault dati importanti.

Due macchine possono condividere un vault di Compartment?

Non contemporaneamente. Un vault bloccato è un singolo file portatile. La procedura documentata consiste nel bloccarlo, copiarlo e quindi sbloccarlo sull'altra macchina con --vault. Non è previsto l'accesso concorrente. Se due macchine scrivono nello stesso file, alcune memorie andranno perse. Quando ti serve questa modalità, esegui un memory server.