compartment 1.15.0__tar.gz

compartment-1.15.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Compartment Project
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

compartment-1.15.0/PKG-INFO

@@ -0,0 +1,396 @@
+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