# Perseus Vault (+ perseus-ctx)

Local-first **agent memory + live workspace context** from Perseus Computing LLC. Three public pieces: Rust MCP memory server (`perseus-vault`), Python context renderer on PyPI (`perseus-ctx`), and a Hermes Agent memory-provider plugin. Fetched 2026-08-13.

Tags: product, local-first, mcp, agent-memory, hermes, rust, pypi, perseus-computing

## Summary

**Perseus Vault** is a single Rust binary that stores durable, AES-256-GCM-encrypted agent memory in one SQLite file and exposes it over MCP (stdio / SSE / HTTP). **perseus-ctx** (`pip install perseus-ctx`, current **v1.0.26**, MIT, Python ≥3.10, Beta) is a separate "resolve before context" engine: it renders `.perseus/context.md` directives into `.hermes.md` / `AGENTS.md` / `CLAUDE.md` so the assistant starts with verified workspace facts. The **Hermes plugin** ([[hermes-plugin-perseus-vault]]) makes Vault Hermes's external memory provider (prefetch, session distillation, `MEMORY.md` mirroring).

Not the same as [[hermes-agent]] (Nous runtime), [[grok-bot]] (managed cloud teammates), or [[ia-local-casa]] (home document/photo RAG).

## How the pieces connect

```
.perseus/context.md  --perseus-ctx render-->  .hermes.md / AGENTS.md / CLAUDE.md
        |                                              ^
        | @memory / perseus_vault: config              | session start
        v                                              |
perseus-vault (Rust MCP)  <---- MCP stdio/HTTP ---->  Hermes / Cursor / Claude / Codex
        ^
        | streamable-HTTP + bearer token
hermes-plugin-perseus-vault  (Hermes memory provider: prefetch, distill, AAR)
```

- Context engine **reads** live workspace (git, docker, files) and **optionally recalls** from Vault at render time.
- Vault **persists** explicit remembers/captures; it does not replace the host's current prompt.
- Plugin is optional: Vault README also shows a plain Hermes `mcp_servers.perseus_vault` local-binary block. Plugin adds provider lifecycle (prefetch every turn, distill at session end, mirror MEMORY.md). Default plugin URL is **hosted** `https://vault.perseus.observer/message` — local binary is the air-gap path.

## perseus-ctx (PyPI)

| Field | From PyPI / GitHub 2026-08-13 |
|-------|-------------------------------|
| Package | perseus-ctx |
| Version | **1.0.26** (uploaded 2026-08-01 12:30 ET; GitHub release v1.0.26 same day) |
| License | MIT (`license_expression` MIT). GitHub LICENSE: Copyright (c) 2026 **Thomas Connally**. README: MIT **does not include a patent grant** |
| Status classifier | Development Status :: 4 - Beta |
| Python | >=3.10 (classifiers 3.10–3.13) |
| Deps | pyyaml <7,>=6.0.1; extra `mcp` |
| Downloads | last day 34 / week 282 / month 1256 (PyPI HTML) |
| Repo | https://github.com/Perseus-Computing-LLC/perseus (34★, 5 forks, 0 open issues, created 2026-05-18) |
| Homepage | https://perseus.observer |
| 1.0.0 | yanked |

Install (quoted): `pip install perseus-ctx && cd your-project && perseus quickstart`

Thesis (quoted): static `CLAUDE.md` / `.cursorrules` rot; Perseus resolves `@query` / `@services` / `@waypoint` at render time so the model sees facts, not instructions to go find facts. Shell-executing directives require `PERSEUS_ALLOW_DANGEROUS=1` or they are skipped.

Hermes wiring (quoted): `perseus mcp serve --workspace /abs/path` under `mcp_servers.perseus`; tools appear as `mcp_perseus_*`. Render target priority for Hermes: `.hermes.md` → `AGENTS.md` → `CLAUDE.md`.

Legal (quoted, not verified at USPTO): "Patent Pending" provisional on the resolve-before-context pipeline; **PERSEUS™** trademark of Thomas Connally.

## Perseus Vault (GitHub)

| Field | From API / README / Cargo.toml |
|-------|--------------------------------|
| Repo | https://github.com/Perseus-Computing-LLC/perseus-vault |
| Latest **tag** | **v2.23.0** (published 2026-08-10 13:01 ET) |
| Cargo.toml on main | version = "2.23.0" (main has commits after the tag, including 2026-08-13 12:46 ET) |
| License | MIT. LICENSE: Copyright (c) 2026 **perseus** |
| Language | Rust (primary) |
| Stars / forks | 47 / 9 |
| Open issues | 2 (#916 Hermes MemConflict bench; #917 contradiction-flag design) |
| Homepage | https://perseus.observer/vault/ (PyPI family table also links /perseus-vault/) |
| Default DB | `~/.perseus-vault/data/perseus-vault.db` |
| Default key | `~/.perseus-vault/secret.key` (owner-only; "cannot be recovered") |

Headline (README): one binary, one file, no Docker, no Postgres, no cloud. Hybrid recall (BM25 + dense + RRF). Bi-temporal history (SQL:2011 valid-time + transaction-time). Bundled quantized all-MiniLM-L6-v2 embeddings (384-d) in default builds.

Encryption (quoted): AES-256-GCM on entity `body_json` for fresh installs; **FTS5 index stays plaintext**.

Canonical tools use `perseus_vault_*` (examples: `perseus_vault_remember`, `perseus_vault_recall`, `perseus_vault_context`, `perseus_vault_capture`). Legacy `mimir_*` / `mneme_*` naming is a compatibility story — README sentences disagree on whether aliases were "removed in the 2026-27 major release" or remain callable but unadvertised.

### MCP tool-count conflict (unknown)

Do not flatten these into one number. Same-day sources disagree:

- GitHub description: **122** canonical MCP tools
- README lede: **137**
- README heading: **65** Canonical MCP Tools
- Comparison matrix: **130** / **103**

Exact `tools/list` length on v2.23.0 was not measured (no binary run).

### Vendor benchmarks (first-party; not re-run)

- LongMemEval official harness: **73.8%** (plain mean of 3 runs) vs Zep 63.8% / Mem0 49.0%; **79.0%** with official CoT
- LOCOMO on Mem0's harness: Vault **2.20.2** 87.9% vs Mem0 Platform 82.2% vs Zep Cloud 33.8%

### Clients (Vault README table)

Claude Desktop, Claude Code / Hermes, Cursor, Windsurf, VS Code + Continue.dev, Zed, Codex CLI — all via `perseus-vault serve`. `perseus-vault install-client --hooks --rules` autodetects some of these. Framework adapters: LangGraph, CrewAI, AutoGen.

### Privacy (quoted for the local binary)

No telemetry, no phoning home, air-gapped by default. Optional network appears if you enable LLM endpoints, SSE/HTTP, GitHub connector, or the **hosted** plugin default. Hosted Vault privacy: **not documented on fetched pages**.

Org claims: Perseus Computing LLC, US-owned small business, SAM.gov registration in progress, NAICS 541715 / 541511 / 541512. SLSA attestation "in progress."

## Hermes plugin

Substantial enough for its own page: [[hermes-plugin-perseus-vault]].

Short version: `plugin.yaml` **v1.1.0**, MIT © 2026 Perseus Computing LLC, Python, 1★, **no GitHub releases**. `hermes plugins install Perseus-Computing-LLC/hermes-plugin-perseus-vault` then `hermes memory setup`. Requires `PERSEUS_VAULT_MCP_TOKEN`. Default URL is hosted; point `PERSEUS_VAULT_URL` at a local `perseus-vault serve --transport sse/http` if staying air-gapped. Adds prefetch, session-end distillation (cron/subagents excluded), MEMORY.md/USER.md mirroring, optional AAR (off/shadow/enforce).

Vault README memory banks (`.hermes.md` `memory_bank:`) are implemented or landing via plugin PR **#21** (still open as of fetch).

## Fit for Josh

- **Hermes:** First-party integration (MCP + dedicated memory plugin + `.hermes.md` render target). Closest match to [[hermes-agent]] / [[youtube-hermes-desktop-plugins]] / [[youtube-hermes-kanban-multi-agent]] (plugin is memory/MCP, not a Desktop UI placement).
- **Local LLM / air-gap:** Vault binary + perseus-ctx renderer match the local-first pitch. Plugin default URL does **not** — override it. Bundled embeddings avoid Ollama for Vault recall; Casa-style document RAG is a different layer ([[ia-local-casa]]).
- **Grok Bot:** Grok Bot memory lives on the shared cloud computer ([[grok-bot]]). Vault is an explicit, encrypted, user-owned store you can attach to Hermes (and, via MCP, theoretically to other hosts). No Grok Bot plugin is documented on these pages.
- **Ops cost:** extra daemon + key backup (`secret.key` unrecoverable) + token discipline. Marketing is aggressive (benchmarks, patent pending, federal-buyers page); verify claims before treating them as selection criteria.

## Unknowns

- True advertised MCP tool count.
- Hosted `vault.perseus.observer` terms, pricing, residency.
- USPTO provisional number.
- Whether main-branch commits after v2.23.0 are released.
- Perseus Ledger (optional hash-only provenance) — mentioned, not ingested.

## Related

- [[hermes-plugin-perseus-vault]]
- [[hermes-agent]]
- [[youtube-hermes-desktop-plugins]]
- [[youtube-hermes-kanban-multi-agent]]
- [[grok-bot]]
- [[grok-bot-vs-hermes-agent]]
- [[ia-local-casa]]
- raw/`perseus-vault-2026-08-13/`

## Sources

- https://pypi.org/project/perseus-ctx/
- https://pypi.org/pypi/perseus-ctx/json
- https://github.com/Perseus-Computing-LLC/perseus
- https://github.com/Perseus-Computing-LLC/perseus-vault
- https://raw.githubusercontent.com/Perseus-Computing-LLC/perseus-vault/main/README.md
- https://github.com/Perseus-Computing-LLC/hermes-plugin-perseus-vault
- https://raw.githubusercontent.com/Perseus-Computing-LLC/hermes-plugin-perseus-vault/main/README.md
- GitHub API (repos, contents, releases, issues, languages, LICENSE files) 2026-08-13