Compartment: an encrypted offline memory vault for MCP agents

The problem Compartment targets: memory that leaks or forgets

Most agent memory setups pick one of two bad options. Either the memory lives in a cloud vector store, which means every fact an agent learns about your codebase or your client leaves the machine, or it lives in a plaintext file that any process on the host can read. Compartment's README frames the choice directly: one vault on your own computer, read and written by Claude Code, Claude Desktop, Hermes Agent, OpenClaw, Cursor, Codex and any other MCP client, with no API key, no account, no network and no telemetry.

The intended user is a developer running agents locally on a workstation. The repository's comparison table, dated 2 September 2026 in docs/COMPARISON.md, lists the memory-at-rest and network behaviour of nine other memory servers. Compartment is the only entry in that table marked as encrypting vectors as well as text. That is the claim to check first, because it is the one that separates this project from a plaintext JSONL file with a search index bolted on.

The scope is deliberately narrow. This is not a knowledge base, a RAG pipeline over documents, or a shared team memory service. It is a per-machine store of short factual claims that an agent writes during a session and reads in later ones.

One claim per memory, and why the store rejects long writes

The most interesting decision in Compartment is a constraint, not a feature. The store refuses any memory longer than 200 characters (the max_memory_chars setting) and rejects anything containing lists, headings or paragraphs, returning an error that explains how to split the text.

The README gives the reason plainly: instructions alone did not work. On a real vault, the median memory written by an agent was 1,938 characters of bulleted session summary. Prompting the model to write short facts was not enough, so the constraint moved into the storage layer. That is a reasonable engineering response, and it is also the point where Compartment stops being a drop-in replacement for anything that stores conversation summaries. If your workflow depends on dumping a session transcript into memory and searching it later, this store will reject the write, and you will have to do the splitting yourself.

Retrieval is a hybrid vector and keyword search over an in-memory index. The README states it answers in about 12 ms and returns only what is relevant. The embedding model ships inside the package, and everything on disk is encrypted, vectors included. A new vault is seeded with roughly 6,700 reference facts about hardware, operating systems, ports, encodings and shell tools; these are ordinary memories and one switch removes them from search.

Importance is assigned by fixed tiers rather than by a model: decisions and consent at 0.90, personal facts and preferences at 0.80, the user's machine and configuration at 0.75, other substantive statements at 0.55, small talk at 0.20. Importance multiplies a match score instead of adding to it, so it breaks near-ties without being able to surface a memory that did not match the query at all. That ordering property is the part worth noticing. Additive scoring is the common mistake, and it produces results that look relevant until you inspect why they ranked.

Installing Compartment and wiring it to Claude Code

The package is on PyPI and requires Python 3.11 or newer, per pyproject.toml. Install it and create a vault first, because init prompts for the passphrase and that passphrase is the only key to the vault.

pip install compartment
compartment init

The README notes that the one-click install buttons for Cursor, VS Code, LM Studio, goose and Kiro only work after that step. For Claude Code, Claude Desktop, Hermes Agent and OpenClaw, the README gives a single integration command instead of a button.

compartment integrate claude

The same command takes hermes or openclaw in place of claude. After it runs, the client should list Compartment among its MCP servers, and a new session should be able to write and recall memories without any further configuration.

A container is also supported. The Dockerfile builds a wheel in a first stage and installs it in a second, runs as uid 10001, and publishes no port because the transport is stdio. The vault is mounted from the host rather than baked into the image.

docker build -t compartment .
docker run -i --rm \
  -v "$HOME/.compartment:/data" \
  -e COMPARTMENT_PASSPHRASE \
  compartment

The Dockerfile comment is explicit that the vault should be created once on the host with compartment init before the first container run, and that the mounted directory has to be readable and writable by the container's uid.

Where Compartment is the wrong tool

The one-claim-per-memory rule is the first real limitation. It is enforced at the store, so an agent that tries to write a session summary gets an error rather than a truncated record. Any workflow built around storing documents, meeting notes or long reasoning traces will fight the store rather than use it.

The second is the single-vault model. The README describes memory as available to every agent on the machine, which is the intended behaviour and also a boundary: there is no documented namespace, project partition or per-agent isolation. If two projects on the same workstation need separate memory, the README does not describe how to get that from one vault.

The third is the passphrase. It is the only key to the vault, and the README does not document recovery, rotation or a backup path for a forgotten passphrase. That is a property of the encryption, not an oversight, but it changes the operational burden: losing the passphrase loses the memory.

Finally, the package metadata classifies the project as Development Status :: 4 - Beta. The last push was on 2026-09-06, and three releases landed in the four days before that (4.9.4, 4.9.5, 4.9.6). Frequent releases at a 4.9.x version number are a signal of active work, but the beta classifier is the project's own description of its stability.

How Compartment differs from mem0 and basic-memory

The comparison table in docs/COMPARISON.md puts the differences in concrete terms. mem0's open source version keeps memory in a vector store plus LLM-extracted facts, and its MCP server is hosted only; the table marks its encryption as not documented and notes LLM calls at runtime with telemetry on by default. Compartment makes no LLM calls at all: the embedding model is in the wheel, and the README says the network is CI-enforced to be unused at runtime. The practical consequence is that mem0 can extract and summarise facts using a model, while Compartment cannot, which is exactly why it needs the 200-character rule.

basic-memory, which is AGPL-licensed, stores Markdown plus SQLite and also has telemetry on by default according to that table. The difference in approach is the storage format itself: basic-memory's memory is human-readable files you can edit in any editor, while Compartment's is an encrypted file that only the passphrase opens. That trade is the whole point of the project, and it is also why you cannot grep the vault or recover a single memory by hand.

Graphiti and Letta take the opposite route entirely, running a server plus a graph database with an LLM key. They model relationships between entities rather than storing one claim at a time. Compartment's v4.9.4 release note mentions a graph that names everyone, so some graph view exists, but the README's memory model is flat claims with sources and dates, not an entity graph.

Licence, maintenance and upgrade cost

Compartment is Apache-2.0, which permits commercial use, modification and redistribution provided the licence and notices are preserved. The README and pyproject.toml both state the licence, and the repository carries a LICENSE file. Nothing in the repository restricts use to non-commercial contexts, and there is no separate enterprise tier described. This is a note about what the repository states, not legal advice; if you redistribute a modified wheel, read the licence text and the NOTICE requirements yourself.

The dependency set is small and mostly native: pynacl, argon2-cffi, onnxruntime, tokenizers, numpy and mcp. The last is pinned as mcp>=1.0,<3, and the comment in pyproject.toml explains why both majors are allowed. mcp 2.0, dated 2026-07-28, removed mcp.server.fastmcp in favour of mcp.server.mcpserver, and server.py imports whichever is present so the same wheel runs on either major. That is a deliberate compatibility choice, and it means an upgrade of the mcp package will not strand you on one side of the rename.

The upgrade cost that matters is the vault format. The README does not document a migration path between versions, and the release notes for 4.9.6 mention one embedding model per machine and an encoder that gives its memory back. If the embedding model changes between versions, the encrypted vectors in an existing vault were produced by the old model. The repository does not say what happens to an existing vault when the model changes, so verify that against the release notes and the vault before upgrading in place.

Editorial conclusion

Compartment fits teams that run agents on a local machine, want memory to stay there, and can accept one claim per memory and one vault per machine. It does not fit anyone who needs a shared server-side memory layer across machines, or who wants the LLM itself to decide what is worth remembering. Before adopting, verify three things: that your agent client speaks MCP over stdio, that the vault path you intend to mount in Docker is writable by uid 10001, and that the passphrase you set at compartment init is one you can store safely, because the README offers no recovery path for it.

Frequently asked questions

Official sources

1. License: Apache-2.0
2. MaxFreedomPollard/Compartment on GitHub
3. Project website
4. README
5. Releases