From f42cdb034d3fcc355f73d37585f922633184c40e Mon Sep 17 00:00:00 2001 From: Perseus Computing <51974392+tcconnally@users.noreply.github.com> Date: Sat, 4 Jul 2026 16:36:05 -0500 Subject: [PATCH 1/5] Add Perseus Vault logo --- logos/perseus-vault.svg | 21 +++++++++++++++++++++ 1 file changed, 21 insertions(+) create mode 100644 logos/perseus-vault.svg diff --git a/logos/perseus-vault.svg b/logos/perseus-vault.svg new file mode 100644 index 00000000..61e2ef99 --- /dev/null +++ b/logos/perseus-vault.svg @@ -0,0 +1,21 @@ + + + + + + + + + + + + + + + + + + + + + From 4772f4af5cd032f81334bcca6602c744a1357f76 Mon Sep 17 00:00:00 2001 From: Perseus Computing <51974392+tcconnally@users.noreply.github.com> Date: Sat, 4 Jul 2026 16:36:06 -0500 Subject: [PATCH 2/5] Add Perseus Vault integration --- integrations/perseus-vault-haystack.md | 68 ++++++++++++++++++++++++++ 1 file changed, 68 insertions(+) create mode 100644 integrations/perseus-vault-haystack.md diff --git a/integrations/perseus-vault-haystack.md b/integrations/perseus-vault-haystack.md new file mode 100644 index 00000000..31705e08 --- /dev/null +++ b/integrations/perseus-vault-haystack.md @@ -0,0 +1,68 @@ +--- +layout: integration +name: Perseus Vault +description: Local-first, encrypted, persistent memory for Haystack 2.x pipelines and agents — backed by Perseus Vault. +authors: + - name: Perseus Computing LLC + socials: + github: Perseus-Computing-LLC +pypi: https://pypi.org/project/perseus-vault-haystack/ +repo: https://github.com/Perseus-Computing-LLC/mimir-haystack +type: Memory Store +report_issue: https://github.com/Perseus-Computing-LLC/mimir-haystack/issues +logo: /logos/perseus-vault.svg +version: Haystack 2.0 +toc: true +--- + +**Table of Contents** + +- [Overview](#overview) +- [Installation](#installation) +- [Usage](#usage) +- [License](#license) + +## Overview + +[Perseus Vault](https://github.com/Perseus-Computing-LLC/perseus-vault) is a local-first, +single-binary memory engine for AI agents. It stores data in an encrypted (AES-256-GCM) +SQLite database with FTS5 full-text and vector search, runs fully offline, and requires no +external vector database or API keys. + +`perseus-vault-haystack` brings that persistent memory into Haystack 2.x pipelines and agents +through three components: + +- **`PerseusVaultMemoryStore`** — the encrypted document/memory store. +- **`PerseusVaultMemoryWriter`** — a pipeline component that persists documents to the store. +- **`PerseusVaultMemoryRetriever`** — a pipeline component that retrieves documents from the store. + +## Installation + +```bash +pip install perseus-vault-haystack +``` + +## Usage + +```python +from haystack import Pipeline, Document +from perseus_vault_haystack import ( + PerseusVaultMemoryStore, + PerseusVaultMemoryWriter, + PerseusVaultMemoryRetriever, +) + +store = PerseusVaultMemoryStore(db_path="~/.mimir/haystack.db") + +write_pipe = Pipeline() +write_pipe.add_component("writer", PerseusVaultMemoryWriter(memory_store=store)) +write_pipe.run({"writer": {"documents": [Document(content="Sample text.")]}}) + +read_pipe = Pipeline() +read_pipe.add_component("retriever", PerseusVaultMemoryRetriever(memory_store=store)) +result = read_pipe.run({"retriever": {"query": "What is stored?"}}) +``` + +## License + +`perseus-vault-haystack` is distributed under the terms of the MIT license. From 7964de5533e7ea5cde9551888b24c4c1011ad2c9 Mon Sep 17 00:00:00 2001 From: perseus <51974392+tcconnally@users.noreply.github.com> Date: Sat, 11 Jul 2026 08:10:53 -0500 Subject: [PATCH 3/5] Expand ~ in usage snippet db_path so example is copy/paste runnable --- integrations/perseus-vault-haystack.md | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/integrations/perseus-vault-haystack.md b/integrations/perseus-vault-haystack.md index 31705e08..b91c0b2d 100644 --- a/integrations/perseus-vault-haystack.md +++ b/integrations/perseus-vault-haystack.md @@ -45,6 +45,8 @@ pip install perseus-vault-haystack ## Usage ```python +from pathlib import Path + from haystack import Pipeline, Document from perseus_vault_haystack import ( PerseusVaultMemoryStore, @@ -52,7 +54,9 @@ from perseus_vault_haystack import ( PerseusVaultMemoryRetriever, ) -store = PerseusVaultMemoryStore(db_path="~/.mimir/haystack.db") +db_path = Path("~/.mimir/haystack.db").expanduser() +db_path.parent.mkdir(parents=True, exist_ok=True) +store = PerseusVaultMemoryStore(db_path=str(db_path)) write_pipe = Pipeline() write_pipe.add_component("writer", PerseusVaultMemoryWriter(memory_store=store)) From 484f2177cd93e9881dfc5fa7b27c8ba14f1301a8 Mon Sep 17 00:00:00 2001 From: perseus <51974392+tcconnally@users.noreply.github.com> Date: Sat, 11 Jul 2026 10:24:24 -0500 Subject: [PATCH 4/5] 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). --- integrations/perseus-vault-haystack.md | 23 ++++++++++++++++++++--- 1 file changed, 20 insertions(+), 3 deletions(-) diff --git a/integrations/perseus-vault-haystack.md b/integrations/perseus-vault-haystack.md index b91c0b2d..142df255 100644 --- a/integrations/perseus-vault-haystack.md +++ b/integrations/perseus-vault-haystack.md @@ -38,12 +38,24 @@ through three components: ## Installation +Install the Python components from PyPI: + ```bash pip install perseus-vault-haystack ``` +The components talk to a local `perseus-vault` executable over stdio, so the binary is a +separate, language-agnostic dependency. Download a pre-built binary from the +[Perseus Vault releases page](https://github.com/Perseus-Computing-LLC/perseus-vault/releases) +(or build from source) and either put it on your `$PATH` (so `perseus-vault` resolves) or pass +its absolute path via `perseus_vault_binary=`. + ## Usage +The example below writes a document into persistent memory and retrieves it back in a +separate pipeline. Because Perseus Vault persists to an encrypted SQLite file, documents +written in one run are available in any future run pointed at the same `db_path`. + ```python from pathlib import Path @@ -54,17 +66,22 @@ from perseus_vault_haystack import ( PerseusVaultMemoryRetriever, ) -db_path = Path("~/.mimir/haystack.db").expanduser() +db_path = Path("~/.perseus-vault/haystack.db").expanduser() db_path.parent.mkdir(parents=True, exist_ok=True) store = PerseusVaultMemoryStore(db_path=str(db_path)) write_pipe = Pipeline() write_pipe.add_component("writer", PerseusVaultMemoryWriter(memory_store=store)) -write_pipe.run({"writer": {"documents": [Document(content="Sample text.")]}}) +write_pipe.run( + {"writer": {"documents": [ + Document(content="Perseus Vault stores encrypted memory for Haystack agents."), + ]}} +) read_pipe = Pipeline() read_pipe.add_component("retriever", PerseusVaultMemoryRetriever(memory_store=store)) -result = read_pipe.run({"retriever": {"query": "What is stored?"}}) +result = read_pipe.run({"retriever": {"query": "encrypted memory"}}) +print(result["retriever"]["documents"]) ``` ## License From 2368c939e17d1f878ebe512152306e22ade2a65d Mon Sep 17 00:00:00 2001 From: perseus <51974392+tcconnally@users.noreply.github.com> Date: Sat, 11 Jul 2026 11:05:31 -0500 Subject: [PATCH 5/5] 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. --- integrations/perseus-vault-haystack.md | 109 ++++++++++++++++++++++--- 1 file changed, 96 insertions(+), 13 deletions(-) diff --git a/integrations/perseus-vault-haystack.md b/integrations/perseus-vault-haystack.md index 142df255..b2799c1b 100644 --- a/integrations/perseus-vault-haystack.md +++ b/integrations/perseus-vault-haystack.md @@ -1,7 +1,7 @@ --- layout: integration name: Perseus Vault -description: Local-first, encrypted, persistent memory for Haystack 2.x pipelines and agents — backed by Perseus Vault. +description: Local-first, encrypted, persistent memory for Haystack 2.x pipelines and agents — no cloud, no API keys. authors: - name: Perseus Computing LLC socials: @@ -20,21 +20,37 @@ toc: true - [Overview](#overview) - [Installation](#installation) - [Usage](#usage) + - [Available Classes](#available-classes) + - [Use with a Haystack Agent](#use-with-a-haystack-agent) + - [Automatic Memory](#automatic-memory) + - [Use in a Pipeline](#use-in-a-pipeline) - [License](#license) ## Overview [Perseus Vault](https://github.com/Perseus-Computing-LLC/perseus-vault) is a local-first, single-binary memory engine for AI agents. It stores data in an encrypted (AES-256-GCM) -SQLite database with FTS5 full-text and vector search, runs fully offline, and requires no -external vector database or API keys. +SQLite database with FTS5 full-text and vector search, runs fully offline, and requires +**no external vector database, no cloud service, and no API keys**. Your data never leaves +the machine — which makes it a fit for privacy-sensitive, air-gapped, and cost-constrained +deployments. -`perseus-vault-haystack` brings that persistent memory into Haystack 2.x pipelines and agents -through three components: +The `perseus-vault-haystack` package brings that persistent memory into Haystack 2.x as +both pipeline components and ready-made Agent tools: -- **`PerseusVaultMemoryStore`** — the encrypted document/memory store. -- **`PerseusVaultMemoryWriter`** — a pipeline component that persists documents to the store. -- **`PerseusVaultMemoryRetriever`** — a pipeline component that retrieves documents from the store. +- **`PerseusVaultMemoryStore`** — the encrypted document/memory store (`Document` and + `ChatMessage` APIs). +- **`PerseusVaultMemoryWriter`** / **`PerseusVaultMemoryRetriever`** — pipeline components + that persist and retrieve documents. +- **`create_perseus_vault_tools(...)`** — `retain_memory` / `recall_memory` / + `reflect_memory` tools so a Haystack `Agent` decides when to store and recall memory. +- **`PerseusVaultMemoryWrapper`** — automatic recall-before / retain-after memory for an + agent, without relying on tool-calling. + +More information: + +- [Perseus Vault GitHub repository](https://github.com/Perseus-Computing-LLC/perseus-vault) +- [perseus-vault-haystack package](https://github.com/Perseus-Computing-LLC/mimir-haystack) ## Installation @@ -47,14 +63,81 @@ pip install perseus-vault-haystack The components talk to a local `perseus-vault` executable over stdio, so the binary is a separate, language-agnostic dependency. Download a pre-built binary from the [Perseus Vault releases page](https://github.com/Perseus-Computing-LLC/perseus-vault/releases) -(or build from source) and either put it on your `$PATH` (so `perseus-vault` resolves) or pass -its absolute path via `perseus_vault_binary=`. +(or build from source) and either put it on your `$PATH` (so `perseus-vault` resolves) or +pass its absolute path via `perseus_vault_binary=`. No API key or account is required. ## Usage -The example below writes a document into persistent memory and retrieves it back in a -separate pipeline. Because Perseus Vault persists to an encrypted SQLite file, documents -written in one run are available in any future run pointed at the same `db_path`. +### Available Classes + +- [`PerseusVaultMemoryStore`](https://github.com/Perseus-Computing-LLC/mimir-haystack): + the encrypted store. `add_memories` / `search_memories` / `delete_all_memories` for + `Document`s, plus `write_messages` / `recall_messages` for `ChatMessage`s. +- `create_perseus_vault_tools(memory_store, ...)`: returns `retain_memory`, + `recall_memory`, and `reflect_memory` `Tool` instances for a Haystack `Agent`. Any tool + can be excluded (e.g. `include_reflect=False`). +- `PerseusVaultMemoryWrapper`: wraps an agent with automatic `auto_recall` / `auto_retain`. +- `PerseusVaultMemoryWriter` / `PerseusVaultMemoryRetriever`: pipeline components over the + store. + +### Use with a Haystack Agent + +Use the ready-made tools when you want an Agent to decide when to retrieve and store +memories. Everything runs against a local, encrypted database — no API key for memory: + +```python +from haystack.components.agents import Agent +from haystack.components.generators.chat import OpenAIChatGenerator +from haystack.dataclasses import ChatMessage + +from perseus_vault_haystack import PerseusVaultMemoryStore, create_perseus_vault_tools + +store = PerseusVaultMemoryStore(db_path="~/.perseus-vault/agent.db", category="agent-memory") +tools = create_perseus_vault_tools(store) # retain_memory, recall_memory, reflect_memory + +agent = Agent( + chat_generator=OpenAIChatGenerator(model="gpt-4o-mini"), + tools=tools, + system_prompt=( + "You are a helpful assistant with long-term memory. " + "Use recall_memory before answering, and retain_memory to store durable " + "user-specific facts, preferences, or project context." + ), +) + +agent.run(messages=[ChatMessage.from_user("Remember that I prefer concise Python examples.")]) +``` + +### Automatic Memory + +Use `PerseusVaultMemoryWrapper` when you want memory to work automatically — injecting +relevant memories into the conversation before each turn and storing the exchange after — +without relying on the model to call tools: + +```python +from haystack.components.agents import Agent +from haystack.components.generators.chat import OpenAIChatGenerator +from haystack.dataclasses import ChatMessage + +from perseus_vault_haystack import PerseusVaultMemoryStore, PerseusVaultMemoryWrapper + +store = PerseusVaultMemoryStore(db_path="~/.perseus-vault/agent.db") +memory = PerseusVaultMemoryWrapper(store, auto_recall=True, auto_retain=True) + +agent = Agent( + chat_generator=OpenAIChatGenerator(model="gpt-4o-mini"), + system_prompt="You are a helpful assistant with long-term memory.", +) + +result = memory.run(agent, messages=[ChatMessage.from_user("I prefer dark mode.")]) +print(result["last_message"].text) +``` + +### Use in a Pipeline + +Use the components when you want explicit pipeline control over when memories are stored +and retrieved. Because Perseus Vault persists to an encrypted SQLite file, documents +written in one run are available in any future run pointed at the same `db_path`: ```python from pathlib import Path