crewai-perseus-vault

📦 Package rename history. This distribution replaced the archived crewai-mimir project. Install crewai-perseus-vault for the current Perseus Vault integration.

Long-term, local-first, encrypted memory for CrewAI agents — as explicit, agent-callable tools.

crewai-perseus-vault wraps Perseus Vault — an open-source, MIT-licensed persistent memory engine with 40+ MCP tools, FTS5 + dense hybrid search, and optional AES-256-GCM encryption — as standard CrewAI BaseTools. Your agents get two first-class actions they can deliberately call:

• perseus_vault_remember — persist a fact, decision, insight, or note that survives across runs.
• perseus_vault_recall — search what was stored earlier.

Why tools (and not CrewAI's built-in memory)?

CrewAI ships implicit memory (auto-captured short/long-term memory) and a generic MCP adapter. crewai-perseus-vault is deliberately different: it exposes explicit, controllable memory the agent chooses to invoke, with a typed args_schema so the LLM sees exactly what each call needs. Use it when you want the agent to reason about what to remember and when to recall — backed by a durable, encryptable store you own on disk.

Prerequisite: the perseus-vault binary

The tools talk to a local perseus-vault process over JSON-RPC (MCP stdio). You need the perseus-vault binary on your PATH (or pass an absolute path).

Install it from the Perseus Vault repository (build from source, or grab a release). Verify:

perseus-vault --version

The tools spawn perseus-vault serve --db <db_path> for you — you do not start it manually.

Install

pip install crewai-perseus-vault

(or, from source: pip install -e ".[test]")

Quickstart

from crewai import Agent, Crew, Task
from crewai_perseus_vault import build_perseus_vault_tools

# One shared perseus-vault process backs both tools.
memory_tools = build_perseus_vault_tools(db_path="~/.perseus-vault/data/crew.db")

researcher = Agent(
    role="Research Analyst",
    goal="Answer questions, remembering durable facts for next time.",
    backstory="You persist key findings to long-term memory and check it before answering.",
    tools=memory_tools,
    verbose=True,
)

remember_task = Task(
    description="Remember that the project deadline is 2026-08-15. Store it under key 'project-deadline'.",
    expected_output="Confirmation the deadline was stored.",
    agent=researcher,
)

recall_task = Task(
    description="What is the project deadline? Check your long-term memory.",
    expected_output="The project deadline date.",
    agent=researcher,
)

crew = Crew(agents=[researcher], tasks=[remember_task, recall_task])
result = crew.kickoff()
print(result)

Using the tool classes directly

from crewai_perseus_vault import (
    PerseusVaultRememberTool,
    PerseusVaultRecallTool,
    PerseusVaultClient,
)

client = PerseusVaultClient(db_path="~/.perseus-vault/data/crew.db")   # one shared process
remember = PerseusVaultRememberTool(client=client)
recall = PerseusVaultRecallTool(client=client)

agent = Agent(..., tools=[remember, recall])

If you omit client, each tool lazily starts its own perseus-vault serve on first use (configurable via db_path and perseus_vault_binary).

Encryption at rest

tools = build_perseus_vault_tools(
    db_path="~/.perseus-vault/data/crew.db",
    encryption_key="~/.perseus-vault/key.b64",   # base64-encoded 32-byte AES-256-GCM key
)

Tool reference

Both return a JSON string. perseus_vault_recall returns {"query": ..., "results": [...]}.

How it works

PerseusVaultClient spawns perseus-vault serve --db <path>, performs the MCP initialize handshake, and issues id-correlated JSON-RPC requests with a per-call timeout over stdin/stdout. The client core is adapted from the proven adk-perseus-vault-memory package.

Development

pip install -e ".[test]"
pytest -q

Unit tests mock the perseus-vault subprocess, so they run with no binary installed. tests/test_smoke_real_binary.py runs an end-to-end round-trip against a real perseus-vault binary when one is found on PATH (otherwise it is skipped).

License

MIT © 2026 Perseus Computing LLC. Perseus Vault is MIT-licensed by Perseus Computing LLC.