llama-index-perseus-vault

Local-first, encrypted persistent memory for LlamaIndex, backed by Perseus Vault.

Perseus Vault is an open-source (MIT) memory engine that runs entirely on your machine, stores data in an encrypted SQLite database, and exposes persistent-memory tools over the Model Context Protocol (MCP). This package wraps it as LlamaIndex agent tools and a retriever so your agents and query engines can persist and retrieve memory across runs — no external vector database, no cloud, and no API key required.

Why Perseus Vault? It is local-first and fully offline, stores everything encrypted at rest (AES-256-GCM), needs no API key or signup, and ships as a single binary with no external vector database. Your data never leaves the machine.

What's included

Prerequisite: the perseus-vault binary

These components talk to a local perseus-vault executable over stdio. Install it first:

1. Download a pre-built binary from the Perseus Vault releases page (or build from source).
2. Put it on your $PATH (so perseus-vault resolves), or pass its absolute path via perseus_vault_binary=.

Install

pip install llama-index-perseus-vault

Give an agent memory tools

from llama_index.core.agent.workflow import FunctionAgent
from llama_index.llms.openai import OpenAI

from llama_index_perseus_vault import PerseusVaultClient, create_perseus_vault_tools

client = PerseusVaultClient(db_path="~/.llama-index/perseus-vault.db", category="agent-memory")
tools = create_perseus_vault_tools(client)  # perseus_vault_remember, perseus_vault_recall

agent = FunctionAgent(
    tools=tools,
    llm=OpenAI(model="gpt-4o-mini"),
    system_prompt=(
        "You are a helpful assistant with long-term memory. "
        "Use perseus_vault_recall before answering, and perseus_vault_remember "
        "to store durable user-specific facts, preferences, or project context."
    ),
)

# await agent.run("Remember that I prefer concise Python examples.")

Use as a retriever (RAG)

from llama_index_perseus_vault import PerseusVaultClient, PerseusVaultRetriever

client = PerseusVaultClient(db_path="~/.llama-index/perseus-vault.db")
client.remember("Perseus Vault is a local-first, encrypted memory engine.")

retriever = PerseusVaultRetriever(client=client, similarity_top_k=5)
nodes = retriever.retrieve("What is Perseus Vault?")
for n in nodes:
    print(n.score, n.node.text)

Because Perseus Vault persists to an encrypted SQLite file, anything written in one run is available in any future run pointed at the same db_path.

Configuration

PerseusVaultClient accepts:

• db_path — path to the Perseus Vault SQLite database (default ~/.llama-index/perseus-vault.db).
• perseus_vault_binary — name on $PATH or absolute path to the executable (default perseus-vault).
• timeout_s — per-RPC timeout for the subprocess (default 30).
• encryption_key — optional path to an AES-256-GCM key file.

License

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