Metadata-Version: 2.4
Name: llama-index-perseus-vault
Version: 0.1.0
Summary: Perseus Vault persistent, local, encrypted memory for LlamaIndex — agent tools and a retriever backed by the Perseus Vault MCP engine.
Project-URL: Homepage, https://github.com/Perseus-Computing-LLC/llama-index-perseus-vault
Project-URL: Repository, https://github.com/Perseus-Computing-LLC/llama-index-perseus-vault
Project-URL: Bug Tracker, https://github.com/Perseus-Computing-LLC/llama-index-perseus-vault/issues
Project-URL: Perseus Vault, https://github.com/Perseus-Computing-LLC/perseus-vault
Author-email: Perseus Computing LLC <hermes@perseus.observer>
License: MIT
License-File: LICENSE
Keywords: agents,llama-index,llamaindex,llm,mcp,memory,perseus-vault,retriever
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.10
Requires-Dist: llama-index-core>=0.11.0
Provides-Extra: test
Requires-Dist: pytest>=7.0; extra == 'test'
Description-Content-Type: text/markdown

# llama-index-perseus-vault

Local-first, encrypted **persistent memory for [LlamaIndex](https://www.llamaindex.ai/)**, backed by [Perseus Vault](https://github.com/Perseus-Computing-LLC/perseus-vault) (formerly "Mimir"/"Mneme").

Perseus Vault is an open-source (MIT) memory engine that runs entirely on your machine, stores data in an encrypted SQLite database, and exposes 50+ 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

| Class / function | Role |
| --- | --- |
| `PerseusVaultClient` | Owns the `perseus-vault` subprocess; `remember` / `recall` / `call_tool`. |
| `create_perseus_vault_tools(client)` | Returns `perseus_vault_remember` / `perseus_vault_recall` `FunctionTool`s for a LlamaIndex agent. |
| `PerseusVaultRetriever` | A `BaseRetriever` returning `NodeWithScore`s for query engines / RAG. |

## 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](https://github.com/Perseus-Computing-LLC/perseus-vault/releases) (or build from source).
2. Put it on your `$PATH` (so `perseus-vault` resolves), **or** pass its absolute path via `perseus_vault_binary=`.

## Install

```bash
pip install llama-index-perseus-vault
```

## Give an agent memory tools

```python
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)

```python
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 (formerly Mimir/Mneme) is also MIT-licensed.
