This project has been archived by its maintainers, and is no longer receiving any updates.
pydantic-ai-perseus-vault
📦 Package rename history. This distribution replaced the archived
pydantic-ai-mimirproject. Installpydantic-ai-perseus-vaultfor the current Perseus Vault integration.
Persistent, local-first, encrypted memory for Pydantic AI agents — backed by Perseus Vault.
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), plusmimir_*andmneme_*kept for backward compatibility. This package uses the canonicalperseus_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 ~/.perseus-vault/agent.db` and exposes its memory tools.
memory = PerseusVaultToolset(db_path="~/.perseus-vault/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="~/.perseus-vault/agent.db",
encryption_key="~/.perseus-vault/key.b64", # base64-encoded 32-byte AES-256-GCM key
)
Custom binary location
memory = PerseusVaultToolset(
db_path="~/.perseus-vault/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="~/.perseus-vault/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
Metadata
Release files for pydantic-ai-perseus-vault 0.1.1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| pydantic_ai_perseus_vault-0.1.1.tar.gz | 9.5 kB | With provenance | Details for pydantic_ai_perseus_vault-0.1.1.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| pydantic_ai_perseus_vault-0.1.1-py3-none-any.whl | Python 3 | none | any | Details for pydantic_ai_perseus_vault-0.1.1-py3-none-any.whl |
Total release size: 17.3 kB
Release files / pydantic_ai_perseus_vault-0.1.1.tar.gz
| Download URL | pydantic_ai_perseus_vault-0.1.1.tar.gz |
|---|---|
| Size | 9.5 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
5508738ecbebca3cdf15d53e3e16b1e9a68bb4f6e467289227b842e91792215d
|
|
BLAKE2b-256 checksum How to use checksums |
84c1749879b663df4684e4794ae3bea8e80651b80f1ebb7731e1d5836c5a92a7
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Aug 1, 2026.
Transparency logRelease files / pydantic_ai_perseus_vault-0.1.1-py3-none-any.whl
| Download URL | pydantic_ai_perseus_vault-0.1.1-py3-none-any.whl |
|---|---|
| Size | 7.8 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
f34a68a44ee148c10c9bef85d99665f540e82d7c8e41016f94f264b889f09b7f
|
|
BLAKE2b-256 checksum How to use checksums |
22ec59fbcfac7e7c3ee2bbc9dcf33fc712d2cfeef9c096ef69d3c41c85f5c2b4
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Aug 1, 2026.
Transparency logSecurity for pydantic-ai-perseus-vault 0.1.1
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for pydantic_ai_perseus_vault-0.1.1.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Aug 1, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.