Skip to content

Commit 2f2990b

Browse files
authored
Add Perseus Vault integration (#538)
* Add Perseus Vault logo * Add Perseus Vault integration * Expand ~ in usage snippet db_path so example is copy/paste runnable * Add binary prerequisite + runnable retrieval example to Perseus Vault page The install section omitted the separate perseus-vault engine binary that the components drive over stdio, so pip-install-only readers hit a RuntimeError. Documented the releases-page download / $PATH step and swapped the usage snippet for a write+read that returns an actual hit (verified against perseus-vault-haystack 0.1.0 and perseus-vault v2.20.2). * Expand Perseus Vault page: Agent tools + auto-memory + pipeline examples Brings the catalog entry to parity with the other Memory Store integrations: Available Classes, a Haystack Agent example (retain/recall/reflect tools), an automatic-memory wrapper example, and the pipeline example. Overview now leads with the differentiators (local-first, encrypted at rest, no cloud, no API keys). All referenced symbols ship in perseus-vault-haystack 0.2.0 on PyPI. * docs: point repo/report_issue links at canonical perseus-vault-haystack The repo was renamed from mimir-haystack; use the canonical slug so links don't rely on GitHub redirects.
1 parent fccc05f commit 2f2990b

2 files changed

Lines changed: 193 additions & 0 deletions

File tree

Lines changed: 172 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,172 @@
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.

‎logos/perseus-vault.svg‎

Lines changed: 21 additions & 0 deletions
Loading

0 commit comments

Comments
 (0)