Compartment: memória de agentes encriptada offline

O que o Compartment faz de forma diferente

O Compartment é um armazenamento de memória de agentes que mantém cada registo encriptado na máquina que o criou e nunca comunica com um serviço de rede. Duas opções distinguem-no do restante campo da memória de agentes. O cofre é um único ficheiro selado que só a sua frase-passe abre, e a etapa de criação de embeddings é executada localmente, pelo que o texto de uma memória nunca é enviado para outro local para ser convertido num vetor. A versão 4.6.0 foi publicada em 10 August 2026, a licença é Apache-2.0 e a instalação é feita a partir do PyPI.

Isto é uma afirmação sobre o modelo de ameaças, pelo que este guia trata-a como tal. A encriptação em repouso e o desenho offline protegem uma lista específica de elementos. Deixam outros elementos expostos, e é nessa lacuna que surgem os problemas do segundo dia.

Este guia segue a documentação e as notas de lançamento do próprio projeto, consultadas em 11 August 2026. O Compartment disponibiliza uma aplicação para desktop, um item na barra de menus do macOS e um ícone na área de notificação do Windows, além da sua ferramenta de linha de comandos, e um pedido de frase-passe não pode ser controlado a partir de um contentor automatizado. Considere o que se segue como comportamento documentado, não como comportamento medido neste guia. Execute-o numa máquina sobresselente antes de confiar-lhe dados reais.

O que a encriptação em repouso realmente protege

O cofre é selado com XChaCha20-Poly1305, uma cifra AEAD (authenticated encryption with associated data), e os keyslots que contêm a chave-mestra são protegidos com Argon2id, uma função de hash de palavras-passe concebida para ser lenta e consumir muita memória. Daqui resultam duas consequências. Uma cópia do ficheiro num disco roubado, num backup antigo ou anexada a um pedido de suporte não passa de bytes sem utilidade. Além disso, uma única alteração de bit faz falhar a autenticação quando o ficheiro é aberto. A corrupção transforma-se num erro explícito, em vez de produzir uma resposta errada.

Os vetores de embedding também são encriptados, o que é mais importante do que pode parecer. Um embedding não é um hash. Estudos sobre a inversão de embeddings recuperaram fragmentos legíveis do texto original apenas a partir do vetor. Por isso, um índice de vetores em texto simples ao lado de uma base de dados encriptada equivale quase a deixar a base de dados aberta. O Compartment não grava índices em texto simples no disco.

A eliminação é efetiva. Cada registo tem a sua própria chave, e compartment forget --shred destrói essa chave. Assim, o texto cifrado restante não pode ser desencriptado por ninguém, incluindo por si. Compare isto com uma linha eliminada de um ficheiro de base de dados. Normalmente, ela continua legível nas páginas livres até ser substituída.

O funcionamento offline é a outra metade. Nada é carregado, por isso não existe uma conta do fornecedor que guarde as suas memórias nem uma chave de API que possa divulgá-las.

O que o Compartment não protege

A proteção termina no limite do cofre, e esse limite está mais próximo do que parece.

O agente lê texto simples. O Recall desencripta uma memória e entrega o texto ao agente. Se esse agente for um modelo alojado, a memória segue para o fornecedor do modelo dentro do prompt seguinte, exatamente como todo o restante conteúdo da janela de contexto. A encriptação em repouso protege o ficheiro. Não protege a recuperação. Por isso, as regras sobre manter segredos fora dos agentes de IA não são menos importantes porque o armazenamento está encriptado: uma palavra-passe guardada como memória é uma palavra-passe que configurou para ser colada automaticamente num prompt.

Um cofre desbloqueado numa máquina em execução está aberto. As notas de segurança do projeto afirmam isto claramente. Enquanto o cofre está desbloqueado, a chave mestra e o conjunto de trabalho permanecem na RAM, o Python não pode garantir que um buffer seja apagado e o swap ou uma imagem de hibernação pode gravar essa memória no disco. Um malware em execução com o seu utilizador nunca precisa de quebrar a cifra, porque pode consultar o cofre já desbloqueado.

A identidade do chamador é declarativa. Os namespaces podem ser restringidos por chamador, mas o nome do chamador vem do processo anfitrião. Por isso, um anfitrião que minta sobre o próprio nome recebe as concessões que declara. As permissões dos namespaces são uma forma de organização, não uma fronteira de segurança contra um programa local hostil.

A destruição segura não alcança as cópias. forget --shred destrói a chave dentro do ficheiro atual. Uma cópia de segurança criada antes da destruição ainda contém esse registo e continua a abrir com a frase-passe usada nesse dia.

Uma frase-passe fraca encerra a discussão. O Argon2id torna cada tentativa dispendiosa. Não protege uma frase-passe que apareça numa lista de palavras.

Instalar o Compartment a partir de uma versão fixada

O Compartment requer Python 3.11 ou mais recente. O projeto evolui rapidamente e já tinha trinta versões no PyPI em 10 August 2026. Por isso, fixe a versão em vez de instalar a versão que estiver disponível no dia da instalação.

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

compartment --version deve apresentar a versão que fixou. Se a shell responder compartment: command not found, o diretório de instalação não está no seu PATH. Na maioria dos sistemas, esse diretório é ~/.local/bin. pipx install compartment==4.6.0 e uv tool install compartment==4.6.0 evitam esse problema ao gerirem os próprios caminhos.

compartment init pede uma frase-passe duas vezes e não apresenta qualquer texto enquanto a escreve. Essa frase-passe é a única chave. O projeto não gera uma palavra-passe nem uma frase de recuperação. Isto é intencional: não existe uma credencial que o software detenha sem que você a detenha também.

Verifique o resultado antes de o integrar em qualquer sistema.

compartment status

Um vault em bom estado informa que está desbloqueado. Se informar que está bloqueado, execute compartment unlock e introduza a frase-passe. Um reinício bloqueia-o novamente, porque a credencial que o mantém aberto depende de um segredo específico de cada boot. No macOS, compartment unlock --keychain permite que sobreviva a um reinício, armazenando essa credencial no keychain do sistema.

Onde os dados ficam de facto

O cofre predefinido é ~/.compartment/memory.vault. Aponte para outro local com --vault PATH em qualquer comando ou com a variável de ambiente COMPARTMENT_VAULT.

Esse único ficheiro é todo o armazenamento. Começa com um cabeçalho que contém a versão do formato e os keyslots Argon2id, seguido do payload selado e das entradas de journal anexadas à medida que chegam novas memórias. Cada entrada de journal inclui o seu tamanho e um CRC (verificação de redundância cíclica) desse tamanho. Assim, uma escrita interrompida por uma falha é reconhecida como uma entrada truncada, em vez de ser lida como dados. A compactação serializa o cofre, escreve um ficheiro temporário, executa fsync e depois muda o nome desse ficheiro para o nome final. Deste modo, um leitor nunca vê um cofre escrito apenas parcialmente.

A consequência útil é que um script de backup copia exatamente um caminho. A consequência menos conveniente é que não pode fazer grep no cofre nem repará-lo num editor de texto. Se quiser memória que possa ler com cat e enviar para o git, os ficheiros de memória locais simples do Memmy representam a opção oposta. Ambas as opções são razoáveis, dependendo de recear mais um portátil roubado ou uma ferramenta que deixa de funcionar.

compartment uninstall remove o software e mantém o cofre. Passe --purge apenas quando essa for realmente a sua intenção.

Integração num agente

Um comando integra um cliente compatível.

compartment integrate --list
compartment integrate claude

No Claude Code, este comando cria uma entrada de servidor MCP (model context protocol) e um hook PostToolUse em ~/.claude/settings.json, fazendo primeiro uma cópia de segurança do ficheiro, instala uma skill /compartmentalize em ~/.claude/skills/ e adiciona um bloco gerido a ~/.claude/CLAUDE.md. Esse bloco informa o agente de que o Compartment substitui a memória baseada em ficheiros que o agente utilizava. Confirme as duas partes:

compartment hook status
compartment recent

Para registar o servidor manualmente:

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

Qualquer outro host compatível com MCP utiliza o mesmo servidor com o nome do chamador correspondente.

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

Atribua um valor --caller diferente a cada host. Esse é o rótulo que o log de auditoria regista e a chave contra a qual são escritas as concessões de namespace. Por isso, um nome partilhado torna ambos inúteis.

Se o Claude Code já tiver escrito factos nos seus próprios ficheiros de memória, compartment import-claude --dry-run mostra o que seria movido antes de qualquer alteração. Leia primeiro o que o Claude Code mantém nos seus ficheiros de memória, porque importar um ano de notas para um vault vazio é uma forma de encher um armazenamento de memória com conteúdo que ninguém pretendia manter.

Qual é a velocidade de um vault local

Estes são os valores publicados pelo projeto para um vault de tamanho pessoal. Foram retirados da documentação do projeto, não de uma execução realizada aqui.

[
  {
    "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
  }
]

O armazenamento de uma memória demora 40 ms, e uma pesquisa vetorial em vinte mil registos demora 0.68 ms no percentil 95. O argumento do projeto para manter a memória local é uma questão de aritmética: uma única ida e volta pela rede até uma API de memória alojada muitas vezes demora mais do que a mediana de 11.6 ms de uma pesquisa híbrida completa aqui.

Dois detalhes de conceção explicam os valores da pesquisa. Abaixo de vinte mil registos, o Compartment compara a consulta com todos os vetores, pelo que a recuperação é exata por construção, e não aproximada. Acima desse limite, muda para HNSW (hierarchical navigable small world), um índice aproximado que troca alguma recuperação por velocidade. O vault também regista o hash SHA-256 do modelo de embeddings e recusa abrir com um modelo diferente, porque é possível comparar vetores de dois modelos diferentes sem que seja apresentado qualquer erro, mas as pontuações devolvidas não têm significado.

Backups e a cópia que ainda consegue abrir no próximo ano

Um vault bloqueado é um único ficheiro portátil, por isso movê-lo consiste em copiar o ficheiro.

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

Bloqueie-o primeiro. Copiá-lo enquanto o agente está a escrever pode capturar uma entrada do journal a meio do append. Embora o enquadramento CRC permita que um leitor ignore esse fragmento final, os dados que estavam na memória perdem-se. compartment lock --sign sela o ficheiro com um manifesto Ed25519, para que a máquina de destino possa verificar se a cópia chegou intacta sem ter a passphrase.

Como o ficheiro já está selado, o armazenamento cloud comum é um local aceitável para o guardar. É neste ponto que a encriptação em repouso produz um benefício direto: o destino do backup nunca vê nenhuma memória.

Dois avisos. Shredding não afeta os backups. Por isso, um registo que foi crypto shredded hoje continua legível na cópia da semana passada para qualquer pessoa com a passphrase da semana passada. E compartment export --plaintext escreve o vault inteiro sem encriptação. É a ferramenta certa para migrar para outra solução e o ficheiro errado para deixar em ~/Downloads.

Mantenha poucas cópias e coloque-lhes a data. Um armazenamento de memórias transforma-se numa responsabilidade quando ninguém o depura. Esse é o motivo explicado em porque as memórias antigas do agente contaminam silenciosamente a recuperação.

Gestão, rotação de chaves e o segundo fator

compartment rekey
compartment 2fa enable
compartment 2fa status

rekey altera a frase secreta ao voltar a proteger a chave principal no keyslot do ficheiro atual. As cópias antigas mantêm a frase secreta antiga, porque esses bytes foram selados antes da alteração e nada volta atrás para os editar. Rode também as cópias ou aceite que uma frase secreta desativada ainda abre algum conteúdo.

2fa enable adiciona um keyfile como segundo fator. O keyfile é combinado com a frase secreta durante a derivação da chave, por isso ambos são necessários para abrir o cofre. Isto também duplica o número de elementos que pode perder. Mantenha o keyfile fora da máquina que contém o cofre.

Para scripts e CI (integração contínua), a frase secreta pode ser fornecida através da variável de ambiente COMPARTMENT_PASSPHRASE, e unlock --passphrase-stdin lê-a a partir de um pipe. Prefira o pipe. Uma variável de ambiente pode ser lida por outros processos pertencentes ao mesmo utilizador e tende a aparecer nos logs dos jobs.

O histórico de auditoria está encadeado por hashes, e compartment audit verify percorre-o e indica a primeira ligação quebrada. Execute-o depois de qualquer restauro, porque é nesse momento que um ficheiro truncado silenciosamente se torna evidente.

O que acontece quando você perde a passphrase

Nada acontece. Esse é o comportamento esperado. Não existe reposição, frase de recuperação nem endereço para o qual escrever, porque não há nenhuma cópia da chave fora da sua memória e do seu keyfile opcional. O vault continua a ser um ficheiro com bytes de aparência aleatória.

Por isso, o plano de recuperação não é um plano para o vault. É um plano para a passphrase. Registe-a num gestor de palavras-passe no dia em que executar compartment init. Depois, teste-a: bloqueie o vault, desbloqueie-o usando apenas o que registou e só depois deixe um agent começar a preenchê-lo.

Compartimento ou servidor de memória

O Compartment foi concebido para uma única máquina. A partilha implica copiar o ficheiro bloqueado, ou exportar e importar, e não existe escrita concorrente. Por isso, um portátil e uma estação de trabalho que apontem para o mesmo ficheiro vão sobrescrever o trabalho um do outro.

Quando várias máquinas precisam da mesma memória ao mesmo tempo, o problema passa a ser de servidor. Um servidor de memória Mem0 autoalojado numa VPS resolve essa necessidade: um endpoint, vários clientes e uma memória que não depende do portátil. É importante indicar claramente o custo. Esse servidor executa um processo que pode ler os dados armazenados. Por isso, o modelo de ameaças passa a incluir a VPS e todas as pessoas que conseguem aceder à respetiva API.

Escolha com base na perda que realmente pretende evitar. Se teme o roubo do portátil ou que um fornecedor leia as suas notas, o cofre local cifrado é a opção mais forte. Se teme um agente que se esquece de tudo assim que muda de máquina, a opção é o servidor.

FAQ

O que a encriptação do Compartment protege realmente?

Protege o ficheiro. O vault é selado com XChaCha20-Poly1305, os seus keyslots são protegidos com Argon2id e os vetores de embedding também são encriptados. Assim, um disco roubado ou uma cópia de segurança antiga contém apenas bytes sem conteúdo legível. A encriptação não protege um vault desbloqueado numa máquina em execução, porque a master key permanece na RAM enquanto o vault está aberto. Também não controla o que um agente faz com uma memória depois de a receber em texto simples na sequência de uma consulta.

Se o Compartment estiver offline, as minhas memórias ficam privadas do meu fornecedor de modelos?

Apenas até serem consultadas. O armazenamento e a pesquisa são feitos sem rede, e o modelo de embedding é executado localmente. Assim, nada sai da máquina no momento da gravação. No momento da leitura, o agente recebe o conteúdo em texto simples. Se esse agente for um modelo alojado, a memória entra no prompt e é enviada para o fornecedor como o restante conteúdo da janela de contexto. Nunca armazene uma credencial como memória.

O que acontece se eu perder a passphrase do Compartment?

O vault fica irrecuperável, de forma intencional. O Compartment não gera uma seed nem uma recovery phrase e não guarda nenhuma credencial que não esteja na sua posse. Por isso, não existe nada para repor. Guarde a passphrase num gestor de palavras-passe, mantenha qualquer keyfile de 2FA fora da máquina que armazena o vault e confirme que consegue desbloquear uma cópia antes de guardar no vault algo de que sentiria falta.

Dois computadores podem partilhar o mesmo vault do Compartment?

Não em simultâneo. Um vault bloqueado é um único ficheiro portátil. O procedimento documentado consiste em bloqueá-lo, copiá-lo e depois desbloqueá-lo no outro computador com --vault. Não existe acesso concorrente. Por isso, dois computadores a escrever no mesmo ficheiro irão perder memórias. Execute um memory server quando precisar dessa funcionalidade.