|
| 1 | +--- |
| 2 | +layout: integration |
| 3 | +name: Perseus Vault |
| 4 | +description: Local-first, encrypted, persistent memory for Haystack 2.x pipelines and agents — no cloud, no API keys. |
| 5 | +authors: |
| 6 | + - name: Perseus Computing LLC |
| 7 | + socials: |
| 8 | + github: Perseus-Computing-LLC |
| 9 | +pypi: https://pypi.org/project/perseus-vault-haystack/ |
| 10 | +repo: https://github.com/Perseus-Computing-LLC/perseus-vault-haystack |
| 11 | +type: Memory Store |
| 12 | +report_issue: https://github.com/Perseus-Computing-LLC/perseus-vault-haystack/issues |
| 13 | +logo: /logos/perseus-vault.svg |
| 14 | +version: Haystack 2.0 |
| 15 | +toc: true |
| 16 | +--- |
| 17 | + |
| 18 | +**Table of Contents** |
| 19 | + |
| 20 | +- [Overview](#overview) |
| 21 | +- [Installation](#installation) |
| 22 | +- [Usage](#usage) |
| 23 | + - [Available Classes](#available-classes) |
| 24 | + - [Use with a Haystack Agent](#use-with-a-haystack-agent) |
| 25 | + - [Automatic Memory](#automatic-memory) |
| 26 | + - [Use in a Pipeline](#use-in-a-pipeline) |
| 27 | +- [License](#license) |
| 28 | + |
| 29 | +## Overview |
| 30 | + |
| 31 | +[Perseus Vault](https://github.com/Perseus-Computing-LLC/perseus-vault) is a local-first, |
| 32 | +single-binary memory engine for AI agents. It stores data in an encrypted (AES-256-GCM) |
| 33 | +SQLite database with FTS5 full-text and vector search, runs fully offline, and requires |
| 34 | +**no external vector database, no cloud service, and no API keys**. Your data never leaves |
| 35 | +the machine — which makes it a fit for privacy-sensitive, air-gapped, and cost-constrained |
| 36 | +deployments. |
| 37 | + |
| 38 | +The `perseus-vault-haystack` package brings that persistent memory into Haystack 2.x as |
| 39 | +both pipeline components and ready-made Agent tools: |
| 40 | + |
| 41 | +- **`PerseusVaultMemoryStore`** — the encrypted document/memory store (`Document` and |
| 42 | + `ChatMessage` APIs). |
| 43 | +- **`PerseusVaultMemoryWriter`** / **`PerseusVaultMemoryRetriever`** — pipeline components |
| 44 | + that persist and retrieve documents. |
| 45 | +- **`create_perseus_vault_tools(...)`** — `retain_memory` / `recall_memory` / |
| 46 | + `reflect_memory` tools so a Haystack `Agent` decides when to store and recall memory. |
| 47 | +- **`PerseusVaultMemoryWrapper`** — automatic recall-before / retain-after memory for an |
| 48 | + agent, without relying on tool-calling. |
| 49 | + |
| 50 | +More information: |
| 51 | + |
| 52 | +- [Perseus Vault GitHub repository](https://github.com/Perseus-Computing-LLC/perseus-vault) |
| 53 | +- [perseus-vault-haystack package](https://github.com/Perseus-Computing-LLC/perseus-vault-haystack) |
| 54 | + |
| 55 | +## Installation |
| 56 | + |
| 57 | +Install the Python components from PyPI: |
| 58 | + |
| 59 | +```bash |
| 60 | +pip install perseus-vault-haystack |
| 61 | +``` |
| 62 | + |
| 63 | +The components talk to a local `perseus-vault` executable over stdio, so the binary is a |
| 64 | +separate, language-agnostic dependency. Download a pre-built binary from the |
| 65 | +[Perseus Vault releases page](https://github.com/Perseus-Computing-LLC/perseus-vault/releases) |
| 66 | +(or build from source) and either put it on your `$PATH` (so `perseus-vault` resolves) or |
| 67 | +pass its absolute path via `perseus_vault_binary=`. No API key or account is required. |
| 68 | + |
| 69 | +## Usage |
| 70 | + |
| 71 | +### Available Classes |
| 72 | + |
| 73 | +- [`PerseusVaultMemoryStore`](https://github.com/Perseus-Computing-LLC/perseus-vault-haystack): |
| 74 | + the encrypted store. `add_memories` / `search_memories` / `delete_all_memories` for |
| 75 | + `Document`s, plus `write_messages` / `recall_messages` for `ChatMessage`s. |
| 76 | +- `create_perseus_vault_tools(memory_store, ...)`: returns `retain_memory`, |
| 77 | + `recall_memory`, and `reflect_memory` `Tool` instances for a Haystack `Agent`. Any tool |
| 78 | + can be excluded (e.g. `include_reflect=False`). |
| 79 | +- `PerseusVaultMemoryWrapper`: wraps an agent with automatic `auto_recall` / `auto_retain`. |
| 80 | +- `PerseusVaultMemoryWriter` / `PerseusVaultMemoryRetriever`: pipeline components over the |
| 81 | + store. |
| 82 | + |
| 83 | +### Use with a Haystack Agent |
| 84 | + |
| 85 | +Use the ready-made tools when you want an Agent to decide when to retrieve and store |
| 86 | +memories. Everything runs against a local, encrypted database — no API key for memory: |
| 87 | + |
| 88 | +```python |
| 89 | +from haystack.components.agents import Agent |
| 90 | +from haystack.components.generators.chat import OpenAIChatGenerator |
| 91 | +from haystack.dataclasses import ChatMessage |
| 92 | + |
| 93 | +from perseus_vault_haystack import PerseusVaultMemoryStore, create_perseus_vault_tools |
| 94 | + |
| 95 | +store = PerseusVaultMemoryStore(db_path="~/.perseus-vault/agent.db", category="agent-memory") |
| 96 | +tools = create_perseus_vault_tools(store) # retain_memory, recall_memory, reflect_memory |
| 97 | + |
| 98 | +agent = Agent( |
| 99 | + chat_generator=OpenAIChatGenerator(model="gpt-4o-mini"), |
| 100 | + tools=tools, |
| 101 | + system_prompt=( |
| 102 | + "You are a helpful assistant with long-term memory. " |
| 103 | + "Use recall_memory before answering, and retain_memory to store durable " |
| 104 | + "user-specific facts, preferences, or project context." |
| 105 | + ), |
| 106 | +) |
| 107 | + |
| 108 | +agent.run(messages=[ChatMessage.from_user("Remember that I prefer concise Python examples.")]) |
| 109 | +``` |
| 110 | + |
| 111 | +### Automatic Memory |
| 112 | + |
| 113 | +Use `PerseusVaultMemoryWrapper` when you want memory to work automatically — injecting |
| 114 | +relevant memories into the conversation before each turn and storing the exchange after — |
| 115 | +without relying on the model to call tools: |
| 116 | + |
| 117 | +```python |
| 118 | +from haystack.components.agents import Agent |
| 119 | +from haystack.components.generators.chat import OpenAIChatGenerator |
| 120 | +from haystack.dataclasses import ChatMessage |
| 121 | + |
| 122 | +from perseus_vault_haystack import PerseusVaultMemoryStore, PerseusVaultMemoryWrapper |
| 123 | + |
| 124 | +store = PerseusVaultMemoryStore(db_path="~/.perseus-vault/agent.db") |
| 125 | +memory = PerseusVaultMemoryWrapper(store, auto_recall=True, auto_retain=True) |
| 126 | + |
| 127 | +agent = Agent( |
| 128 | + chat_generator=OpenAIChatGenerator(model="gpt-4o-mini"), |
| 129 | + system_prompt="You are a helpful assistant with long-term memory.", |
| 130 | +) |
| 131 | + |
| 132 | +result = memory.run(agent, messages=[ChatMessage.from_user("I prefer dark mode.")]) |
| 133 | +print(result["last_message"].text) |
| 134 | +``` |
| 135 | + |
| 136 | +### Use in a Pipeline |
| 137 | + |
| 138 | +Use the components when you want explicit pipeline control over when memories are stored |
| 139 | +and retrieved. Because Perseus Vault persists to an encrypted SQLite file, documents |
| 140 | +written in one run are available in any future run pointed at the same `db_path`: |
| 141 | + |
| 142 | +```python |
| 143 | +from pathlib import Path |
| 144 | + |
| 145 | +from haystack import Pipeline, Document |
| 146 | +from perseus_vault_haystack import ( |
| 147 | + PerseusVaultMemoryStore, |
| 148 | + PerseusVaultMemoryWriter, |
| 149 | + PerseusVaultMemoryRetriever, |
| 150 | +) |
| 151 | + |
| 152 | +db_path = Path("~/.perseus-vault/haystack.db").expanduser() |
| 153 | +db_path.parent.mkdir(parents=True, exist_ok=True) |
| 154 | +store = PerseusVaultMemoryStore(db_path=str(db_path)) |
| 155 | + |
| 156 | +write_pipe = Pipeline() |
| 157 | +write_pipe.add_component("writer", PerseusVaultMemoryWriter(memory_store=store)) |
| 158 | +write_pipe.run( |
| 159 | + {"writer": {"documents": [ |
| 160 | + Document(content="Perseus Vault stores encrypted memory for Haystack agents."), |
| 161 | + ]}} |
| 162 | +) |
| 163 | + |
| 164 | +read_pipe = Pipeline() |
| 165 | +read_pipe.add_component("retriever", PerseusVaultMemoryRetriever(memory_store=store)) |
| 166 | +result = read_pipe.run({"retriever": {"query": "encrypted memory"}}) |
| 167 | +print(result["retriever"]["documents"]) |
| 168 | +``` |
| 169 | + |
| 170 | +## License |
| 171 | + |
| 172 | +`perseus-vault-haystack` is distributed under the terms of the MIT license. |
0 commit comments