pydantic-ai-perseus-vault 0.1.0

Perseus Vault persistent, local, encrypted memory for Pydantic AI agents — exposed as a Toolset.

pydantic-ai-perseus-vault

Persistent, local-first, encrypted memory for Pydantic AI agents — backed by Perseus Vault (formerly "Mimir"/"Mneme").

PerseusVaultToolset gives a Pydantic AI Agent durable memory that survives across runs and processes. Your agent can perseus_vault_remember facts and perseus_vault_recall them later, with full-text + semantic search, all stored in a local SQLite database that never leaves the machine (and can be AES-256-GCM encrypted at rest).

Tool names. Perseus Vault exposes its MCP tools under three aliased prefixes — perseus_vault_* (canonical), plus mimir_* and mneme_* kept for backward compatibility. This package uses the canonical perseus_vault_* names throughout.

Why this package?

Pydantic AI already speaks the Model Context Protocol natively via MCPToolset, and Perseus Vault is an MCP stdio server — so you could wire them together by hand. PerseusVaultToolset is the ergonomic shortcut: it subclasses MCPToolset, resolves the perseus-vault binary, manages the database path, optionally enables encryption, and spawns perseus-vault serve for you. One line instead of a transport assembly. Because it is an MCPToolset, every Pydantic AI MCP feature (tool caching, include_instructions, process_tool_call, tool filtering/renaming) works unchanged.

Prerequisite: the perseus-vault binary

Perseus Vault is a single self-contained binary. Install it and make sure it is on your PATH:

# One-line install (installs to ~/.local/bin/perseus-vault):
curl -sSf https://raw.githubusercontent.com/Perseus-Computing-LLC/perseus-vault/main/scripts/install.sh | sh

# ...or build from source (Rust toolchain required):
git clone https://github.com/Perseus-Computing-LLC/perseus-vault
cd perseus-vault && cargo build --release
# then put target/release/perseus-vault on your PATH

# ...or download a prebuilt binary from the releases page:
#   https://github.com/Perseus-Computing-LLC/perseus-vault/releases

Verify:

perseus-vault --version

Install

pip install pydantic-ai-perseus-vault

This pulls in pydantic-ai-slim[mcp]. If you already use the full pydantic-ai, that satisfies the dependency too.

Usage

import asyncio

from pydantic_ai import Agent
from pydantic_ai_perseus_vault import PerseusVaultToolset

# Spawns `perseus-vault serve --db ~/.mimir/agent.db` and exposes its memory tools.
memory = PerseusVaultToolset(db_path="~/.mimir/agent.db")

agent = Agent(
    "openai:gpt-5",
    toolsets=[memory],
    instructions=(
        "You have a persistent memory. Use perseus_vault_remember to store "
        "durable facts about the user, and perseus_vault_recall to look them "
        "up before answering."
    ),
)


async def main() -> None:
    async with agent:  # opens the MCP connection for the agent's lifetime
        await agent.run("My favourite colour is teal. Please remember that.")
        result = await agent.run("What's my favourite colour?")
        print(result.output)  # -> teal


asyncio.run(main())

Encryption at rest

memory = PerseusVaultToolset(
    db_path="~/.mimir/agent.db",
    encryption_key="~/.mimir/key.b64",  # base64-encoded 32-byte AES-256-GCM key
)

Custom binary location

memory = PerseusVaultToolset(
    db_path="~/.mimir/agent.db",
    perseus_vault_binary="/opt/perseus-vault/bin/perseus-vault",  # explicit path; otherwise resolved from PATH
)

Passing through MCPToolset options

Any MCPToolset keyword is forwarded:

memory = PerseusVaultToolset(
    db_path="~/.mimir/agent.db",
    id="perseus-vault-memory",  # stable id (needed for Temporal/DBOS durability)
    include_instructions=True,  # inject Perseus Vault's server instructions into the agent
    cache_tools=True,
)

What tools does the agent get?

All of Perseus Vault's MCP tools (exposed under the canonical perseus_vault_* prefix), including:

Tool	Purpose
perseus_vault_remember	Store a durable memory (category, key, body, tags)
perseus_vault_recall	Hybrid full-text + semantic search over memories
perseus_vault_get_entity	Fetch a specific memory by id/key
perseus_vault_timeline	Time-ordered view of memories
perseus_vault_forget / perseus_vault_supersede	Delete or replace memories
perseus_vault_link / perseus_vault_traverse	Relate and walk between memories
...	and many more (stats, journaling, vault import/export, etc.)

The exact set depends on your installed Perseus Vault version.

Development

pip install -e ".[test]"
pytest

The unit tests mock the subprocess and run with no perseus-vault binary installed. A real end-to-end smoke test runs automatically when a perseus-vault binary is on PATH, and is skipped otherwise.

License

MIT © 2026 Perseus Computing LLC