Compartment: Offline Encrypted Agent Memory

Wetin Compartment dey do differently

Compartment na agent memory store wey dey keep every record encrypted for the machine wey create am, and e no dey talk to any network service. Two things dey separate am from the rest of the agent memory field. The vault na one sealed file wey na only your passphrase fit open, and the embedding step dey run locally. So, dem no dey send the text of any memory anywhere to turn am into vector. Version 4.6.0 publish on 10 August 2026, the licence na Apache-2.0, and you fit install am from PyPI.

This na claim about threat model, so this guide dey treat am that way. Encryption at rest plus offline design protect specific list of things. Dem leave other things open, and na for that gap day two problems dey happen.

This guide follow the project's own documentation and release notes, wey dem read on 11 August 2026. Compartment dey ship with desktop application, menu bar item for macOS, and notification area icon for Windows, together with its command line tool. Also, automated container no fit drive passphrase prompt. Treat wetin follow as documented behaviour, no be behaviour we measure here. Run am for spare machine before you trust am with any real data.

Wetín encryption at rest really dey protect

The vault dey sealed with XChaCha20-Poly1305, wey be AEAD (authenticated encryption with associated data) cipher. The keyslots wey dey hold master key dey wrapped with Argon2id, wey be password hashing function wey dem build to dey slow and need plenty memory. Two things follow from this. Copy of the file for stolen disk, old backup, or support ticket na only bytes; e no be anything more. And if even one bit change, authentication go fail when the file open. So corruption go show as clear error instead of wrong answer.

The embedding vectors dey encrypted too, and this matter pass as e fit sound. Embedding no be hash. Research on embedding inversion don recover readable pieces of the original text from the vector alone. So plaintext vector index wey dey beside encrypted database almost be like leaving the database open. Compartment no write plaintext index to disk.

Deletion na real deletion. Every record get im own key, and compartment forget --shred destroy that key. So nobody fit decrypt the ciphertext wey remain, including you. Compare am with row wey you delete from database file. That row usually still dey readable for free pages until something overwrite am.

Offline na the other half. Nothing dey upload, so no vendor account dey hold your memories, and no API key dey wey fit leak dem.

Wetin Compartment no protect

The claim stop for vault boundary, and that boundary dey nearer than e look.

Agent dey read plaintext. Recall decrypt memory and hand the text to agent. If that agent na hosted model, the memory go travel to model provider inside the next prompt, exactly like every other thing for context window. Encryption at rest protect the file. E no protect the retrieval. So the rules for keeping secrets out of AI agents no relax because the store dey encrypted: password wey you save as memory na password wey you arrange make e paste into prompt automatically.

Unlocked vault for running machine dey open. The project's security notes talk this one clearly. While vault dey unlocked, master key and working set dey RAM, Python no fit guarantee say buffer don wipe, and swap or hibernation image fit write that memory to disk. Malware wey dey run as your user no need break the cipher, because e fit ask the vault wey already dey unlocked.

Caller identity na declarative. You fit restrict namespaces per caller, but caller name dey come from host process, so host wey lie about im name go receive the grants wey e claim. Namespace permissions na organisation, no be security boundary against hostile local program.

Shredding no fit reach copies. forget --shred destroy the key inside current file. Backup wey dem take before the shred still get that record, and e still open with the passphrase of that day.

Weak passphrase end the matter. Argon2id make every guess expensive. E no fit save passphrase wey dey inside word list.

Install Compartment from one pinned release

Compartment need Python 3.11 or newer. The project dey move fast, with thirty versions for PyPI by 10 August 2026, so pin the version instead of taking any version wey dey current on the day you install am.

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

compartment --version suppose print the version wey you pin. If shell answer compartment: command not found, install directory no dey for your PATH, and for most systems, that directory na ~/.local/bin. pipx install compartment==4.6.0 and uv tool install compartment==4.6.0 avoid this by managing their own paths.

compartment init go ask for passphrase two times and e no go echo anything. That passphrase na the only key. The project no generate password or recovery phrase. This one na deliberate: software no hold any credential wey you no get.

Check the result before you connect anything to am.

compartment status

Healthy vault go report say e don unlock. If e report locked, run compartment unlock and enter the passphrase. Restart go lock am again, because the credential wey keep am open depend on secret wey e create for each boot. For macOS, compartment unlock --keychain make the credential survive reboot by storing am for the system keychain.

Wey the data really dey

The default vault na ~/.compartment/memory.vault. To point am go another place, use --vault PATH for any command, or set COMPARTMENT_VAULT environment variable.

That one file na the complete store. E dey open with header wey hold the format version and the Argon2id keyslots. After that na the sealed payload, then journal entries wey dem append as new memories dey arrive. Each journal entry get length and CRC (cyclic redundancy check) for that length. So if crash cut the write short, system go recognise am as truncated entry instead of reading am as data. Compaction serialise the vault, write temporary file, run fsync on am, then rename am into place. This mean say reader no go ever see vault wey write don stop halfway.

The useful part be say: backup script only need copy exactly one path. The awkward part be say: you no fit grep am, and you no fit repair am with text editor. If you want memory wey you fit read with cat and commit to git, Memmy plain local memory files dey offer the opposite trade-off. Both options make sense, depending on whether na stolen laptop or broken tool be the thing wey worry you.

compartment uninstall remove the software but keep the vault. Pass --purge only when na exactly wetin you mean.

Wey wire am enter agent

One command go wire supported client.

compartment integrate --list
compartment integrate claude

For Claude Code, command go write MCP (model context protocol) server entry and PostToolUse hook inside ~/.claude/settings.json, after e back up the file first. E go install /compartmentalize skill under ~/.claude/skills/, and add managed block to ~/.claude/CLAUDE.md wey tell agent say Compartment don supersede the file-based memory wey e dey use. Confirm both sides:

compartment hook status
compartment recent

To register the server by hand instead:

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

Any other MCP-capable host fit use the same server with its own caller name.

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

Give each host different --caller value. Na this label audit log dey record, and na the key wey namespace grants dey write against. If dem share name, both things no go useful.

If Claude Code don already dey write facts to its own memory files, compartment import-claude --dry-run go show wetin go move before anything moves. Read wetin Claude Code dey keep for its memory files first, because importing notes from one year enter fresh vault na how memory store dey fill with things wey nobody mean to keep.

Local vault dey fast how?

Na these figures the project publish for vault wey person fit use by himself. Dem come from the project documentation, no be test we run here.

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

To store one memory, dem quote 40 ms. Vector search across twenty thousand records dey take 0.68 ms for 95th percentile. The project reason for keeping memory local na simple arithmetic: one network round trip to hosted memory API often cost pass the 11.6 ms median wey full hybrid search take here.

Two design details explain the search figures. If records no reach twenty thousand, Compartment dey compare the query with every vector. So recall exact by design, instead of approximate. If records pass that number, e switch to HNSW (hierarchical navigable small world), an approximate index wey trade small recall for more speed. The vault still dey record the SHA-256 hash of the embedding model, and e no go open with another model. This na because vectors from two different models fit compare without any error showing, but the scores wey come back no get useful meaning.

Backups, and the copy wey you fit still open next year

One locked vault na one portable file, so to move am na to copy am.

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

Lock am first. If you copy while the agent dey write, e fit catch journal entry for middle of append. CRC framing fit make reader skip that trailing fragment, but the memory wey dey inside am don lost. compartment lock --sign seal the file with Ed25519 manifest, so the receiving machine fit verify say the copy arrive intact without holding the passphrase.

Because the file don already seal, ordinary cloud storage dey acceptable to store am. Na here encryption at rest dey pay you back directly: backup target no go ever see any memory.

Two warnings. Shredding no reach backups, so record wey you crypto shredded today still dey readable for last week's copy by anybody wey get last week's passphrase. And compartment export --plaintext dey write the whole vault unencrypted, wey correct for migrating go another thing but wrong file to leave for ~/Downloads.

Keep few copies and put date for dem. Memory store go turn liability once nobody dey prune am. Na this be the reason for why stale agent memories dey quietly poison retrieval.

How to handle key, rotate am, and use second factor

compartment rekey
compartment 2fa enable
compartment 2fa status

rekey dey change the passphrase by rewrapping the master key for the keyslot of the current file. Old copies still get the old passphrase, because dem bytes don seal before the change, and nothing go back edit dem. Rotate the copies too, or accept say retired passphrase still fit open something.

2fa enable dey add keyfile as second factor. E join with the passphrase during key derivation, so you need both before you fit open the vault. This one also double the things wey fit loss. Keep the keyfile away from the machine wey dey hold the vault.

For scripts and CI (continuous integration), passphrase fit come through the COMPARTMENT_PASSPHRASE environment variable, while unlock --passphrase-stdin dey read am from pipe. Prefer the pipe. Other processes wey the same user own fit read environment variable, and e often dey enter job logs.

The audit history use hash chain, and compartment audit verify dey go through am and report the first broken link. Run am after any restore, because na that time silently truncated file go show itself.

Wetin go happen if you lose the passphrase

Nothing go happen, and na so dem design am. No reset, no recovery phrase, and no address to write, because no copy of the key dey outside your memory and your optional keyfile. The vault go remain file wey contain bytes wey look random.

So the recovery plan no be plan for the vault. Na plan for the passphrase. Save am for password manager the day wey you run compartment init. Then test am: lock the vault, unlock am with only wetin you write down, and allow agent start to fill am after e work.

Compartment or memory server

Compartment na single machine by design. To share am na to copy the locked file, or export and import am. No two writers fit work at the same time. So, if laptop and workstation point to one file, dem go overwrite each other work.

When plenty machines need the same memory at the same time, na server problem be that. Self-hosted Mem0 memory server for VPS fit solve am: one endpoint, many clients, and memory wey outlive the laptop. But make we talk the cost plainly. That server dey run process wey fit read the data e stores. So, your threat model now include the VPS and everybody wey fit reach its API.

Choose based on the loss wey you really fear. If na stolen laptop or vendor wey dey read your notes, encrypted local vault na the stronger answer. If na agent wey dey forget everything immediately you change machine, server na the answer.

FAQ

Wetin Compartment encryption really dey protect?

E dey protect the file. XChaCha20-Poly1305 seal the vault, Argon2id wrap the keyslots, and e encrypt the embedding vectors too. So if person steal the disk or old backup, na bytes wey nobody fit read go remain. E no protect unlocked vault for machine wey dey run, because the master key dey RAM while the vault open. E also no control wetin agent do with memory after recall return am as plaintext.

If Compartment dey offline, my memories private from my model provider?

Na only until dem recall am. Storing and searching happen without network, and embedding model run locally, so nothing comot from the machine when e dey write. When dem read am, agent receive plaintext. If that agent na hosted model, the memory enter the prompt and go to provider like the rest of the context window. No ever store credential as memory.

Wetin go happen if I lose my Compartment passphrase?

The vault no fit recover, and na so e suppose be. Compartment no generate seed or recovery phrase, and e no hold any credential wey you no hold, so nothing dey to reset. Put the passphrase for password manager. Keep any 2FA keyfile away from the machine wey store the vault. Confirm say you fit unlock a copy before the vault hold anything wey you go miss.

Two machines fit share one Compartment vault?

No be at the same time. Locked vault na one portable file. The documented method na to lock am, copy am, then unlock am for the other machine with --vault. Concurrent access no dey, so if two machines write to one file, dem go lose memories. Run a memory server when you need that.