+
-
+
- 
-
- 
+
@@ -371,42 +347,61 @@ whole suite under it on Linux, macOS and Windows. The full threat model,
including what Compartment cannot protect against, is in
[SECURITY.md](SECURITY.md).
-You lock and unlock the vault yourself.
+### From the app
+
+Everything you do day to day is a button. **Unlock** asks for your
+passphrase; **Lock** closes the vault and clears every stored credential;
+**Change password** rekeys it; **Auto-lock** chooses 15, 30 or 60 idle
+minutes, or never. Compartment never generates a password, seed or recovery
+phrase, and holds no credential you do not.
+
+After an unlock the vault stays open across processes, logouts and logins
+for as long as you leave it, until a restart or power loss, until the
+auto-lock timer fires, or until you lock it. A restart or power loss always
+locks it: the unlock credential is the master key wrapped with a random
+per-boot secret that lives only in kernel memory and is never written to
+disk, so a new boot cannot open it. A copy of the credential file on its own
+is useless.
+
+### From the command line
-- **`compartment unlock`** opens the vault with your passphrase. Compartment
- never generates a password, seed or recovery phrase, and holds no
- credential you do not. (Vaults from older versions that were issued a
- recovery phrase still accept it.)
-- **`compartment lock`** closes it and clears every stored credential.
- Agents can do the same with the `memory_lock` tool.
+The same controls, plus two that only exist here:
+
+- **`compartment unlock`** and **`compartment lock`** do what the buttons do.
+ Agents can lock with the `memory_lock` tool. (Vaults from older versions
+ that were issued a recovery phrase still accept it.)
- **`compartment 2fa enable`** adds a second factor: your passphrase plus a
keyfile, for example on a USB stick. Both feed Argon2id together, so the
requirement is enforced by the cryptography, not by a setting; a stolen
vault file plus your passphrase opens nothing without the keyfile. The
keyfile's location is remembered, so unlocking feels the same while it is
present.
+- **`compartment unlock --keychain`** on macOS is an explicit opt-in that
+ survives reboots.
-After a normal unlock the vault stays open across processes, logouts and
-logins for as long as you leave it, until a restart or power loss, until the
-auto-lock timer fires (15, 30 or 60 idle minutes in the panel; `0` never),
-or until you lock it. A restart or power loss always locks it: the unlock
-credential is the master key wrapped with a random per-boot secret that
-lives only in kernel memory and is never written to disk, so a new boot
-cannot open it. A copy of the credential file on its own is useless.
-
-On macOS, `compartment unlock --keychain` is an explicit opt-in that survives
-reboots. The `memory_unlock` MCP tool exists but is off by default, because
-enabling it puts the passphrase in the model's context.
+The `memory_unlock` MCP tool exists but is off by default, because enabling
+it puts the passphrase in the model's context.
## One vault, many agents, any machine
-Claude, Hermes Agent, Cursor and the CLI can use one vault at the same
-time. Writes are serialised by an advisory file lock, every process detects
-writes by others and reloads, and each caller has its own identity and
-namespace with rw / ro / none grants, so a scratch agent can read without
-writing.
+### Without the command line
+
+Every agent on the machine uses the same vault, and none of that needs
+setting up: the app's **Connect an agent** buttons wire Claude, Hermes Agent
+and OpenClaw, and what one agent stores the others recall. Claude, Hermes
+Agent, Cursor and the CLI can use the vault at the same time: writes are
+serialised by a file lock, every process notices writes by others and
+reloads, and each agent has its own identity and namespace.
-A locked vault is one portable file:
+A locked vault is one file, `memory.vault` in the `.compartment` folder of
+your home directory. To move to another machine, lock the vault, copy the
+file there, install Compartment and unlock it in the app with your
+passphrase.
+
+### From the command line
+
+The same move, signed so the recipient can check it, plus the escape
+hatches:
```bash
compartment lock --sign
@@ -418,7 +413,8 @@ compartment --vault memory.vault unlock # your passphrase (+ keyfile if 2FA)
`compartment verify` and no credential. `export --plaintext` writes the vault
as JSONL and `import` reads it back, so you are never locked in.
[FORMAT.md](FORMAT.md) specifies the `.vault` and `.mpack` files byte by
-byte.
+byte. Per-agent namespaces take `rw`, `ro` or `none` grants in the settings
+file, so a scratch agent can read without writing.
**Memory packs** are signed, read-only bundles of curated memories
(`compartment pack build | install | remove | list | export`). They install
@@ -450,11 +446,18 @@ benchmark).
## Install
+**No command line needed.** On a Mac, download **Compartment.pkg** from the
+[latest release](https://github.com/MaxFreedomPollard/Compartment/releases/latest)
+and open it. Python, the embedding model and every dependency are inside it.
+It asks you to choose a passphrase, creates the vault, and puts Compartment
+in your menu bar, where the **Connect an agent** buttons do the rest.
+
+From the command line, on any system:
+
| | |
|---|---|
| **pip** (macOS, Linux, Windows) | `pip install compartment && compartment init` |
| **pipx / uv** | `pipx install compartment` or `uv tool install compartment`, then `compartment init` |
-| **One click** (macOS) | open **Compartment.pkg** from the [latest release](https://github.com/MaxFreedomPollard/Compartment/releases/latest). Python, the embedding model and every dependency are inside it |
| **Claude Code plugin** | after `pip install compartment && compartment init`: `/plugin marketplace add MaxFreedomPollard/Compartment`, then `/plugin install compartment@maxfreedompollard`. Codex reads the same marketplace file |
| **Docker** | `docker build -t compartment .` from a checkout; see [Wiring each agent](#wiring-each-agent) |
@@ -487,9 +490,11 @@ installed in their skills directories. Any other MCP client uses this block
## Wiring each agent
-Each of these is also a button in the app under **CONNECT AN AGENT**. On
-Windows, run the same commands in PowerShell with
-`py -m pip install compartment` in place of `pip install compartment`.
+None of this needs a terminal: the **Connect an agent** buttons in the app
+run the same steps for Claude, Hermes Agent and OpenClaw. The commands below
+are for people who prefer them, and for wiring a client the app does not
+list. On Windows, run them in PowerShell with `py -m pip install compartment`
+in place of `pip install compartment`.
**Claude (Code + Desktop)**
@@ -608,6 +613,16 @@ Global flags, before the command: `--vault PATH`, `--caller NAME`,
| `update` | upgrade in place. `--source` takes GitHub main, `--no-app` skips the restart |
| `uninstall` | remove it. The vault is kept unless you pass `--purge` |
+`compartment panel --login on | off | status` controls starting at login (on
+Linux, the applications menu entry). `init --no-app` skips the app on
+headless machines and in CI.
+
+`compartment dash` is the Dashboard button from the terminal: the whole vault
+in your browser, growth over time, the relation graph with every entity
+named, tags, per-agent counts, live search. It serves from RAM on 127.0.0.1
+only, behind a random URL token, read-only, with no outbound requests and no
+configuration. Ctrl-C closes it.
+
### The /compartmentalize skill
`compartment integrate
-
-
What the vault remembers
-
-
-
`).join("");
}
-function types(s){
- const total=s.types.reduce((a,b)=>a+b.count,0)||1;
- $("typebar").innerHTML=s.types.map(t=>
- ``).join("");
- requestAnimationFrame(()=>requestAnimationFrame(()=>{
- [...$("typebar").children].forEach(d=>d.style.width=d.dataset.w+"%");}));
- $("typelegend").innerHTML=s.types.map(t=>
- `${esc(t.label)}
- ${fmt(t.count)}${(100*t.count/total).toFixed(1)}%`).join("");
-}
function growth(s){
const c=$("growth"),dpr=devicePixelRatio||1;
const W=c.clientWidth,H=170;c.width=W*dpr;c.height=H*dpr;
@@ -694,88 +665,113 @@ def run(path: str, vault: Vault) -> None:
:'none yet';
}
function graph(g){
+ /* Every entity is drawn as a pill with its name inside: no unlabeled
+ shapes. Size and colour follow the number of relations. The server sends
+ the most connected entities (see snapshot_graph), so the picture stays
+ readable however large the vault. */
const c=$("graph"),dpr=devicePixelRatio||1;
- const W=c.clientWidth,H=400;c.width=W*dpr;c.height=H*dpr;
- c.style.height=H+"px";
+ const W=c.clientWidth,n=g.nodes.length;
+ const H=Math.max(380,Math.min(760,120+n*10));
+ c.width=W*dpr;c.height=H*dpr;c.style.height=H+"px";
const x=c.getContext("2d");x.scale(dpr,dpr);
const total=g.total_relations===undefined?g.edges.length:g.total_relations;
- $("graphcount").textContent=g.nodes.length?
- (g.edges.lengthMemories over time
@@ -629,18 +612,6 @@ def run(path: str, vault: Vault) -> None:
`${typeof n==="number"?fmt(n):n}`+
`${l}${rel.join("`:"");
}else tip.style.display="none";};
c.onmouseleave=()=>{draw(-1);tip.style.display="none";};
}
@@ -806,7 +802,7 @@ def run(path: str, vault: Vault) -> None:
setBadge("indexbadge",s.index);
setBadge("auditbadge",s.audit_ok?"audit chain verified":"AUDIT CHAIN BROKEN",
s.audit_ok?"badge ok":"badge bad");
- tiles(s);types(s);growth(s);
+ tiles(s);growth(s);
tablefill("nstable",s.namespaces.map(n=>[n.namespace,n.records]));
tablefill("agtable",s.agents.map(a=>[a.agent,a.count]));
chips("tagchips",s.tags,"tag","count");
diff --git a/src/compartment/menubar.py b/src/compartment/menubar.py
index a17d9b9..c0a0562 100644
--- a/src/compartment/menubar.py
+++ b/src/compartment/menubar.py
@@ -25,7 +25,9 @@
import shutil
import subprocess
import sys
+import threading
import time
+import webbrowser
from pathlib import Path
from . import __version__
@@ -398,6 +400,78 @@ def fetch_state(vault: str) -> dict:
return state
+#: The `compartment dash` started from the panel, if any. One per panel
+#: process: a second click reopens the same page instead of starting a second
+#: server with a second random token for the same vault.
+_DASH: dict = {"proc": None, "url": None}
+_DASH_PREFIX = "Compartment dashboard: "
+
+
+def dashboard_url(line: str) -> str | None:
+ """The URL `compartment dash` announces on its first line, or None."""
+ line = line.strip()
+ if line.startswith(_DASH_PREFIX):
+ return line[len(_DASH_PREFIX):].strip() or None
+ return None
+
+
+def _drain(proc) -> None:
+ # `dash` says a few more lines over its life; read them so it can never
+ # block on a full pipe.
+ try:
+ for _ in proc.stdout:
+ pass
+ except (OSError, ValueError):
+ pass
+
+
+def open_dashboard(vault: str) -> str | None:
+ """Open the vault's dashboard in the browser.
+
+ Starts `compartment dash` if this panel has not already started one.
+ `dash` opens the browser itself the moment it is serving, so a first
+ click needs only a started process; a later click reopens the URL it
+ announced. Returns that URL, or None when the server did not start (a
+ locked vault, for instance, which `dash` refuses).
+ """
+ proc, url = _DASH["proc"], _DASH["url"]
+ if proc is not None and proc.poll() is None and url:
+ webbrowser.open(url)
+ return url
+ try:
+ proc = subprocess.Popen(
+ [*_cli_argv(), "--vault", vault, "dash"],
+ stdout=subprocess.PIPE, stderr=subprocess.DEVNULL, text=True,
+ encoding="utf-8", errors="replace",
+ env={**os.environ, "PATH": user_path()})
+ except (OSError, subprocess.SubprocessError):
+ return None
+ _DASH["proc"], _DASH["url"] = proc, None
+ url = None
+ for line in proc.stdout: # the announcement is line one
+ url = dashboard_url(line)
+ if url:
+ break
+ if not url:
+ stop_dashboard()
+ return None
+ _DASH["url"] = url
+ threading.Thread(target=_drain, args=(proc,), daemon=True).start()
+ return url
+
+
+def stop_dashboard() -> None:
+ """End the dashboard this panel started, if it is still running."""
+ proc = _DASH["proc"]
+ _DASH["proc"], _DASH["url"] = None, None
+ if proc is not None and proc.poll() is None:
+ proc.terminate()
+ try:
+ proc.wait(timeout=3)
+ except subprocess.TimeoutExpired:
+ proc.kill()
+
+
def lock_vault(vault: str) -> bool:
return _run([*_cli_argv(), "--vault", vault, "lock"])[0] == 0
@@ -1638,8 +1712,17 @@ def newfield(placeholder):
wrap=True))
views.append(divider())
- views.append(label(f"LAST {RECENT_COUNT} MEMORIES", 10, bold=True,
- secondary=True))
+ head = label(f"LAST {RECENT_COUNT} MEMORIES", 10, bold=True,
+ secondary=True)
+ if st["exists"] and not st["locked"]:
+ # The five here are a glance; the whole vault is a page.
+ dash_b = NSButton.buttonWithTitle_target_action_(
+ "Dashboard", self, "openDashboard:")
+ dash_b.setToolTip_("Open the whole vault in your browser: "
+ "growth, the relation graph, tags, search")
+ views.append(row(head, _spacer(), dash_b))
+ else:
+ views.append(head)
if not st["exists"]:
views.append(label("nothing yet - create the vault above", 11,
secondary=True))
@@ -1881,6 +1964,10 @@ def lockNow_(self, sender):
self.unlock_note = None
self.rebuild()
+ def openDashboard_(self, sender):
+ if open_dashboard(vault_path) is None:
+ _d("the dashboard did not start")
+
def unlockNow_(self, sender):
if self.pw_field is None:
return
@@ -1915,6 +2002,7 @@ def saveChangePw_(self, sender):
self.rebuild()
def quitApp_(self, sender):
+ stop_dashboard()
NSApp.terminate_(self)
def togglePopover_(self, sender):
diff --git a/src/compartment/systray.py b/src/compartment/systray.py
index ef81d3b..50d006d 100644
--- a/src/compartment/systray.py
+++ b/src/compartment/systray.py
@@ -35,6 +35,7 @@
acquire_instance_lock, auto_lock_label,
change_passphrase, claim_first_run, create_vault,
default_vault, fetch_state, integrate, lock_vault,
+ open_dashboard, stop_dashboard,
release_instance_lock, self_check,
set_setting, starter_note, summarise, unlock_vault)
@@ -1106,6 +1107,9 @@ def work():
command=lambda: (panel.update(changing=True,
change_note=None),
refresh())).pack(side="left", padx=6)
+ ttk.Button(buttons, text="Dashboard",
+ command=lambda: open_dashboard(vault_path)
+ ).pack(side="left", padx=6)
ttk.Button(buttons, text="Quit", command=quit_app).pack(side="right")
def build(win) -> None:
@@ -1201,6 +1205,7 @@ def refresh() -> None:
place(win)
def quit_app() -> None:
+ stop_dashboard()
icon = panel.get("icon")
if icon is not None:
try:
@@ -1225,6 +1230,8 @@ def from_tray(fn):
from_tray(lambda: (lock_vault(vault_path),
panel.update(note=None),
refresh()))),
+ pystray.MenuItem("Open dashboard",
+ from_tray(lambda: open_dashboard(vault_path))),
pystray.Menu.SEPARATOR,
pystray.MenuItem("Quit", from_tray(quit_app)),
))
diff --git a/tests/test_dash.py b/tests/test_dash.py
index eb80f20..5a25403 100644
--- a/tests/test_dash.py
+++ b/tests/test_dash.py
@@ -45,16 +45,13 @@ def test_page_and_stats(served):
assert status == 200 and b"Compartment" in body and b"
")}