Perseus Vault

What Perseus-Computing-LLC/perseus-vault MCP server does

Perseus-Computing-LLC/perseus-vault MCP server provides a durable memory layer for AI agents. It stores explicit memories in an embedded SQLite database and makes them available through a canonical MCP interface. The project is distributed as a single Rust executable and is designed to operate locally, including in offline or air-gapped environments.

The memory model separates three kinds of information. Durable records are created by explicit remember, capture, write, or capture operations. Temporary prompts and context supplied by the host are not saved automatically. Derived context, consolidated records, and Markdown exports retain provenance but do not replace the original durable records.

How it works

The server runs with the serve subcommand and communicates with MCP clients over standard input and output. A client registers the executable and passes a database path in its MCP configuration. The same database can be shared by multiple configured clients.

Recall uses a hybrid path combining BM25-style full-text search, dense-vector search, and reciprocal-rank fusion. The perseus_vault_recall operation searches stored records, while perseus_vault_context and the prepare command produce a bounded working-context snapshot for a task. That snapshot is assembled from durable records; it is not itself a background save operation. The default context budget is 1,500 characters, with a 6,000-character option for larger-window hosts or an explicit limit.

Records also support bi-temporal history and lifecycle handling such as journaling, decay, archive, and purge. New default installations create an owner-only secret key and an encrypted database canary. Existing plaintext databases can be retained for migration with init --rekey.

Setup and configuration

Install the binary with the repository’s shell installer, which places perseus-vault in ~/.local/bin. Start the MCP server with a database path, for example:

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

The install-client --hooks --rules command can detect supported local clients, merge the server registration into their configuration, and add lifecycle hooks and memory rules. Supported client choices listed by the project include Claude Code, Codex, Cursor, Claude Desktop, Hermes, Windsurf, VS Code, Zed, and a generic option. A backup is created before configuration changes, and --dry-run previews the files that would be modified.

For manual setup, add an MCP entry whose command is perseus-vault and whose arguments are serve, --db, and the database path. Run perseus-vault doctor to inspect the on-disk state. On Apple Silicon, binaries built or copied manually must be ad-hoc signed after each rebuild; the provided installers perform that signing.

Tools and capabilities

Perseus-Computing-LLC/perseus-vault MCP server exposes operations for:

• Writing explicit durable memories with perseus_vault_remember.
• Capturing information through capture operations.
• Searching stored records with perseus_vault_recall.
• Building bounded active context with perseus_vault_context.
• Managing record history, journaling, decay, archive, and purge behavior.
• Running maintenance and inspecting installation state through the command-line interface.

The exact published v2.23.2 --no-default-features reference records 175 unique canonical tools. Tool counts are release- and profile-specific, so integrations should use the versioned reference or published metadata for an exact surface.

Limitations and notes

Vault does not automatically persist whatever appears in an agent prompt or transcript. A client must perform an explicit write or capture operation. Context returned to a host is a rolling snapshot and may need to be refreshed when the task changes.

Lifecycle hooks are optional orchestration around server-owned operations, not a second storage system. If the server or a hook is unavailable, the host should continue without injected memory and report the degraded state. Encryption keys cannot be recovered, so the generated key must be backed up. The documented LongMemEval figures measure session-level retrieval, not end-to-end question-answering accuracy.