perseus vault

Give your agents memory that survives the session, so they stop re-deriving what they already learned and stop repeating past mistakes. Hybrid recall (BM25 + dense + RRF), bi-temporal history, andAES-256-GCMat rest, exposed as169 canonical MCP toolsthat work with any host. Legacymimir_/mneme_aliases were removed in the 2026-27 major release and are not counted separately.73.8% on LongMemEval's official harness(vs Zep 63.8%, Mem0 49.0%).One binary. One file. No Docker. No Postgres. No cloud.Local-first, air-gap ready, MIT.

curl -sSf https://raw.githubusercontent.com/Perseus-Computing-LLC/perseus-vault/main/scripts/install.sh | sh

That's it. Perseus Vault is installed to~/.local/bin/perseus-vault. Start it:

perseus-vault serve --db ~/.perseus-vault/data/perseus-vault.db

Encryption is enabled automatically for the default installation.The first run creates~/.perseus-vault/secret.keywith owner-only permissions and an encrypted database canary. Back up that key: it cannot be recovered. Explicit--encryption-keypaths remain supported, and existing plaintext databases are preserved for migration withperseus-vault init --rekey. Usedoctorto inspect the actual on-disk state.

macOS note (Apple Silicon).A freshly built or copied binary is SIGKILLed on first run (Killed: 9, no other output) by the OS binary policy — even with no quarantine attribute. The one-line installer and thebootstrap.shbuild-from-source installer ad-hoc code-sign Perseus Vault for you. If you build the binary yourself, sign it onceafter each rebuild:

cargo build --release cp target/release/perseus-vault ~/.local/bin/perseus-vault codesign --force --sign - ~/.local/bin/perseus-vault # required on Apple Silicon; fixes "Killed: 9"

--forcere-signs an already-signed binary (needed after every rebuild); the step is harmless on Intel macOS and unnecessary on Linux/Windows.

Then wire your MCP client(s) — and the full recall/capture loop — in one command:

perseus-vault install-client --hooks --rules

This autodetects Claude Code / Codex / Cursor (pass--client <name>for claude-desktop, hermes, windsurf, vscode, zed, or generic;--all-detectedwires every detected client), merges the MCP server registration into the client's config without clobbering anything (a.bak-perseusbackup is written first), points every client atone shared memory database, registers the session lifecycle hooks (recall injection on SessionStart, hygiene on session end — thedocs/lifecycle-hooks.mdcontract), and appends the memory usage rules toCLAUDE.md/AGENTS.md. Re-running is a no-op; add--dry-runto preview every file it would touch.

Or connect any MCP host by hand (Claude Desktop, Cursor, Hermes Agent, Perseus, etc.):

# Start Perseus Vault perseus-vault serve --db memory.db & sleep 1 # Remember a fact (via MCP JSON-RPC on stdio) echo '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"perseus_vault_remember","arguments":{"category":"demo","key":"hello","body_json":"{\"text\":\"Hello from Perseus Vault!\"}"}}}' | perseus-vault serve --db memory.db # Search for it echo '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"perseus_vault_recall","arguments":{"query":"Hello"}}}' | perseus-vault serve --db memory.db

Perseus Vault keeps three planes distinct:

- Implicit working contextis the host's current prompt, transcript, and any context block a client chooses to inject. It is ephemeral and host-owned; it is not persisted merely because Vault returned it.
- Explicit durable memoryis written by an explicitperseus_vault_remember,perseus_vault_capture,write, orcaptureoperation. The Vault server owns the SQLite record, history, journal, decay, archive, and purge lifecycle.
- Derived projectionsinclude consolidated or synthesized records and exported Markdown. They carry provenance, but they are not a replacement for the durable source records and may need separate cleanup.

Perseus Vault is a standard MCPstdioserver — the sameperseus-vault servecommand works everywhere. Runperseus-vault doctorto validate your install and print this matrix locally.