Metadata-Version: 2.4
Name: compartment
Version: 1.15.0
Summary: Compartment - high-security, fully offline, encrypted vector memory for AI agents (MCP)
License: MIT
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pynacl>=1.5
Requires-Dist: argon2-cffi>=23.1
Requires-Dist: onnxruntime>=1.17
Requires-Dist: tokenizers>=0.15
Requires-Dist: numpy>=1.26
Requires-Dist: mcp>=1.0
Provides-Extra: hnsw
Requires-Dist: usearch>=2.9; extra == "hnsw"
Provides-Extra: menubar
Requires-Dist: pyobjc-framework-Cocoa>=10.0; sys_platform == "darwin" and extra == "menubar"
Provides-Extra: dev
Requires-Dist: pytest>=8; extra == "dev"
Requires-Dist: usearch>=2.9; extra == "dev"
Dynamic: license-file

# Compartment

### Superior agentic memory, encrypted at rest.

Compartment is the memory your AI agents plug into. Hermes, Claude, and
OpenClaw each register in one command; anything that runs a subprocess
can use the CLI. Every agent can share the same memory - even across
different machines. Everything is local. The default install never
touches the network: the embedding model ships inside the package, so
recall works as soon as the vault is open. Every byte at rest is
AEAD-encrypted, the vectors included. The vault locks itself on restart
or power loss and unlocks once per boot.

*In intelligence work a **compartment** is a body of knowledge walled off
from everything around it, opened only by those who need it. This one is
sealed with a key only you hold, and it is kept in RAM: the whole index
lives in memory, which is what makes it both the fastest place to search and
the safest place to hold plaintext, because nothing decrypted is ever
written to disk.*

## Why Compartment

Most memory tools ask you to choose: powerful, or private, or easy. Compartment
refuses the trade, because one design decision delivers all three.

**Useful before you teach it anything.** A new vault is not empty: `compartment
init` seeds **6,718 self-contained reference facts** - hardware, operating
systems, networking and HTTP, file signatures, character encodings, shell
and Unix internals, git, regex, SQL, cryptography, dates and number
formats, physical constants, world geography, and first aid - so an offline
agent can look things up instead of guessing at them. They are ordinary
memories in `main`, editable and forgettable like anything else you store.

**Better recall.** Compartment does not just store chat, it decides what
matters. A bare "OK" answering "send this reply to the client?" is
captured as a consent decision, with its question, at the highest
priority. What you said about yourself and your machine outranks
background noise. Search is hybrid (meaning plus keywords) and, at
personal scale, mathematically exact: the top result is the true top
result, not an approximation. It learns you first, and forgets nothing.

**More secure, by construction.** Every byte at rest is authenticated-
encrypted, the embedding vectors included (most tools leave those in the
clear, and vectors can be inverted back toward text). Deletion is
cryptographic: destroy the record's key and it is gone, unrecoverable.
Tampering is detected, history is hash-chained, and the vault locks itself
on restart or power loss. It runs fully offline: a runtime guard aborts on
any network attempt, and CI proves it on three operating systems.

**Not one step harder.** One command installs it, creates the vault, and
wires your agent. No API key, no cloud account, no daemon. Unlock when you
want to use it; lock when you want it closed. By default an unlock stays
open for weeks (until restart or you lock it), like any app you leave
running. The security is free at the point of use because it falls out of
the architecture, not out of your patience: keeping plaintext off disk
forces the index into RAM, and a RAM-resident index is also the fastest
one there is. Secure and fast are the same choice here, and neither costs
you a configuration step.

## Install

**macOS - download and open.**
[**Compartment.pkg**](https://github.com/MaxFreedomPollard/Compartment/releases/latest)
from the latest release. The installer asks whether you also want the menu
bar utility, and everything - the interpreter, the embedding model, every
dependency - is inside the app, so there is nothing to install first. A
`.dmg` is there too if you would rather drag it to Applications yourself.
(The build is not signed with an Apple Developer ID yet. The `.pkg` handles
that for you; if you take the `.dmg` instead, macOS blocks the first launch
and you allow it once in System Settings → Privacy & Security → Open Anyway.)

Everywhere else, and for the CLI and MCP server on their own, it is one
command per platform - each installs the package, creates your encrypted
vault, and wires the agent:

**Claude (Code + Desktop)** - macOS / Linux:
```bash
pip install compartment && compartment init && compartment integrate claude
```
Windows (PowerShell):
```powershell
py -m pip install compartment; compartment init; compartment integrate claude
```
Registers the MCP server with the Claude Code CLI (user scope, all
projects), **imports any memories Claude Code already wrote to its own
file-based memory** (copy-only - the Markdown files are never modified;
`--no-import` opts out, `compartment import-claude` does it later), and prints
the Claude Desktop config block. The server describes
itself over the MCP handshake - it tells the model to recall before answering
and to store durable facts, credentials, names, and decisions - so Claude
treats Compartment as its memory with no hand-written instruction; `integrate
claude` also writes a managed, idempotent block into your CLAUDE.md as backup.

**Hermes** - macOS / Linux:
```bash
pip install compartment && compartment init && compartment integrate hermes
```
Windows (PowerShell):
```powershell
py -m pip install compartment; compartment init; compartment integrate hermes
```
Installs the provider plugin, wires the Hermes venv, and runs
`hermes memory setup compartment`. Compartment then appears in the
`hermes memory setup` picker beside hindsight and mem0, the only entry
marked **"no setup needed"**: no API key, no cloud account, no daemon.
Verify with `hermes memory status`. See everything Hermes remembers at
any time with **`compartment dash`** - one command, and the vault opens in
your browser (memories by kind, growth, the relation graph, live
search); Ctrl-C closes it.

**OpenClaw** - macOS / Linux:
```bash
pip install compartment && compartment init && compartment integrate openclaw
```
Windows (PowerShell):
```powershell
py -m pip install compartment; compartment init; compartment integrate openclaw
```
Writes the `mcpServers` entry into `~/.openclaw/openclaw.json` (with a
backup), then: `openclaw gateway restart` and confirm with
`openclaw mcp list`.

**Any MCP client** - macOS / Linux / Windows:

```bash
pip install compartment && compartment init
```

Then add the server to your client's MCP config (stdio transport, no API
key, no environment variables):

```json
{
  "mcpServers": {
    "compartment": {
      "command": "compartment",
      "args": ["serve"]
    }
  }
}
```

`--vault` and `--caller` are optional (`compartment --vault PATH --caller NAME
serve`); the defaults use `~/.compartment/memory.vault` with caller `user`.
Client-by-client walkthroughs in
[docs/INTEGRATIONS.md](docs/INTEGRATIONS.md).

## Measured, on an 8 GB baseline laptop

Every number below is reproducible on your machine with `compartment selftest`
and `compartment bench`.

| Metric | Measured |
|---|---|
| Fresh install → open vault, offline | seconds, zero network |
| Vector search, 20k records (HNSW) | p95 0.68 ms |
| Full hybrid search (embed + vector + BM25 + fuse) | p95 8.8 ms |
| Peak RSS, model + vault + index resident | 319 MB |
| Store one memory (embed + encrypt + fsync journal) | ~40 ms |
| Wheel size, model included | ~30 MB |
| Test suite (crypto, tamper, crash, offline, concurrency, 2FA, graph, dash, hooks, install path, bundle) | 173 tests, ~60 s |

A single network round-trip to a cloud memory API costs more than this
entire pipeline. The property that makes Compartment secure (no plaintext
index ever on disk, so all search is RAM-resident) is the same property
that makes it fast: below 20k records search is exact SIMD matrix math,
recall = 1.0 by construction; above it, SIMD HNSW at ~99% recall.

## The memory logic

Full write-path, decision math, and comparisons in
[docs/MEMORY.md](docs/MEMORY.md). The load-bearing ideas:

**Nearly everything is stored; nothing important is buried.** Only empty
turns are dropped. A bare "OK" is not noise, it is a decision: when the
agent asks *"Want me to send this reply to the client now?"* and the user
answers *"OK"*, Compartment resolves the question from the conversation and
stores
`[decision 2026-07-20] Approved (answered "OK"): Want me to send this
reply to the client now?` at the top importance tier. Asking *"did the
user say to email the client?"* later retrieves exactly that record.

**Deterministic importance tiers rank recall**: decisions/consent 0.90,
personal facts and preferences 0.80, the user's machine and configuration
0.75, other substantive statements 0.55, pleasantries 0.20 (kept, ranked
last). The fused score is
`RRF(vector) + RRF(keyword) + 0.02·cosine + 0.006·importance`: cosine
magnitude keeps the genuinely best match on top, importance settles
near-ties in favor of what matters. The agent learns the user and the
computer first, the world second, and forgets nothing.

**One memory, not two.** Agent hosts increasingly ship a memory of their
own - Claude Code keeps per-project Markdown files with an auto-loaded
index. Two memories means facts land in whichever one the model happened to
think of, and neither is complete. Compartment takes over on install: it imports
what the file memory already holds, and both the MCP handshake and the
managed CLAUDE.md block tell the model that compartment supersedes it - write
every new memory here, treat the files as a read-only archive. One vault,
encrypted, shared by every agent and project on the machine. Nothing is
deleted; the files stay exactly where they were.

**Capture that does not depend on the model.** Instructions are a request,
and a host that declares its own memory in its system prompt outranks
anything a tool says. So `compartment integrate claude` also installs a
`PostToolUse` hook: when Claude Code writes a memory file, the fact lands in
the vault whether or not the model ever thought about compartment. The hook is
additive and idempotent (your other hooks are untouched, settings.json is
backed up first), it exits successfully no matter what - a memory tool must
never break your editor - and it stays quiet when the vault is locked.
`compartment hook status | install | uninstall`, or `integrate claude --no-hooks`.

<p align="center">
  <img src="docs/images/menubar-panel.png" width="330"
       alt="The Compartment menu bar panel: vault state, the three settings, and the last five memories.">
</p>

**A menu bar app for the Mac.** Download **Compartment.pkg** from the
[latest release](https://github.com/MaxFreedomPollard/Compartment/releases/latest)
and open it - the installer asks whether you also want the menu bar utility,
and everything (Python included) is self-contained, so there is nothing to
install first. From a checkout, `pip install 'compartment[menubar]'`
then `compartment menubar` does the same thing. Either way it puts Compartment in the
status bar: click the icon and a
popover shows whether the vault is open, how much it has learned, the three
settings worth changing day to day (capture hook, whether starter facts join
searches, auto-lock), and the last five things it remembered. It holds no
vault in memory - state comes from the CLI, so an idle menu bar app costs
nothing.

Can't find the icon? A full menu bar hides whatever does not fit behind the
notch, so **open Compartment.app again** and the same panel appears as a window
instead. That works no matter how crowded the bar is, and it is what the
first launch does by itself.

**See what it just learned.** `compartment recent` lists the newest memories,
newest last, hiding the thousands of seeded starting facts so the handful
that real use produced are actually visible - and `compartment status` reports
`organic_records` beside the total, so a vault that has learned nothing can
never look busy. Same view over MCP as `memory_recent`.

**One pinned embedding space.** The model's SHA-256 is recorded in the
vault and enforced at open; cosine comparisons stay mathematically valid
forever instead of silently degrading when a model changes. Migration is
explicit: `compartment reindex --re-embed`.

**No LLM inside.** Embeddings run locally (bundled 384-dim int8 ONNX
model, <300 MB RAM). Judgment belongs to the host model you already run,
via `compartment_store` / `compartment_forget`; Compartment contributes deterministic
capture, encryption, and total recall. That split is what makes the
offline guarantee absolute and every decision reproducible. Pair Compartment
with an offline LLM and the whole agent stack can run usefully with no
network at all.

## Agent-native by design

Compartment is built to sit under agents you already use, not as a separate
app you babysit.

- **Hermes native provider** - shows up in `hermes memory setup` with
  **"no setup needed"**. Turns sync automatically; search injects only
  what is relevant, tagged as data not instructions.
- **Claude over MCP** - one `integrate claude` step registers the server
  and gives you the Desktop config block plus a managed CLAUDE.md block so memory
  is part of normal work.
- **OpenClaw and any MCP client** - same stdio server, zero open ports,
  same tools (`memory_search`, `memory_store`, `memory_forget`, lock).
- **A memory graph, not just a memory pile** - `memory_link` records
  explicit relations (who works where, what belongs to what), with
  optional validity windows; `memory_relations` answers entity,
  predicate, and as-of queries. Deterministic storage, host-model
  judgment - the same split as everything else in Compartment.
- **CLI for everything else** - scripts, cron, other agents: `compartment
  store`, `compartment search`, `compartment recent`, `compartment forget`, `compartment link`,
  `compartment relations`, `compartment import-claude`, `compartment lock`.
- **See the vault: `compartment dash`** - one command opens a local page with
  everything at a glance: how many memories of what kind, growth over
  time, the relation graph, tags, per-agent counts, live search. Served
  from RAM, 127.0.0.1-only behind a random URL token, read-only, zero
  outbound requests, zero configuration.
- **Panic lock from the agent** - `memory_lock` / `compartment lock` clears
  stored credentials instantly when you need the vault closed now.
- **One vault, many hosts** - Hermes, Claude, and the CLI can share a
  vault at once; each caller gets its own identity and namespace ACLs.
- **One memory, no sections** - the starting memories seeded at `init`
  live in `main` as ordinary records, editable and forgettable like
  anything the agent stores; older vaults reorganize automatically.

Day to day, the point is simple: the agent remembers *you*, your
decisions, and your machine - encrypted, offline, and fast - without a
cloud account.

## The lock model

You lock and unlock the vault yourself whenever you want. Manual control
is always available:

- **`compartment unlock`** - open the vault with YOUR passphrase. You choose
  it; Compartment never auto-generates a password, seed, or recovery phrase,
  and there is no credential it knows that you don't. (Vaults made by
  older versions that received an auto-generated recovery phrase still
  open with it.)
- **`compartment lock`** - close it again and clear every stored credential.
  Agents can do the same via the `memory_lock` panic tool.
- **`compartment 2fa enable`** - optional two-factor unlock: your passphrase
  (knowledge) plus a keyfile (possession - keep it on a USB stick).
  Both factors feed Argon2id together, so needing both is enforced by
  arithmetic, not a policy check; a stolen vault file plus your
  passphrase still opens nothing without the keyfile. One command, zero
  configuration: the keyfile's location is remembered, so day-to-day
  unlocking feels exactly the same while the file is present.

The default unlock mode is convenience, not a cage: after a normal
unlock, the vault stays usable across processes, logouts, and logins -
for weeks or months if you leave it that way - until the next restart or
power loss, or until you lock it yourself. Restart/power loss always
locks it: the stored credential is the master key wrapped by a key
derived from the kernel's boot timestamp plus the stable machine id; a
new boot can never open the old wrap. That is arithmetic, not a policy
check.

If you prefer reboot-surviving unlock on macOS, that is an explicit
opt-in (`compartment unlock --keychain`), with the tradeoff documented. At any
time you can lock, unlock, lock again - on your schedule.

## Security, in one paragraph

XChaCha20-Poly1305 AEAD on everything at rest including vectors
(embedding-inversion resistance) · Argon2id keyslots, LUKS-style, opened
only by the user's own passphrase (no auto-generated credentials),
optionally two-factor with a keyfile · per-record keys enabling `forget --shred`
(crypto-shred: key destroyed, content mathematically unrecoverable) ·
fsync'd sealed journal, atomic compaction, verified kill-9 crash recovery ·
hash-chained tamper-evident audit log (`compartment audit verify`) · per-caller
namespace ACLs, quarantine tier for untrusted content, signed vault
manifests · stdio MCP transport: zero open ports · runtime offline guard
that aborts on any socket attempt; CI runs the whole suite with it active
on Linux, macOS, and Windows · no telemetry, ever. Full honest threat
model, including what Compartment cannot protect against, in
[SECURITY.md](SECURITY.md).

## One vault, many agents

Hermes, Claude, and the CLI can share a single vault simultaneously:
writes are serialized by an advisory file lock, every process detects
foreign writes and reloads, and each host gets its own caller identity
and namespace with rw/ro grants. A locked vault is one portable file,
safe to move over any channel; `compartment lock --sign` seals it with an
Ed25519 manifest the recipient can verify without any credential.

```bash
compartment lock
scp ~/.compartment/memory.vault other-machine:
compartment --vault memory.vault unlock     # your passphrase (+ keyfile if 2FA)
```

## Documentation

| | |
|---|---|
| [docs/MEMORY.md](docs/MEMORY.md) | how memory is stored, what gets remembered, why the math wins |
| [docs/INTEGRATIONS.md](docs/INTEGRATIONS.md) | selecting Compartment in Hermes, OpenClaw, Claude, everything else |
| [SECURITY.md](SECURITY.md) | full threat model, honest limits |
| [FORMAT.md](FORMAT.md) | byte-level `.vault` and `.mpack` specs (language-agnostic) |
| [PACKS.md](PACKS.md) | authoring and shipping signed memory packs |
| [RELEASING.md](RELEASING.md) | cutting a release: every download, every time |

## License

MIT.

---

mcp-name: io.github.MaxFreedomPollard/compartment
