Integrating Perseus Vault with Claude Code

Claude Code is Anthropic's CLI coding agent. It supports custom MCP servers via configuration, allowing Perseus Vault to serve as persistent long-term memory across coding sessions.

Quick Start

1. Install Perseus Vault

# One-shot bootstrap (recommended)
curl -sSL https://raw.githubusercontent.com/Perseus-Computing-LLC/perseus-vault/main/scripts/bootstrap.sh | bash

# Or build from source via cargo
cargo install --git https://github.com/Perseus-Computing-LLC/perseus-vault

Verify:

perseus-vault --version
# Expected: perseus-vault 2.14.0

2. Create a data directory

mkdir -p ~/.perseus-vault/data

3. Configure Claude Code

Claude Code reads MCP server config from .mcp.json in your project root, or from ~/.claude.json for global configuration.

Project-level (recommended — travels with the repo):

Create .mcp.json in your project root:

{
  "mcpServers": {
    "perseus-vault": {
      "command": "perseus-vault",
      "args": ["--db", "/home/YOUR_USER/.perseus-vault/data/perseus-vault.db"]
    }
  }
}

Replace /home/YOUR_USER/.perseus-vault/data/perseus-vault.db with the absolute path to your database. Do NOT use ~ — tilde expansion may not work in the MCP spawn context.

Global (applies to all projects):

Add the same mcpServers block to ~/.claude.json.

4. Verify

Launch Claude Code in your project directory:

claude

Ask:

List your available tools. Do you have access to Perseus Vault tools?

You should see perseus_vault_remember, perseus_vault_recall, perseus_vault_context, and other Perseus Vault tools in the tool list.

5. Wire the lifecycle loop (optional)

Claude Code supports SessionStart/SessionEnd hooks in .claude/settings.json that can seed each session with recalled memories and run vault hygiene when a session ends. See docs/lifecycle-hooks.md for the contract and copy-paste snippets.

Usage Patterns

Persisting decisions across sessions

I just decided to use SQLite for the caching layer instead of Redis. Remember this architectural decision.

Claude Code will call perseus_vault_remember to store the entity.

Resuming context from a previous session

What architectural decisions did I make about caching in this project?

Claude Code will call perseus_vault_recall to retrieve relevant entities.

Getting a session summary

Give me the recent memory context for this project.

Claude Code will call perseus_vault_context which returns a pre-formatted markdown block suitable for session injection.

Recording journal events

Log this as a decision: we're dropping PostgreSQL support in favor of SQLite.

Claude Code will call perseus_vault_journal to append a structured event.

Troubleshooting

Perseus Vault tools don't appear

1. Absolute paths: Ensure the --db argument uses a full absolute path. /home/user/.perseus-vault/data/perseus-vault.db not ~/.perseus-vault/data/perseus-vault.db.

2. Binary on PATH: Run which perseus-vault. If not found, install it or use the full path in the command field: /usr/local/bin/perseus-vault.

3. Database writable: The directory containing perseus-vault.db must be writable by the user running Claude Code.

4. Restart Claude Code: MCP servers are discovered at startup. After changing config, restart Claude Code with /exit and relaunch.

Permission denied on database

chmod 755 ~/.perseus-vault/data
chmod 644 ~/.perseus-vault/data/perseus-vault.db

Perseus Vault exits immediately

Run Perseus Vault manually to check for startup errors:

perseus-vault --db ~/.perseus-vault/data/perseus-vault.db
# Should hang waiting for stdin (this is correct — MCP stdio server)

# If it exits with an error, check:
# - SQLite is available (ldd $(which perseus-vault) | grep sqlite)
# - Database file is not corrupted (perseus-vault --db /tmp/test.db to try a fresh DB)

Multiple Claude Code instances

SQLite WAL mode supports concurrent readers. If you see "database is locked", another process has an exclusive lock. Kill orphaned Perseus Vault processes:

ps aux | grep '[p]erseus-vault'
kill <PID>

Advanced

Using a project-specific database

{
  "mcpServers": {
    "perseus-vault": {
      "command": "perseus-vault",
      "args": ["--db", "/home/YOU/projects/my-project/.perseus-vault/perseus-vault.db"]
    }
  }
}

This keeps project memories isolated.

Web dashboard

Perseus Vault includes an optional web dashboard for browsing entities:

perseus-vault --db ~/.perseus-vault/data/perseus-vault.db --web --port 8767

Open http://localhost:8767 in a browser. The dashboard shows entity lists, search, graph visualization, and journal events.

Encryption at rest

Encryption is enabled by default for fresh installs — the first write auto-generates ~/.perseus-vault/secret.key (owner-only on Unix) and establishes the encrypted canary; no setup step is required. An explicit key remains supported:

perseus-vault keygen --key-file ~/.perseus-vault/secret.key

Then in .mcp.json:

{
  "mcpServers": {
    "perseus-vault": {
      "command": "perseus-vault",
      "args": [
        "--db", "/home/YOU/.perseus-vault/data/perseus-vault.db",
        "--encryption-key", "/home/YOU/.perseus-vault/secret.key"
      ]
    }
  }
}

The body_json column of entities is now AES-256-GCM encrypted. FTS5 indexes remain plaintext for search, and existing plaintext databases fail closed with an init --rekey migration path (or explicit PERSEUS_VAULT_ALLOW_PLAINTEXT=1).