perseus-vault-haystack 0.1.0__py3-none-any.whl

perseus_vault_haystack/__init__.py

@@ -0,0 +1,27 @@
+# SPDX-FileCopyrightText: 2026 Perseus Computing LLC
+#
+# SPDX-License-Identifier: MIT
+
+"""perseus-vault-haystack — Perseus Vault persistent memory for Haystack 2.x.
+
+Perseus Vault (https://github.com/Perseus-Computing-LLC/perseus-vault) is an
+open-source (MIT) local-first, encrypted persistent memory engine with 40+ MCP
+tools. This package exposes Perseus Vault to Haystack 2.x pipelines as a memory
+store plus two ``@component`` adapters.
+
+Requirements:
+    A ``perseus-vault`` binary must be on ``$PATH`` or passed explicitly via
+    ``perseus_vault_binary``. Download from:
+    https://github.com/Perseus-Computing-LLC/perseus-vault/releases
+"""
+
+from .components import PerseusVaultMemoryRetriever, PerseusVaultMemoryWriter
+from .memory_store import PerseusVaultMemoryStore
+
+__all__ = [
+    "PerseusVaultMemoryStore",
+    "PerseusVaultMemoryWriter",
+    "PerseusVaultMemoryRetriever",
+]
+
+__version__ = "0.1.0"

perseus_vault_haystack/_client.py

@@ -0,0 +1,237 @@
+# SPDX-FileCopyrightText: 2026 Perseus Computing LLC
+#
+# SPDX-License-Identifier: MIT
+
+"""Low-level JSON-RPC (MCP stdio) client for the Perseus Vault memory engine.
+
+Perseus Vault (https://github.com/Perseus-Computing-LLC/perseus-vault) is an
+open-source (MIT) local-first, encrypted persistent memory engine exposing 40+
+MCP tools. It runs as ``perseus-vault serve --db <path>`` and speaks JSON-RPC 2.0
+over stdin/stdout (the MCP stdio transport).
+
+This client spawns the ``perseus-vault`` binary and provides a thin, thread-safe
+``call_tool`` method. It is adapted from the proven client core in
+``Perseus-Computing-LLC/adk-perseus-vault-memory``.
+"""
+
+from __future__ import annotations
+
+import atexit
+import json
+import os
+import queue
+import shutil
+import subprocess
+import threading
+import time
+
+
+class PerseusVaultClient:
+    """Thread-safe JSON-RPC client over a ``perseus-vault`` stdio subprocess.
+
+    The client lazily spawns the subprocess on first use (``start``), performs
+    the MCP ``initialize`` handshake, and exposes ``call_tool`` to invoke any
+    Perseus Vault MCP tool. The subprocess is terminated at interpreter exit.
+    """
+
+    def __init__(
+        self,
+        db_path: str = "~/.mimir/haystack.db",
+        perseus_vault_binary: str = "perseus-vault",
+        timeout_s: float = 30.0,
+    ) -> None:
+        """Initialize the client (does not start the subprocess yet).
+
+        :param db_path: Path to the Perseus Vault SQLite database file.
+        :param perseus_vault_binary: Name (resolved on ``$PATH``) or absolute path
+            of the ``perseus-vault`` executable.
+        :param timeout_s: Per-RPC timeout guarding against a hung subprocess.
+        """
+        self.db_path = os.path.expanduser(db_path)
+        self.perseus_vault_binary = perseus_vault_binary
+        self.timeout_s = timeout_s
+
+        self._proc: subprocess.Popen | None = None
+        self._lock = threading.Lock()
+        self._request_id = 0
+        self._recv: queue.Queue = queue.Queue()
+        self._reader: threading.Thread | None = None
+        self._started = False
+
+    # ------------------------------------------------------------------ #
+    # Lifecycle
+    # ------------------------------------------------------------------ #
+    def _resolve_binary(self) -> str:
+        if os.path.isabs(self.perseus_vault_binary):
+            if not os.path.exists(self.perseus_vault_binary):
+                msg = f"perseus-vault binary not found at '{self.perseus_vault_binary}'."
+                raise RuntimeError(msg)
+            return self.perseus_vault_binary
+        resolved = shutil.which(self.perseus_vault_binary)
+        if (
+            resolved is None
+            and os.name == "nt"
+            and not self.perseus_vault_binary.lower().endswith(".exe")
+        ):
+            # On Windows the binary may be installed without the .exe suffix
+            # (shutil.which only matches PATHEXT extensions by default).
+            resolved = shutil.which(self.perseus_vault_binary + ".exe")
+        if resolved is None:
+            msg = (
+                f"perseus-vault binary not found on $PATH (looked for "
+                f"'{self.perseus_vault_binary}'). Install Perseus Vault from "
+                "https://github.com/Perseus-Computing-LLC/perseus-vault/releases "
+                "or pass an absolute path via perseus_vault_binary=."
+            )
+            raise RuntimeError(msg)
+        return resolved
+
+    def start(self) -> None:
+        """Spawn the subprocess and perform the MCP handshake (idempotent)."""
+        with self._lock:
+            if self._started:
+                return
+            binary = self._resolve_binary()
+
+            db_dir = os.path.dirname(self.db_path)
+            if db_dir:
+                os.makedirs(db_dir, exist_ok=True)
+
+            # stderr is discarded: nothing drains it, so a chatty server filling
+            # the OS pipe buffer would block on its stderr write while we wait on
+            # stdout (a classic two-pipe deadlock).
+            self._proc = subprocess.Popen(
+                [binary, "serve", "--db", self.db_path],
+                stdin=subprocess.PIPE,
+                stdout=subprocess.PIPE,
+                stderr=subprocess.DEVNULL,
+                text=True,
+            )
+
+            proc_stdout = self._proc.stdout
+
+            def _pump() -> None:
+                try:
+                    for line in proc_stdout:  # type: ignore[union-attr]
+                        self._recv.put(line)
+                except Exception:  # noqa: BLE001
+                    pass
+                finally:
+                    self._recv.put(None)  # EOF sentinel
+
+            self._reader = threading.Thread(target=_pump, daemon=True)
+            self._reader.start()
+            self._started = True
+            atexit.register(self.close)
+
+        # Handshake (outside the lock; _rpc takes the lock itself).
+        self._rpc(
+            "initialize",
+            {
+                "protocolVersion": "2024-11-05",
+                "capabilities": {},
+                "clientInfo": {"name": "perseus-vault-haystack", "version": "0.1.0"},
+            },
+        )
+        self._notify("notifications/initialized", {})
+
+    def close(self) -> None:
+        """Terminate the Perseus Vault subprocess."""
+        proc = self._proc
+        if proc is None:
+            return
+        try:
+            proc.terminate()
+            proc.wait(timeout=5)
+        except Exception:  # noqa: BLE001
+            try:
+                proc.kill()
+            except Exception:  # noqa: BLE001
+                pass
+
+    # ------------------------------------------------------------------ #
+    # JSON-RPC plumbing
+    # ------------------------------------------------------------------ #
+    def _next_id(self) -> int:
+        self._request_id += 1
+        return self._request_id
+
+    def _rpc(self, method: str, params: object) -> dict:
+        """Send a JSON-RPC request and return its ``result`` dict."""
+        with self._lock:
+            if self._proc is None or self._proc.stdin is None:
+                msg = "Perseus Vault subprocess is not running. Call start() first."
+                raise RuntimeError(msg)
+            req_id = self._next_id()
+            req = {"jsonrpc": "2.0", "id": req_id, "method": method, "params": params}
+            payload = json.dumps(req, default=str)
+            try:
+                self._proc.stdin.write(payload + "\n")
+                self._proc.stdin.flush()
+            except (BrokenPipeError, OSError) as e:
+                msg = (
+                    f"Perseus Vault subprocess communication failed: {e}. "
+                    "The perseus-vault process may have crashed."
+                )
+                raise RuntimeError(msg) from e
+
+            deadline = time.monotonic() + self.timeout_s
+            while True:
+                remaining = deadline - time.monotonic()
+                if remaining <= 0:
+                    msg = f"Perseus Vault RPC '{method}' timed out after {self.timeout_s}s."
+                    raise RuntimeError(msg)
+                try:
+                    raw = self._recv.get(timeout=remaining)
+                except queue.Empty:
+                    msg = f"Perseus Vault RPC '{method}' timed out after {self.timeout_s}s."
+                    raise RuntimeError(msg) from None
+                if raw is None:
+                    msg = "Perseus Vault subprocess closed its output (it may have crashed)."
+                    raise RuntimeError(msg)
+                raw = raw.strip()
+                if not raw:
+                    continue
+                try:
+                    resp = json.loads(raw)
+                except json.JSONDecodeError:
+                    continue  # non-JSON noise on stdout
+                if resp.get("id") != req_id:
+                    continue  # notification or a stale/other reply
+                if "error" in resp:
+                    err = resp["error"]
+                    msg = f"Perseus Vault RPC error [{err.get('code')}]: {err.get('message')}"
+                    raise RuntimeError(msg)
+                return resp.get("result", {})
+
+    def _notify(self, method: str, params: object) -> None:
+        """Send a JSON-RPC notification (no id, no response expected)."""
+        with self._lock:
+            if self._proc is None or self._proc.stdin is None:
+                return
+            payload = json.dumps({"jsonrpc": "2.0", "method": method, "params": params})
+            try:
+                self._proc.stdin.write(payload + "\n")
+                self._proc.stdin.flush()
+            except (BrokenPipeError, OSError):
+                pass
+
+    def call_tool(self, name: str, arguments: dict) -> dict:
+        """Call a Perseus Vault MCP tool and return its ``structuredContent``.
+
+        Falls back to parsing the first text content block if no structured
+        content is present.
+        """
+        if not self._started:
+            self.start()
+        result = self._rpc("tools/call", {"name": name, "arguments": arguments})
+        sc = result.get("structuredContent")
+        if sc is not None:
+            return sc
+        content = result.get("content", [])
+        if content:
+            try:
+                return json.loads(content[0].get("text", "{}"))
+            except (json.JSONDecodeError, IndexError, KeyError, AttributeError):
+                pass
+        return {}

perseus_vault_haystack/components.py

@@ -0,0 +1,122 @@
+# SPDX-FileCopyrightText: 2026 Perseus Computing LLC
+#
+# SPDX-License-Identifier: MIT
+
+"""Haystack 2.x components wrapping the Perseus Vault memory store."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from haystack import component, default_from_dict, default_to_dict
+from haystack.dataclasses import Document
+
+from .memory_store import PerseusVaultMemoryStore
+
+
+@component
+class PerseusVaultMemoryWriter:
+    """Haystack component that persists ``Document``s into a ``PerseusVaultMemoryStore``.
+
+    Slots into a pipeline as a sink: it writes the incoming documents to Perseus
+    Vault and passes them through unchanged (plus a count), so it can also sit
+    mid-pipeline.
+
+    Usage::
+
+        from perseus_vault_haystack import PerseusVaultMemoryStore, PerseusVaultMemoryWriter
+
+        store = PerseusVaultMemoryStore(db_path="~/.mimir/haystack.db")
+        writer = PerseusVaultMemoryWriter(memory_store=store)
+        writer.run(documents=[Document(content="Perseus Vault is local-first.")])
+    """
+
+    def __init__(self, *, memory_store: PerseusVaultMemoryStore) -> None:
+        """Initialize the writer.
+
+        :param memory_store: Backing :class:`PerseusVaultMemoryStore` to write into.
+        """
+        if not isinstance(memory_store, PerseusVaultMemoryStore):
+            msg = "memory_store must be an instance of PerseusVaultMemoryStore"
+            raise ValueError(msg)
+        self._memory_store = memory_store
+
+    @component.output_types(documents=list[Document], documents_written=int)
+    def run(self, documents: list[Document]) -> dict[str, Any]:
+        """Store ``documents`` in Perseus Vault and pass them through.
+
+        :param documents: Documents to persist.
+        :returns: ``{"documents": <same documents>, "documents_written": <count>}``.
+        """
+        written = self._memory_store.add_memories(documents)
+        return {"documents": documents, "documents_written": written}
+
+    def to_dict(self) -> dict[str, Any]:
+        """Serialize this component to a dictionary."""
+        return default_to_dict(self, memory_store=self._memory_store.to_dict())
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> PerseusVaultMemoryWriter:
+        """Deserialize a component from a dictionary."""
+        data["init_parameters"]["memory_store"] = PerseusVaultMemoryStore.from_dict(
+            data["init_parameters"]["memory_store"]
+        )
+        return default_from_dict(cls, data)
+
+
+@component
+class PerseusVaultMemoryRetriever:
+    """Haystack component that retrieves ``Document``s from a ``PerseusVaultMemoryStore``.
+
+    A thin pipeline adapter over :meth:`PerseusVaultMemoryStore.search_memories`.
+    Takes a ``query`` and returns the most relevant stored documents — drop it in
+    front of a prompt builder for retrieval-augmented generation over persistent
+    memory.
+
+    Usage::
+
+        from perseus_vault_haystack import PerseusVaultMemoryStore, PerseusVaultMemoryRetriever
+
+        store = PerseusVaultMemoryStore(db_path="~/.mimir/haystack.db")
+        retriever = PerseusVaultMemoryRetriever(memory_store=store, top_k=5)
+        result = retriever.run(query="What is Perseus Vault?")
+        docs = result["documents"]
+    """
+
+    def __init__(self, *, memory_store: PerseusVaultMemoryStore, top_k: int | None = None) -> None:
+        """Initialize the retriever.
+
+        :param memory_store: Backing :class:`PerseusVaultMemoryStore` to query.
+        :param top_k: Default max results; falls back to the store's ``top_k``
+            when ``None``.
+        """
+        if not isinstance(memory_store, PerseusVaultMemoryStore):
+            msg = "memory_store must be an instance of PerseusVaultMemoryStore"
+            raise ValueError(msg)
+        self._memory_store = memory_store
+        self._top_k = top_k
+
+    @component.output_types(documents=list[Document])
+    def run(self, query: str, top_k: int | None = None) -> dict[str, list[Document]]:
+        """Search the attached store and return matching documents.
+
+        :param query: Natural-language / keyword query.
+        :param top_k: Per-call override; falls back to init ``top_k``, then the
+            store's default.
+        :returns: ``{"documents": [Document, ...]}`` ordered by relevance.
+        """
+        effective_top_k = top_k if top_k is not None else self._top_k
+        documents = self._memory_store.search_memories(query=query, top_k=effective_top_k)
+        return {"documents": documents}
+
+    def to_dict(self) -> dict[str, Any]:
+        """Serialize this component to a dictionary."""
+        return default_to_dict(self, memory_store=self._memory_store.to_dict(), top_k=self._top_k)
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> PerseusVaultMemoryRetriever:
+        """Deserialize a component from a dictionary."""
+        data["init_parameters"]["memory_store"] = PerseusVaultMemoryStore.from_dict(
+            data["init_parameters"]["memory_store"]
+        )
+        return default_from_dict(cls, data)

perseus_vault_haystack/memory_store.py

@@ -0,0 +1,188 @@
+# SPDX-FileCopyrightText: 2026 Perseus Computing LLC
+#
+# SPDX-License-Identifier: MIT
+
+"""Perseus Vault-backed memory store for Haystack 2.x."""
+
+from __future__ import annotations
+
+import json
+import logging
+import time
+from typing import Any
+
+from haystack import default_from_dict, default_to_dict
+from haystack.dataclasses import Document
+
+from ._client import PerseusVaultClient
+
+logger = logging.getLogger(__name__)
+
+_DEFAULT_CATEGORY = "haystack-memory"
+
+
+class PerseusVaultMemoryStore:
+    """Persistent memory backend backed by the Perseus Vault engine.
+
+    Wraps the Perseus Vault MCP tools ``perseus_vault_remember`` (write),
+    ``perseus_vault_recall`` (search) and ``perseus_vault_forget`` (delete). Each
+    Haystack ``Document`` is stored as one Perseus Vault entity; the document's
+    ``content`` becomes the entity body and its ``meta`` is preserved as JSON. On
+    recall, entities are rehydrated back into ``Document`` objects with their
+    original ``id``, ``content``, ``meta`` and a relevance ``score`` from Perseus
+    Vault.
+
+    The store owns the long-lived ``perseus-vault`` subprocess; the thin
+    :class:`~perseus_vault_haystack.PerseusVaultMemoryWriter` and
+    :class:`~perseus_vault_haystack.PerseusVaultMemoryRetriever` components
+    delegate to it so a single store can back several pipeline components.
+
+    This class is safe to use across threads (the underlying client is
+    thread-safe).
+    """
+
+    def __init__(
+        self,
+        db_path: str = "~/.mimir/haystack.db",
+        perseus_vault_binary: str = "perseus-vault",
+        category: str = _DEFAULT_CATEGORY,
+        top_k: int = 10,
+        timeout_s: float = 30.0,
+    ) -> None:
+        """Initialize the store.
+
+        :param db_path: Path to the Perseus Vault SQLite database file.
+        :param perseus_vault_binary: Name (on ``$PATH``) or absolute path of the
+            ``perseus-vault`` executable.
+        :param category: Perseus Vault category that scopes every write and
+            recall for this store. Use distinct categories to isolate corpora.
+        :param top_k: Default maximum number of documents returned by
+            :meth:`search_memories`.
+        :param timeout_s: Per-RPC timeout for the underlying Perseus Vault
+            subprocess.
+        """
+        self.db_path = db_path
+        self.perseus_vault_binary = perseus_vault_binary
+        self.category = category
+        self.top_k = top_k
+        self.timeout_s = timeout_s
+
+        self._client = PerseusVaultClient(
+            db_path=db_path,
+            perseus_vault_binary=perseus_vault_binary,
+            timeout_s=timeout_s,
+        )
+
+    # ------------------------------------------------------------------ #
+    # Write
+    # ------------------------------------------------------------------ #
+    def add_memories(self, documents: list[Document]) -> int:
+        """Persist ``documents`` into Perseus Vault via ``perseus_vault_remember``.
+
+        Documents with empty ``content`` are skipped. The document ``id`` is used
+        as the Perseus Vault entity key so re-writing the same document updates it
+        in place (idempotent upsert).
+
+        :param documents: Documents to store.
+        :returns: The number of documents actually written.
+        """
+        written = 0
+        for doc in documents:
+            if not doc.content:
+                continue
+            key = doc.id or f"doc:{int(time.time() * 1_000_000)}:{written}"
+            self._client.call_tool(
+                "perseus_vault_remember",
+                {
+                    "category": self.category,
+                    "key": key,
+                    "body_json": json.dumps(
+                        {
+                            "doc_id": doc.id,
+                            "content": doc.content,
+                            "meta": doc.meta or {},
+                        }
+                    ),
+                    "tags": ["haystack"],
+                },
+            )
+            written += 1
+        logger.info("Stored %d documents in Perseus Vault category '%s'", written, self.category)
+        return written
+
+    # ------------------------------------------------------------------ #
+    # Search
+    # ------------------------------------------------------------------ #
+    def search_memories(self, query: str, top_k: int | None = None) -> list[Document]:
+        """Search Perseus Vault via ``perseus_vault_recall`` and return matching documents.
+
+        :param query: Natural-language / keyword query. Empty queries return
+            ``[]``.
+        :param top_k: Per-call override of the store's default ``top_k``.
+        :returns: A list of :class:`~haystack.dataclasses.Document`, ordered by
+            Perseus Vault relevance, each carrying a ``score`` when Perseus Vault
+            provides one.
+        """
+        if not query:
+            return []
+        limit = top_k if top_k is not None else self.top_k
+        result = self._client.call_tool(
+            "perseus_vault_recall",
+            {"query": query, "limit": limit, "category": self.category},
+        )
+        items = result.get("items", []) or result.get("results", [])
+        documents: list[Document] = []
+        for item in items:
+            body = item.get("body_json", "{}")
+            try:
+                body_data = json.loads(body) if isinstance(body, str) else body
+            except (json.JSONDecodeError, TypeError):
+                body_data = {}
+            if not isinstance(body_data, dict):
+                continue
+            content = body_data.get("content") or item.get("content")
+            if not content:
+                continue
+            # Perseus Vault's recall ranks by relevance but names the field
+            # differently across versions: prefer an explicit ``score``, else fall
+            # back to ``certainty`` (relevance/confidence in v2.x).
+            score = item.get("score")
+            if score is None:
+                score = item.get("certainty")
+            documents.append(
+                Document(
+                    id=body_data.get("doc_id") or item.get("key", ""),
+                    content=content,
+                    meta=body_data.get("meta", {}) or {},
+                    score=float(score) if isinstance(score, (int, float)) else None,
+                )
+            )
+        logger.info("Recalled %d documents for query '%s'", len(documents), query[:80])
+        return documents
+
+    # ------------------------------------------------------------------ #
+    # Delete
+    # ------------------------------------------------------------------ #
+    def delete_all_memories(self) -> None:
+        """Delete every entity in this store's category via ``perseus_vault_forget``."""
+        self._client.call_tool("perseus_vault_forget", {"category": self.category})
+        logger.info("Deleted all documents in Perseus Vault category '%s'", self.category)
+
+    # ------------------------------------------------------------------ #
+    # Serialization
+    # ------------------------------------------------------------------ #
+    def to_dict(self) -> dict[str, Any]:
+        """Serialize this store for pipeline persistence."""
+        return default_to_dict(
+            self,
+            db_path=self.db_path,
+            perseus_vault_binary=self.perseus_vault_binary,
+            category=self.category,
+            top_k=self.top_k,
+            timeout_s=self.timeout_s,
+        )
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> PerseusVaultMemoryStore:
+        """Deserialize a store from a dict produced by :meth:`to_dict`."""
+        return default_from_dict(cls, data)

perseus_vault_haystack-0.1.0.dist-info/METADATA

@@ -0,0 +1,129 @@
+Metadata-Version: 2.4
+Name: perseus-vault-haystack
+Version: 0.1.0
+Summary: Local-first, encrypted persistent memory for Haystack 2.x pipelines — backed by Perseus Vault.
+Project-URL: Homepage, https://github.com/Perseus-Computing-LLC/mimir-haystack
+Project-URL: Repository, https://github.com/Perseus-Computing-LLC/mimir-haystack
+Project-URL: Bug Tracker, https://github.com/Perseus-Computing-LLC/mimir-haystack/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,haystack,mcp,memory,perseus-vault,rag
+Classifier: Development Status :: 4 - Beta
+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: haystack-ai>=2.0.0
+Provides-Extra: test
+Requires-Dist: pytest>=7.0; extra == 'test'
+Description-Content-Type: text/markdown
+
+# perseus-vault-haystack
+
+Local-first, encrypted **persistent memory for [Haystack](https://haystack.deepset.ai/) 2.x pipelines**, 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 40+ tools over the Model Context Protocol (MCP). This package wraps Perseus Vault's `remember` / `recall` / `forget` tools as Haystack components so your pipelines can persist and retrieve documents across runs — no external vector database or API key required.
+
+## Components
+
+| Class | Type | Role |
+| --- | --- | --- |
+| `PerseusVaultMemoryStore` | Memory store | Owns the `perseus-vault` subprocess and config; holds `add_memories` / `search_memories` / `delete_all_memories`. |
+| `PerseusVaultMemoryWriter` | `@component` | Pipeline sink that persists `Document`s into the store. |
+| `PerseusVaultMemoryRetriever` | `@component` | Pipeline source that retrieves the most relevant `Document`s for a query. |
+
+## 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=`.
+
+You can verify it works with:
+
+```bash
+perseus-vault --version
+```
+
+## Install
+
+```bash
+pip install perseus-vault-haystack
+```
+
+This pulls in `haystack-ai`. The `perseus-vault` binary is a separate, language-agnostic dependency (see above).
+
+## Quickstart — write then read in a pipeline
+
+```python
+from haystack import Pipeline, Document
+from perseus_vault_haystack import (
+    PerseusVaultMemoryStore,
+    PerseusVaultMemoryWriter,
+    PerseusVaultMemoryRetriever,
+)
+
+# One store, shared by both components (single perseus-vault subprocess).
+store = PerseusVaultMemoryStore(db_path="~/.mimir/haystack.db", category="docs")
+
+# --- Write documents into persistent memory ---
+write_pipe = Pipeline()
+write_pipe.add_component("writer", PerseusVaultMemoryWriter(memory_store=store))
+write_pipe.run(
+    {
+        "writer": {
+            "documents": [
+                Document(content="Perseus Vault is a local-first, encrypted memory engine."),
+                Document(content="Haystack is an open-source LLM framework by deepset."),
+            ]
+        }
+    }
+)
+
+# --- Retrieve them later (even in a separate process / run) ---
+read_pipe = Pipeline()
+read_pipe.add_component("retriever", PerseusVaultMemoryRetriever(memory_store=store, top_k=3))
+result = read_pipe.run({"retriever": {"query": "What is Perseus Vault?"}})
+
+for doc in result["retriever"]["documents"]:
+    print(doc.score, doc.content)
+```
+
+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`.
+
+### Use directly (without a pipeline)
+
+```python
+from haystack import Document
+from perseus_vault_haystack import PerseusVaultMemoryStore
+
+store = PerseusVaultMemoryStore(db_path="~/.mimir/haystack.db")
+store.add_memories([Document(content="Remember this fact.")])
+hits = store.search_memories("fact", top_k=5)
+```
+
+## Configuration
+
+`PerseusVaultMemoryStore` accepts:
+
+- `db_path` — path to the Perseus Vault SQLite database (default `~/.mimir/haystack.db`).
+- `perseus_vault_binary` — name on `$PATH` or absolute path to the executable (default `perseus-vault`).
+- `category` — Perseus Vault category scoping all writes/recalls for this store (default `haystack-memory`). Use distinct categories to isolate corpora.
+- `top_k` — default number of documents returned by retrieval (default `10`).
+- `timeout_s` — per-RPC timeout for the subprocess (default `30`).
+
+## Serialization
+
+All three classes implement `to_dict()` / `from_dict()` and round-trip through `Pipeline.dumps()` / `Pipeline.loads()`.
+
+## License
+
+MIT © 2026 Perseus Computing LLC. Perseus Vault (formerly Mimir/Mneme) is also MIT-licensed.

perseus_vault_haystack-0.1.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+perseus_vault_haystack/__init__.py,sha256=dA1n9c26MMkpHBk7FVMNkKcuP9EH0FQLVjl1a4-bIFs,918
+perseus_vault_haystack/_client.py,sha256=yeH9POfvgglFjYv1f3sKBqV7G7Zcfum5i8InZJGdbjs,9423
+perseus_vault_haystack/components.py,sha256=uc8SsQpPup9bJmGI5PaBL1ofSY3PDtzNaR5fMEh995E,5017
+perseus_vault_haystack/memory_store.py,sha256=S4X5NyeFm1wkyYHDMzP3maoncRs4tQGg48NyRBjot3A,7671
+perseus_vault_haystack/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+perseus_vault_haystack-0.1.0.dist-info/METADATA,sha256=Ym_LeN2EGowKGsgld7ga49AIXtn47JwlJy2PgJ421Gs,5526
+perseus_vault_haystack-0.1.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+perseus_vault_haystack-0.1.0.dist-info/licenses/LICENSE,sha256=aPjotXyzchCdsLnPGaLiCHAhdGQvIBywrdt0qJC9SuU,1078
+perseus_vault_haystack-0.1.0.dist-info/RECORD,,

perseus_vault_haystack-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.30.1
+Root-Is-Purelib: true
+Tag: py3-none-any

perseus_vault_haystack-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Perseus Computing LLC
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.