Perseus Vault

Persistent Memory for AI Agents — MCP-Native. Local-First. Zero Dependencies.

Perseus Vault is a single Rust binary that gives AI agents durable memory across sessions. One binary. One file. No Docker. No Postgres. No cloud. Just persistent memory that works with any MCP host.

One-Line Install

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 ~/.mimir/data/perseus-vault.db

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 the bootstrap.sh build-from-source installer ad-hoc code-sign Perseus Vault for you. If you build the binary yourself, sign it once after each rebuild:

bash

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"

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

Connect any MCP host (Claude Desktop, Cursor, Hermes Agent, Perseus, etc.):

{
  "mcpServers": {
    "perseus-vault": {
      "command": "perseus-vault",
      "args": ["serve", "--db", "~/.mimir/data/perseus-vault.db"]
    }
  }
}

30-Second Quickstart

# 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":"mimir_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":"mimir_recall","arguments":{"query":"Hello"}}}' | perseus-vault serve --db memory.db

Works With Every MCP Client

Perseus Vault is a standard MCP stdio server — the same perseus-vault serve command works everywhere. Run perseus-vault doctor to validate your install and print this matrix locally.

Copy-paste config snippets for each: docs/clients/.

Why Perseus Vault

Perseus Vault is the only memory engine that is simultaneously MCP-native, local-first, zero-dependency, AND agent-first.

Comparison Matrix

Full comparison: Perseus Vault vs Mem0 → vs Letta → vs Zep →

Stress Test: 100K Entities

Perseus Vault handles production workloads on modest hardware:

Run it yourself: cargo test stress_100k --release -- --ignored --nocapture

Framework Integrations

Ready-to-use adapters that make Perseus Vault the default memory backend for popular AI agent frameworks:

Each adapter:

• Connects via MCP stdio subprocess (persistent session)
• Maps the framework's memory interface to Perseus Vault tools
• Comes with a README quickstart (5 minutes to working)
• Has passing tests with mocked MCP transport

Any MCP-compatible framework works with Perseus Vault directly. See Awesome Mimir for the full list.

55 MCP Tools

Entity CRUD

Search & RAG

Graph

Journal

State

Lifecycle

Quality

Vault & Federation

Metrics & Ops

CLI

# Server
perseus-vault serve --db /data/perseus-vault.db
perseus-vault serve --web --port 8767 --encryption-key ~/.mimir/secret.key
perseus-vault serve --llm-endpoint http://localhost:11434/api/generate --llm-model llama3
perseus-vault serve --transport sse --port 8787 --mcp-token my-secret-token

# Maintenance (operate directly on DB, no server needed)
perseus-vault stats          --db /data/perseus-vault.db
perseus-vault forget         --db /data/perseus-vault.db --category decision --key stale-choice --reason "superseded"
perseus-vault prune          --db /data/perseus-vault.db --category junk --min-decay 0.1 --dry-run
perseus-vault purge          --db /data/perseus-vault.db --dry-run
perseus-vault decay          --db /data/perseus-vault.db
perseus-vault reindex        --db /data/perseus-vault.db
perseus-vault vault-export   --db /data/perseus-vault.db --vault-dir ./export/
perseus-vault vault-import   --db /data/perseus-vault.db --vault-dir ./export/
perseus-vault obsidian-sync  ~/obsidian-vault/Perseus Vault/          # one-shot export to an Obsidian vault
perseus-vault obsidian-sync  ~/obsidian-vault/Perseus Vault/ --watch  # continuous sync on every memory change

# Key management
perseus-vault keygen --key-file ~/.mimir/secret.key

Flags

Database location

The canonical database path is:

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

Always pass --db (or set $MIMIR_DB_PATH) in scripts, MCP host configs, and cron/harvest jobs so every invocation targets the same file. When neither is set, Perseus Vault resolves the default in this order and uses the first that already exists (so upgraders and legacy single-user installs are picked up instead of silently starting empty):

1. ~/.mimir/data/perseus-vault.db — canonical (current name)
2. ~/.mimir/data/mneme.db — pre-rename
3. ~/.mimir/data/mimir.db — pre-rename
4. ~/mimir.db — legacy single-user install location

If none exist, it creates ~/.mimir/data/perseus-vault.db. If more than one of these exists and you did not pass --db/$MIMIR_DB_PATH, Perseus Vault prints a stderr warning naming the chosen file and the others it ignored, so an ambiguous multi-database state is visible rather than silent. Setting --db or $MIMIR_DB_PATH explicitly always wins and suppresses the warning.

Your AI Memory in Obsidian

Perseus Vault is your AI agent's long-term memory — and it doubles as your second brain. Every entity your agent remembers exports to a plain Markdown note with YAML frontmatter, so your AI's memory becomes a navigable personal knowledge base inside the tools you already use: Obsidian, Logseq, or Notion.

# Export your entire memory to an Obsidian vault as linked Markdown notes
perseus-vault obsidian-sync ~/obsidian-vault/Perseus Vault/

# Keep it live — re-export automatically on every memory change
perseus-vault obsidian-sync ~/obsidian-vault/Perseus Vault/ --watch

Open the vault in Obsidian and you get a graph of your agent's knowledge.

WikiLink backlinks. When one entity links to another (via mimir_link or a depends_on / implements / references relationship), the exported note gets a ## Links section with [[WikiLink]] backlinks that resolve natively in Obsidian's graph view:

---
id: cli-de8dfb8364b6
category: architecture
key: api
type: insight
decay_score: 0.5000
---

{"content":"axum service"}

## Links

- [[cli-99756b494c7d|database]] (depends_on)

Links resolve by entity id (notes are written as <id>.md) so they never break, and Obsidian shows the human-readable key as the link label. Open the graph view and your agent's architecture, decisions, and insights become a clickable knowledge map.

--watch polls Perseus Vault's cheap, deterministic state digest on an interval and re-exports only when memory actually changes. It naturally catches every mimir_remember write with no filesystem-watcher dependency and no coupling to the server. Tune the interval with MIMIR_SYNC_INTERVAL_SECS (default: 2s).

Other PKM tools

Unlike cloud-only "second brain" tools, Perseus Vault runs 100% local, is written in Rust, encrypts at rest with AES-256-GCM, and applies decay scoring so stale memories fade — your knowledge base stays yours and stays fresh.

Features

Semantic Search (on by default)

• Bundled, in-process embeddings — a quantized all-MiniLM-L6-v2 model (384-dim) is compiled into the binary, so dense/semantic search works with zero config and zero network: no Ollama, no API key, no model download. This is the default build (bundled-embeddings feature).
• Auto-embed on write (#271) — mimir_remember embeds each new (or content-changed) entity synchronously as it is written, using the bundled model. Single-entity embedding is deterministic and LRU-cached, so it is cheap and adds no background tasks. Embedding failures are non-fatal (logged to stderr); the write always succeeds.
• Hybrid is the default recall mode (#271) — mimir_recall(query=...) with no mode flag automatically selects hybrid (dense + keyword fused via RRF) whenever embeddings exist, and transparently falls back to fts5 keyword search when none do. No manual mimir_embed step, no flags to remember.
• mimir_semantic_search(query, limit) — a one-tool shortcut for pure dense, meaning-based search (no keyword fallback) when you just want "find things like this".
• Optional alternate embedder — to use Ollama or any OpenAI-compatible /v1/embeddings endpoint instead of the bundled model, set --llm-endpoint (and --embedding-endpoint / --llm-api-key as needed). This is entirely optional; the bundled model is used by default.
• Build a lean binary without bundled embeddings via cargo build --no-default-features — recall then defaults to keyword search unless a remote embedder is configured.

Hybrid Search internals

• FTS5 keyword search with LIKE fallback and Porter stemming expansion
• Dense vector search via cosine similarity on stored embeddings
• Reciprocal Rank Fusion (RRF) — combine keyword + vector results
• Query expansion — automatic stemming variants for broader recall

Memory Lifecycle

Perseus Vault models memory using three biomimetic layers, inspired by human memory pathways:

• World (Core): Slow-decaying, global facts about the environment.
• Episodic (Buffer): Fast-decaying, session-specific interaction history.
• Semantic (Working): Medium-decaying, general knowledge and learned concepts.

You can interact with these layers directly using the mimir_recall_layer tool or by specifying the layer parameter in mimir_remember.

• Ebbinghaus decay — memories naturally fade unless retrieved (refresh on access)
• Layer promotion — buffer → working → core based on access frequency
• Automatic archival — stale entities archive; purge to permanently delete + VACUUM
• Always-on entities — pin identity-critical memories for session injection (hard-capped under recall-first; prefer recall_when triggers)

Recall-First Context Injection

The vault is the query layer — it retrieves the few facts a turn needs instead of handing the host a standing blob to staple into every system prompt. mimir_context and perseus-vault prepare are recall-first by default:

• Relevance gating — pass query (the current task/message) and only entities whose recall_when triggers or indexed content match it are injected. No query, no topical injection: the block is a compact retrieval pointer, byte-stable across unrelated vault writes (prefix-cache friendly).
• Per-model recall budget — output is clamped to a character budget resolved from the host model: default/lean profile 1500 chars; large-window ("opus") profile 6000 chars; max_context_chars overrides both.
• Capped always-on — always_on: true still works for identity-critical facts, but the recall-first set is hard-capped (top 5) and overflow emits a warning steering you to recall_when triggers.
• Legacy opt-in — the old unconditional top-N dump is still available with mode: "always_inject" (--legacy-context for prepare), unclamped unless you pass a budget.

perseus-vault prepare --task "deploying the payments service" --model claude-sonnet-4-6
perseus-vault prepare --task "..." --max-context-chars 800     # explicit budget
perseus-vault prepare --task "..." --legacy-context            # old dump, opt-in

RAG & Embeddings

• mimir_ask — natural language Q&A over stored memories via any LLM (Ollama, OpenAI, etc.)
• mimir_embed — generate and store dense vectors via Ollama or OpenAI-compatible /v1/embeddings
• Supports single-entity and batch-category embedding

Encryption

• AES-256-GCM transparent encryption for entity body_json
• Opt-in via --encryption-key flag
• perseus-vault keygen subcommand for key generation
• FTS5 index stays plaintext for search

Web Dashboard

• Built-in Axum HTTP server (perseus-vault serve --web --port 8767)
• Dark-themed dashboard with search, entity table, vis.js graph, timeline
• Default bind: 127.0.0.1 (use --web-bind 0.0.0.0 to expose)
• Separate SQLite connection in WAL mode for concurrent reads

External Connectors

• GitHub issues connector — ingest issues/PRs by repo, rate-limit aware
• File watcher — scan directories for .md/.txt/.json files with content-hash dedup
• YAML-based connector config via --connectors-config

Multi-Transport

• stdio (default) — zero-config, works with any MCP host
• SSE — Server-Sent Events for HTTP-based MCP clients
• HTTP — REST-style MCP endpoint
• Bearer token auth — for SSE/HTTP transports

Perseus Integration

Perseus Vault is the default memory backend for Perseus:

mimir:
  enabled: true
  transport: "stdio"
  command: ["perseus-vault", "serve", "--db", "~/.mimir/data/perseus-vault.db"]
  timeout_s: 30.0
  merge_strategy: "local_first"
  fallback_to_local: true
  context_categories: ["decision", "architecture", "convention"]
  context_limit: 10

Government & Federal Procurement

Perseus Vault is built for government deployment from the ground up.

For federal buyers: See docs/federal-buyers.md for procurement information, compliance status, and deployment models (air-gapped, on-premises, classified environments).

Perseus Computing LLC is a US-owned small business. SAM.gov registration in progress. NAICS: 541715, 541511, 541512.

Privacy Policy

Perseus Vault is a local-first MCP server — it runs entirely on your machine.

Data Collection

• No data collection. Perseus Vault does not collect, transmit, or phone home any user data, usage statistics, or telemetry.
• All data remains in your local SQLite database file.

Data Usage & Storage

• All memory entities, journal entries, and state are stored locally in a SQLite database at the path you specify via --db.
• Optional AES-256-GCM encryption at rest is available — when enabled, entity bodies are encrypted before storage.
• No data is shared with Perseus Computing LLC or any third party.

Third-Party Sharing

• None. Perseus Vault is fully air-gapped by default. No API calls, no cloud services, no external network requests.
• The optional dense vector embeddings feature uses a locally-compiled model — no external embedding API is called.

Data Retention

• You control retention: entities can be soft-deleted (mimir_forget), archived (via decay/compact), or permanently purged (mimir_purge).
• No automatic off-machine backup is performed.

Contact

• Email: privacy@perseus.observer
• GitHub: Perseus-Computing-LLC/perseus-vault

License

MIT — see LICENSE.