adk-perseus-vault-memory 0.3.0__tar.gz

adk_perseus_vault_memory-0.3.0/.github/workflows/publish.yml

@@ -0,0 +1,46 @@
+name: Publish to PyPI
+
+on:
+  push:
+    tags:
+      - 'v*'
+  workflow_dispatch:
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+
+      - name: Install build
+        run: pip install build==1.2.2.post1
+
+      - name: Build
+        run: python -m build
+
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/adk-perseus-vault-memory
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+

adk_perseus_vault_memory-0.3.0/.github/workflows/test.yml

@@ -0,0 +1,28 @@
+name: Test
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+  workflow_dispatch:
+
+jobs:
+  test:
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, windows-latest, macos-latest]
+        python-version: ['3.10', '3.12']
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install
+        run: pip install -e ".[test]"
+
+      - name: Run tests
+        run: python -m pytest tests/ -q

adk_perseus_vault_memory-0.3.0/.gitignore

@@ -0,0 +1,7 @@
+dist/
+*.egg-info/
+__pycache__/
+*.pyc
+.env
+.vault/
+.mimir/

adk_perseus_vault_memory-0.3.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Perseus Computing
+
+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.

adk_perseus_vault_memory-0.3.0/PKG-INFO

@@ -0,0 +1,162 @@
+Metadata-Version: 2.4
+Name: adk-perseus-vault-memory
+Version: 0.3.0
+Summary: Persistent, local, encrypted cross-session memory for Google ADK agents — backed by Perseus Vault.
+Project-URL: Homepage, https://github.com/Perseus-Computing-LLC/adk-mimir-memory
+Project-URL: Repository, https://github.com/Perseus-Computing-LLC/adk-mimir-memory
+Project-URL: Bug Tracker, https://github.com/Perseus-Computing-LLC/adk-mimir-memory/issues
+Project-URL: Perseus Vault, https://github.com/Perseus-Computing-LLC/perseus-vault
+Author-email: Thomas Connally <51974392+tcconnally@users.noreply.github.com>
+License: MIT
+License-File: LICENSE
+Keywords: adk,agent-memory,google-adk,mcp,memory,perseus-vault
+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: google-adk>=1.0.0
+Requires-Dist: typing-extensions>=4.4.0
+Provides-Extra: perseus
+Requires-Dist: perseus-ctx>=1.0.10; extra == 'perseus'
+Provides-Extra: test
+Requires-Dist: pytest>=7.0; extra == 'test'
+Description-Content-Type: text/markdown
+
+# ADK Perseus Vault Memory
+
+Persistent, local, encrypted cross-session memory for [Google ADK](https://github.com/google/adk-python) agents — backed by [Perseus Vault](https://github.com/Perseus-Computing-LLC/perseus-vault) (formerly "Mimir"/"Mneme").
+
+## Why Perseus Vault?
+
+| Backend | Dependencies | Encryption | Hybrid Search | Local |
+|---|---|---|---|---|
+| **InMemoryMemoryService** | None | ❌ | ❌ | ✅ |
+| **VertexAiMemoryBankService** | GCP + Gemini | ❌ | Gemini-driven | ❌ |
+| **VertexAiRagMemoryService** | GCP + RAG | ❌ | GCP vector | ❌ |
+| **PerseusVaultMemoryService** | **Single binary** | **✅ AES-256** | **✅ BM25+FTS5+Dense** | **✅** |
+
+- **Zero cloud dependencies** — a single Rust binary, SQLite database, fully local
+- **AES-256-GCM encryption** at rest — your memory data stays private
+- **Hybrid search** — BM25 keyword + FTS5 + dense vector search
+- **30+ MCP tools** — remember, recall, synthesize, benchmark, federate, and more
+- **Ebbinghaus confidence decay** — memories fade naturally, important ones persist
+
+## Installation
+
+```bash
+pip install adk-perseus-vault-memory
+```
+
+This package requires the `perseus-vault` binary. Download it from:
+https://github.com/Perseus-Computing-LLC/perseus-vault/releases
+
+Or build from source:
+```bash
+cargo install perseus-vault
+```
+
+## Quick Start
+
+```python
+from google.adk.agents import Agent
+from google.adk.runners import Runner
+from google.adk.sessions import InMemorySessionService
+from adk_perseus_vault_memory import PerseusVaultMemoryService
+
+agent = Agent(
+    name="my_agent",
+    model="gemini-2.5-flash",
+    instruction="You are a helpful assistant with persistent memory.",
+)
+
+# The memory service is configured on the Runner, not on the Agent.
+runner = Runner(
+    agent=agent,
+    app_name="my_app",
+    session_service=InMemorySessionService(),
+    memory_service=PerseusVaultMemoryService(db_path="~/.adk/vault.db"),
+)
+```
+
+That's it. Sessions, events, and explicit memories are now persisted across restarts.
+
+### Configuration
+
+```python
+# Custom database location
+PerseusVaultMemoryService(db_path="/data/agent_memory.db")
+
+# Custom perseus-vault binary path (if not on $PATH)
+PerseusVaultMemoryService(vault_binary="/usr/local/bin/perseus-vault")
+
+# Both
+PerseusVaultMemoryService(
+    db_path="/data/agent_memory.db",
+    vault_binary="/usr/local/bin/perseus-vault",
+)
+```
+
+## Perseus Live Context (Optional)
+
+This package also includes a drop-in agent with live workspace awareness via [Perseus](https://github.com/Perseus-Computing-LLC/perseus):
+
+```python
+from google.adk.runners import Runner
+from google.adk.sessions import InMemorySessionService
+from adk_perseus_vault_memory.perseus_context import perseus_context_agent
+
+# The agent resolves @file, @search, @memory directives at inference time.
+# Bind it on the Runner; run_async takes no `agent` argument.
+runner = Runner(
+    agent=perseus_context_agent,
+    app_name="my_app",
+    session_service=InMemorySessionService(),
+)
+runner.run_async(
+    user_id="user",
+    session_id="session",
+    new_message=types.Content(role="user", parts=[types.Part.from_text(
+        text="What does the README say about deployment?"
+    )]),
+)
+```
+
+```bash
+pip install adk-perseus-vault-memory[perseus]  # installs perseus-ctx
+```
+
+Set directives via session state:
+```python
+session = await runner.session_service.create_session(
+    app_name="my_app",
+    user_id="user",
+    state={
+        "_perseus_directives": "@file AGENTS.md @file README.md @memory deployment",
+        "_perseus_workspace": "/path/to/project",
+    },
+)
+```
+
+## How It Works
+
+```
+┌─────────────┐     JSON-RPC (MCP stdio)     ┌────────────────┐
+│  ADK Agent  │ ──────────────────────────▶  │  Perseus Vault │
+│  (Python)   │ ◀──────────────────────────  │  (Rust)        │
+└─────────────┘                              └───────┬────────┘
+                                                      │
+                                                 SQLite + FTS5
+                                                 (AES-256-GCM)
+```
+
+The `PerseusVaultMemoryService` spawns a `perseus-vault` subprocess and communicates via JSON-RPC over stdin/stdout (MCP stdio transport). Each `add_session_to_memory`, `add_memory`, and `search_memory` call translates to a Perseus Vault MCP tool invocation.
+
+## License
+
+MIT — see [Perseus Vault](https://github.com/Perseus-Computing-LLC/perseus-vault) and [Perseus](https://github.com/Perseus-Computing-LLC/perseus) for the backing services.

adk_perseus_vault_memory-0.3.0/README.md

@@ -0,0 +1,132 @@
+# ADK Perseus Vault Memory
+
+Persistent, local, encrypted cross-session memory for [Google ADK](https://github.com/google/adk-python) agents — backed by [Perseus Vault](https://github.com/Perseus-Computing-LLC/perseus-vault) (formerly "Mimir"/"Mneme").
+
+## Why Perseus Vault?
+
+| Backend | Dependencies | Encryption | Hybrid Search | Local |
+|---|---|---|---|---|
+| **InMemoryMemoryService** | None | ❌ | ❌ | ✅ |
+| **VertexAiMemoryBankService** | GCP + Gemini | ❌ | Gemini-driven | ❌ |
+| **VertexAiRagMemoryService** | GCP + RAG | ❌ | GCP vector | ❌ |
+| **PerseusVaultMemoryService** | **Single binary** | **✅ AES-256** | **✅ BM25+FTS5+Dense** | **✅** |
+
+- **Zero cloud dependencies** — a single Rust binary, SQLite database, fully local
+- **AES-256-GCM encryption** at rest — your memory data stays private
+- **Hybrid search** — BM25 keyword + FTS5 + dense vector search
+- **30+ MCP tools** — remember, recall, synthesize, benchmark, federate, and more
+- **Ebbinghaus confidence decay** — memories fade naturally, important ones persist
+
+## Installation
+
+```bash
+pip install adk-perseus-vault-memory
+```
+
+This package requires the `perseus-vault` binary. Download it from:
+https://github.com/Perseus-Computing-LLC/perseus-vault/releases
+
+Or build from source:
+```bash
+cargo install perseus-vault
+```
+
+## Quick Start
+
+```python
+from google.adk.agents import Agent
+from google.adk.runners import Runner
+from google.adk.sessions import InMemorySessionService
+from adk_perseus_vault_memory import PerseusVaultMemoryService
+
+agent = Agent(
+    name="my_agent",
+    model="gemini-2.5-flash",
+    instruction="You are a helpful assistant with persistent memory.",
+)
+
+# The memory service is configured on the Runner, not on the Agent.
+runner = Runner(
+    agent=agent,
+    app_name="my_app",
+    session_service=InMemorySessionService(),
+    memory_service=PerseusVaultMemoryService(db_path="~/.adk/vault.db"),
+)
+```
+
+That's it. Sessions, events, and explicit memories are now persisted across restarts.
+
+### Configuration
+
+```python
+# Custom database location
+PerseusVaultMemoryService(db_path="/data/agent_memory.db")
+
+# Custom perseus-vault binary path (if not on $PATH)
+PerseusVaultMemoryService(vault_binary="/usr/local/bin/perseus-vault")
+
+# Both
+PerseusVaultMemoryService(
+    db_path="/data/agent_memory.db",
+    vault_binary="/usr/local/bin/perseus-vault",
+)
+```
+
+## Perseus Live Context (Optional)
+
+This package also includes a drop-in agent with live workspace awareness via [Perseus](https://github.com/Perseus-Computing-LLC/perseus):
+
+```python
+from google.adk.runners import Runner
+from google.adk.sessions import InMemorySessionService
+from adk_perseus_vault_memory.perseus_context import perseus_context_agent
+
+# The agent resolves @file, @search, @memory directives at inference time.
+# Bind it on the Runner; run_async takes no `agent` argument.
+runner = Runner(
+    agent=perseus_context_agent,
+    app_name="my_app",
+    session_service=InMemorySessionService(),
+)
+runner.run_async(
+    user_id="user",
+    session_id="session",
+    new_message=types.Content(role="user", parts=[types.Part.from_text(
+        text="What does the README say about deployment?"
+    )]),
+)
+```
+
+```bash
+pip install adk-perseus-vault-memory[perseus]  # installs perseus-ctx
+```
+
+Set directives via session state:
+```python
+session = await runner.session_service.create_session(
+    app_name="my_app",
+    user_id="user",
+    state={
+        "_perseus_directives": "@file AGENTS.md @file README.md @memory deployment",
+        "_perseus_workspace": "/path/to/project",
+    },
+)
+```
+
+## How It Works
+
+```
+┌─────────────┐     JSON-RPC (MCP stdio)     ┌────────────────┐
+│  ADK Agent  │ ──────────────────────────▶  │  Perseus Vault │
+│  (Python)   │ ◀──────────────────────────  │  (Rust)        │
+└─────────────┘                              └───────┬────────┘
+                                                      │
+                                                 SQLite + FTS5
+                                                 (AES-256-GCM)
+```
+
+The `PerseusVaultMemoryService` spawns a `perseus-vault` subprocess and communicates via JSON-RPC over stdin/stdout (MCP stdio transport). Each `add_session_to_memory`, `add_memory`, and `search_memory` call translates to a Perseus Vault MCP tool invocation.
+
+## License
+
+MIT — see [Perseus Vault](https://github.com/Perseus-Computing-LLC/perseus-vault) and [Perseus](https://github.com/Perseus-Computing-LLC/perseus) for the backing services.

adk_perseus_vault_memory-0.3.0/adk_perseus_vault_memory/__init__.py

@@ -0,0 +1,16 @@
+"""ADK Perseus Vault Memory Service — persistent, local, encrypted cross-session memory.
+
+Perseus Vault (github.com/Perseus-Computing-LLC/perseus-vault) is an
+open-source (MIT) persistent memory engine with 30+ MCP tools, FTS5 + dense
+hybrid search, and optional AES-256-GCM encryption. This service talks to the
+Perseus Vault binary via JSON-RPC over stdin/stdout (MCP stdio transport).
+
+Requirements:
+    A ``perseus-vault`` binary must be on ``$PATH`` or passed explicitly via
+    ``vault_binary``. Download from:
+    https://github.com/Perseus-Computing-LLC/perseus-vault/releases
+"""
+
+from .perseus_vault_memory_service import PerseusVaultMemoryService
+
+__all__ = ["PerseusVaultMemoryService"]

adk_perseus_vault_memory-0.3.0/adk_perseus_vault_memory/perseus_context.py

@@ -0,0 +1,97 @@
+"""Agent that uses Perseus for live workspace context resolution.
+
+Perseus (github.com/Perseus-Computing-LLC/perseus) is an open-source (MIT)
+live context engine that resolves workspace state at inference time.  Instead
+of baking static instructions into prompts, agents use Perseus directives
+(``@file``, ``@search``, ``@memory``, etc.) to pull in exactly what they
+need.
+
+This module provides a drop-in agent demonstrating the pattern:
+1. A ``before_agent_callback`` resolves Perseus context before each run.
+2. The resolved context is injected into the agent's instruction template.
+3. The agent knows about workspace state without it being hardcoded.
+
+Usage::
+
+    from adk_perseus_vault_memory.perseus_context import perseus_context_agent
+
+    # Use as a standalone agent
+    runner.run_async(
+        user_id="user",
+        session_id="session",
+        new_message=types.Content(...),
+        agent=perseus_context_agent,
+    )
+"""
+
+from __future__ import annotations
+
+import os
+import subprocess
+
+from google.adk.agents import Agent
+from google.adk.agents.callback_context import CallbackContext
+
+_PERSEUS_BINARY = os.environ.get("PERSEUS_BINARY", "perseus")
+
+
+def resolve_perseus_context(callback_context: CallbackContext) -> None:
+    """Resolves Perseus directives and stores the result in agent state.
+
+    Called before each agent run.  Reads directives from a state key
+    (defaulting to a sensible set) and resolves them via the Perseus CLI.
+    """
+    directives = callback_context.state.get(
+        "_perseus_directives",
+        "@file AGENTS.md @file README.md",
+    )
+
+    workspace = callback_context.state.get("_perseus_workspace", os.getcwd())
+
+    try:
+        result = subprocess.run(
+            [_PERSEUS_BINARY, "resolve", directives],
+            capture_output=True,
+            text=True,
+            timeout=15,
+            cwd=workspace,
+        )
+        if result.returncode == 0 and result.stdout.strip():
+            callback_context.state["_perseus_context"] = result.stdout.strip()
+        else:
+            callback_context.state["_perseus_context"] = (
+                f"(Perseus: no context resolved for directives: {directives})"
+            )
+    except FileNotFoundError:
+        callback_context.state["_perseus_context"] = (
+            "(Perseus CLI not installed. Install with: pip install perseus-ctx)"
+        )
+    except subprocess.TimeoutExpired:
+        callback_context.state["_perseus_context"] = (
+            "(Perseus resolution timed out)"
+        )
+
+
+perseus_context_agent = Agent(
+    name="perseus_context_agent",
+    description=(
+        "Agent with live workspace context via Perseus.  Knows about "
+        "project files, git state, and workspace structure without "
+        "hardcoded instructions."
+    ),
+    before_agent_callback=resolve_perseus_context,
+    instruction="""\
+You are a helpful assistant with live context about the current workspace.
+
+The following context was resolved by Perseus from the workspace files
+and state.  Use it to answer questions accurately.
+
+--- BEGIN PERSEUS CONTEXT ---
+{_perseus_context}
+--- END PERSEUS CONTEXT ---
+
+Use this context to give grounded, file-aware answers.  If the context
+is empty or unavailable, let the user know and fall back to general
+knowledge.
+""",
+)

adk_perseus_vault_memory-0.3.0/adk_perseus_vault_memory/perseus_vault_memory_service.py

@@ -0,0 +1,533 @@
+"""Perseus Vault persistent memory service for ADK.
+
+Perseus Vault (github.com/Perseus-Computing-LLC/perseus-vault) is an
+open-source (MIT) persistent memory engine with 30+ MCP tools, FTS5 + dense
+hybrid search, and optional AES-256-GCM encryption.  This service talks to the
+Perseus Vault binary via JSON-RPC over stdin/stdout (MCP stdio transport).
+
+Requirements:
+    A ``perseus-vault`` binary must be on ``$PATH`` or passed explicitly via
+    ``vault_binary``.  Build from source or download a pre-built binary from
+    the Perseus Vault releases page.
+
+Usage::
+
+    from adk_perseus_vault_memory import PerseusVaultMemoryService
+    from google.adk.runners import Runner
+
+    # The memory service is configured on the Runner (not on the Agent).
+    runner = Runner(
+        agent=my_agent,
+        app_name="my_app",
+        session_service=my_session_service,
+        memory_service=PerseusVaultMemoryService(db_path="~/.adk/vault.db"),
+    )
+"""
+
+from __future__ import annotations
+
+import asyncio
+import atexit
+import json
+import logging
+import os
+import queue
+import shutil
+import subprocess
+import threading
+import time
+from collections.abc import Mapping
+from collections.abc import Sequence
+from datetime import datetime, timezone
+from typing import TYPE_CHECKING
+
+from typing_extensions import override
+
+from google.adk.memory.base_memory_service import BaseMemoryService
+from google.adk.memory.base_memory_service import SearchMemoryResponse
+from google.adk.memory.memory_entry import MemoryEntry
+from google.genai import types
+
+if TYPE_CHECKING:
+    from google.adk.events.event import Event
+    from google.adk.sessions.session import Session
+
+logger = logging.getLogger(__name__)
+
+_VAULT_CATEGORY = "adk-memory"
+
+
+def _format_timestamp(timestamp: float) -> str:
+    """Formats a unix timestamp as a UTC ISO 8601 string."""
+    return datetime.fromtimestamp(timestamp, tz=timezone.utc).isoformat()
+
+
+class PerseusVaultMemoryService(BaseMemoryService):
+    """Persistent memory service backed by Perseus Vault.
+
+    Talks to a local ``perseus-vault`` binary via JSON-RPC (MCP stdio).  Stores
+    session events as structured entities and supports keyword (FTS5) search
+    across sessions.
+
+    This class is thread-safe.
+
+    Attributes:
+        db_path: Filesystem path to the Perseus Vault SQLite database.
+        vault_binary: Path or name of the ``perseus-vault`` executable.
+    """
+
+    def __init__(
+        self,
+        db_path: str = "~/.adk/vault.db",
+        vault_binary: str = "perseus-vault",
+        timeout_s: float = 30.0,
+    ):
+        """Initializes the Perseus Vault memory service.
+
+        Args:
+            db_path: Path to the Perseus Vault database file.  Defaults to
+                ``~/.adk/vault.db``.
+            vault_binary: Name or absolute path of the ``perseus-vault``
+                executable.  Defaults to ``perseus-vault`` (resolved from
+                ``$PATH``).
+            timeout_s: Maximum time to wait for any single Perseus Vault RPC
+                response.  Guards against a hung subprocess blocking the agent
+                forever.
+
+        Raises:
+            RuntimeError: If the ``perseus-vault`` binary cannot be found or the
+                subprocess fails to start.
+        """
+        self.db_path = os.path.expanduser(db_path)
+        self._timeout_s = timeout_s
+
+        # Resolve the perseus-vault binary.
+        if os.path.isabs(vault_binary):
+            self._vault_binary = vault_binary
+        else:
+            resolved = shutil.which(vault_binary)
+            if resolved is None:
+                raise RuntimeError(
+                    f"perseus-vault binary not found on $PATH (looked for "
+                    f"'{vault_binary}'). Install Perseus Vault from "
+                    "https://github.com/Perseus-Computing-LLC/perseus-vault "
+                    "or pass the absolute path via vault_binary=."
+                )
+            self._vault_binary = resolved
+
+        # Ensure the database directory exists.
+        os.makedirs(os.path.dirname(self.db_path) or ".", exist_ok=True)
+
+        # Start the Perseus Vault MCP stdio subprocess. 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 two-pipe
+        # deadlock).
+        self._proc = subprocess.Popen(
+            [self._vault_binary, "--db", self.db_path],
+            stdin=subprocess.PIPE,
+            stdout=subprocess.PIPE,
+            stderr=subprocess.DEVNULL,
+            text=True,
+        )
+        self._lock = threading.Lock()
+        self._request_id = 0
+
+        # Background reader: pump stdout lines into a queue so _rpc can wait with a
+        # timeout and correlate responses by id, rather than blocking forever on a
+        # bare readline().
+        self._recv: queue.Queue = queue.Queue()
+        proc_stdout = self._proc.stdout
+
+        def _pump() -> None:
+            try:
+                for line in proc_stdout:
+                    self._recv.put(line)
+            except Exception:
+                pass
+            finally:
+                self._recv.put(None)  # EOF sentinel
+
+        self._reader = threading.Thread(target=_pump, daemon=True)
+        self._reader.start()
+
+        # Initialize the MCP session, then send the required initialized
+        # notification (per the MCP spec) before any tools/call.
+        self._rpc(
+            "initialize",
+            {
+                "protocolVersion": "2024-11-05",
+                "capabilities": {},
+                "clientInfo": {
+                    "name": "adk-perseus-vault-memory-service",
+                    "version": "1.0",
+                },
+            },
+        )
+        self._notify("notifications/initialized", {})
+
+        # Clean up the subprocess on exit.
+        atexit.register(self._close)
+
+    def _close(self) -> None:
+        """Terminates the Perseus Vault subprocess."""
+        try:
+            self._proc.terminate()
+            self._proc.wait(timeout=5)
+        except Exception:
+            try:
+                self._proc.kill()
+            except Exception:
+                pass
+
+    def _next_id(self) -> int:
+        self._request_id += 1
+        return self._request_id
+
+    def _rpc(self, method: str, params: object) -> dict:
+        """Sends a JSON-RPC request to Perseus Vault and returns the result dict.
+
+        Args:
+            method: The MCP method name (e.g. ``tools/call``).
+            params: The method parameters.
+
+        Returns:
+            The ``result`` field of the JSON-RPC response.
+
+        Raises:
+            RuntimeError: If the RPC returns an error.
+        """
+        with self._lock:
+            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:
+                raise RuntimeError(
+                    f"Perseus Vault subprocess communication failed: {e}. "
+                    "The perseus-vault process may have crashed."
+                ) from e
+
+            # Wait for the reply with this id, honoring a deadline. Skip
+            # notifications (no id) and replies to other ids. The lock is held
+            # for the whole exchange so request/response pairs never interleave.
+            deadline = time.monotonic() + self._timeout_s
+            while True:
+                remaining = deadline - time.monotonic()
+                if remaining <= 0:
+                    raise RuntimeError(
+                        f"Perseus Vault RPC '{method}' timed out after "
+                        f"{self._timeout_s}s."
+                    )
+                try:
+                    raw = self._recv.get(timeout=remaining)
+                except queue.Empty:
+                    raise RuntimeError(
+                        f"Perseus Vault RPC '{method}' timed out after "
+                        f"{self._timeout_s}s."
+                    )
+                if raw is None:
+                    raise RuntimeError(
+                        "Perseus Vault subprocess closed its output "
+                        "(it may have crashed)."
+                    )
+                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"]
+                    raise RuntimeError(
+                        f"Perseus Vault RPC error [{err.get('code')}]: "
+                        f"{err.get('message')}"
+                    )
+                return resp.get("result", {})
+
+    def _notify(self, method: str, params: object) -> None:
+        """Sends a JSON-RPC notification (no id, no response expected)."""
+        payload = json.dumps({"jsonrpc": "2.0", "method": method, "params": params})
+        with self._lock:
+            try:
+                self._proc.stdin.write(payload + "\n")
+                self._proc.stdin.flush()
+            except (BrokenPipeError, OSError):
+                pass
+
+    def _call_tool(self, name: str, arguments: dict) -> dict:
+        """Calls a Perseus Vault MCP tool and returns the ``structuredContent``."""
+        result = self._rpc(
+            "tools/call",
+            {"name": name, "arguments": arguments},
+        )
+        # MCP result is {content: [{type: "text", text: "..."}], structuredContent: {...}}
+        sc = result.get("structuredContent")
+        if sc is not None:
+            return sc
+        # Fallback: parse the text content
+        content = result.get("content", [])
+        if content:
+            try:
+                return json.loads(content[0].get("text", "{}"))
+            except (json.JSONDecodeError, IndexError, KeyError):
+                pass
+        return {}
+
+    @override
+    async def add_session_to_memory(self, session: Session) -> None:
+        """Stores all events from a session in Perseus Vault.
+
+        Each session is stored as a single Perseus Vault entity keyed by session
+        ID.  Subsequent calls for the same session will update the stored events.
+        """
+        if not session.events:
+            return
+
+        events_data = []
+        for event in session.events:
+            if not event.content or not event.content.parts:
+                continue
+            parts = []
+            for part in event.content.parts:
+                if part.text:
+                    parts.append({"text": part.text})
+                elif hasattr(part, "function_call") and part.function_call:
+                    parts.append({
+                        "function_call": {
+                            "name": part.function_call.name,
+                            "args": part.function_call.args,
+                        }
+                    })
+                elif hasattr(part, "function_response") and part.function_response:
+                    parts.append({
+                        "function_response": {
+                            "name": part.function_response.name,
+                            "response": str(part.function_response.response)[:2000],
+                        }
+                    })
+            if parts:
+                events_data.append({
+                    "author": event.author,
+                    "timestamp": event.timestamp,
+                    "parts": parts,
+                })
+
+        if not events_data:
+            return
+
+        await asyncio.to_thread(
+            self._call_tool,
+            "perseus_vault_remember",
+            {
+                "category": _VAULT_CATEGORY,
+                "key": f"session:{session.app_name}:{session.user_id}:{session.id}",
+                "body_json": json.dumps({
+                    "session_id": session.id,
+                    "app_name": session.app_name,
+                    "user_id": session.user_id,
+                    "events": events_data,
+                    "event_count": len(events_data),
+                }),
+                "tags": ["adk", "session", session.app_name],
+            },
+        )
+
+    @override
+    async def add_events_to_memory(
+        self,
+        *,
+        app_name: str,
+        user_id: str,
+        events: Sequence[Event],
+        session_id: str | None = None,
+        custom_metadata: Mapping[str, object] | None = None,
+    ) -> None:
+        """Adds a delta of events to Perseus Vault.
+
+        Events are appended to an existing session entity if one exists, or a
+        new entity is created.  This is the recommended method for incremental
+        memory updates during long-running sessions.
+        """
+        _ = custom_metadata
+        events_data = []
+        for event in events:
+            if not event.content or not event.content.parts:
+                continue
+            parts = []
+            for part in event.content.parts:
+                if part.text:
+                    parts.append({"text": part.text})
+                elif hasattr(part, "function_call") and part.function_call:
+                    parts.append({
+                        "function_call": {
+                            "name": part.function_call.name,
+                            "args": part.function_call.args,
+                        }
+                    })
+            if parts:
+                events_data.append({
+                    "author": event.author,
+                    "timestamp": event.timestamp,
+                    "parts": parts,
+                })
+
+        if not events_data:
+            return
+
+        sid = session_id or "__unknown__"
+        delta_key = f"delta:{app_name}:{user_id}:{sid}:{int(time.time() * 1000)}"
+
+        await asyncio.to_thread(
+            self._call_tool,
+            "perseus_vault_remember",
+            {
+                "category": _VAULT_CATEGORY,
+                "key": delta_key,
+                "body_json": json.dumps({
+                    "session_id": sid,
+                    "app_name": app_name,
+                    "user_id": user_id,
+                    "events": events_data,
+                    "event_count": len(events_data),
+                }),
+                "tags": ["adk", "delta", app_name],
+            },
+        )
+
+    @override
+    async def add_memory(
+        self,
+        *,
+        app_name: str,
+        user_id: str,
+        memories: Sequence[MemoryEntry],
+        custom_metadata: Mapping[str, object] | None = None,
+    ) -> None:
+        """Adds explicit memory entries directly to Perseus Vault.
+
+        Each MemoryEntry is stored as a separate entity tagged for the given
+        application and user.
+        """
+        _ = custom_metadata
+        for i, entry in enumerate(memories):
+            content_text = ""
+            if entry.content and entry.content.parts:
+                content_text = " ".join(
+                    p.text for p in entry.content.parts if p.text
+                )
+
+            if not content_text:
+                continue
+
+            await asyncio.to_thread(
+                self._call_tool,
+                "perseus_vault_remember",
+                {
+                    "category": _VAULT_CATEGORY,
+                    "key": f"memory:{app_name}:{user_id}:{entry.id or i}",
+                    "body_json": json.dumps({
+                        "content": content_text,
+                        "app_name": app_name,
+                        "user_id": user_id,
+                        "author": entry.author,
+                        "timestamp": entry.timestamp,
+                        "metadata": entry.custom_metadata,
+                    }),
+                    "tags": ["adk", "explicit", app_name],
+                },
+            )
+
+    @override
+    async def search_memory(
+        self,
+        *,
+        app_name: str,
+        user_id: str,
+        query: str,
+    ) -> SearchMemoryResponse:
+        """Searches Perseus Vault for memories matching the query.
+
+        Uses Perseus Vault's FTS5 keyword search, then enforces per-(app, user)
+        isolation in-process: Perseus Vault's recall OR's query terms together,
+        so scoping cannot be expressed by stuffing the app/user into the query
+        string (that both leaks other tenants' memories and dilutes relevance).
+        Instead the clean query is sent and every returned item is filtered to
+        the requesting ``app_name`` and ``user_id`` recorded in its body.
+
+        Args:
+            app_name: The application name for memory scope.
+            user_id: The user ID for memory scope.
+            query: The natural-language query to search for.
+
+        Returns:
+            A SearchMemoryResponse containing matching MemoryEntry objects.
+        """
+        # Over-fetch a little since results are post-filtered by tenant.
+        result = await asyncio.to_thread(
+            self._call_tool,
+            "perseus_vault_recall",
+            {
+                "query": query,
+                "limit": 50,
+                "category": _VAULT_CATEGORY,
+            },
+        )
+
+        response = SearchMemoryResponse()
+        items = result.get("items", [])
+        for item in items:
+            body = item.get("body_json", "{}")
+            try:
+                body_data = json.loads(body) if isinstance(body, str) else body
+            except json.JSONDecodeError:
+                body_data = {}
+            if not isinstance(body_data, dict):
+                continue
+
+            # Tenant isolation: never surface another app's or user's memory.
+            if (
+                body_data.get("app_name") != app_name
+                or body_data.get("user_id") != user_id
+            ):
+                continue
+
+            # Determine the best text content to surface.
+            content_text = body_data.get("content", "")
+            if not content_text:
+                events = body_data.get("events", [])
+                texts = []
+                for ev in events:
+                    for part in ev.get("parts", []):
+                        if part.get("text"):
+                            texts.append(part["text"])
+                content_text = " | ".join(texts[:5]) if texts else ""
+
+            if not content_text:
+                continue
+
+            response.memories.append(
+                MemoryEntry(
+                    content=types.Content(
+                        role="model",
+                        parts=[types.Part.from_text(text=content_text)],
+                    ),
+                    author=body_data.get("author") or "perseus-vault",
+                    timestamp=body_data.get("timestamp")
+                    or _format_timestamp(
+                        item.get("created_at_unix_ms", 0) / 1000.0
+                    ),
+                )
+            )
+
+        return response

adk_perseus_vault_memory-0.3.0/pyproject.toml

@@ -0,0 +1,49 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "adk-perseus-vault-memory"
+version = "0.3.0"
+authors = [
+    { name = "Thomas Connally", email = "51974392+tcconnally@users.noreply.github.com" },
+]
+description = "Persistent, local, encrypted cross-session memory for Google ADK agents — backed by Perseus Vault."
+readme = "README.md"
+license = { text = "MIT" }
+requires-python = ">=3.10"
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+    "Intended Audience :: Developers",
+]
+keywords = [
+    "google-adk",
+    "adk",
+    "memory",
+    "perseus-vault",
+    "agent-memory",
+    "mcp",
+]
+dependencies = [
+    "google-adk>=1.0.0",
+    # override is used for the BaseMemoryService overrides; stdlib typing.override
+    # only exists on 3.12+, so the backport is required on 3.10/3.11.
+    "typing-extensions>=4.4.0",
+]
+
+[project.optional-dependencies]
+perseus = ["perseus-ctx>=1.0.10"]
+test = ["pytest>=7.0"]
+
+[project.urls]
+Homepage = "https://github.com/Perseus-Computing-LLC/adk-mimir-memory"
+Repository = "https://github.com/Perseus-Computing-LLC/adk-mimir-memory"
+"Bug Tracker" = "https://github.com/Perseus-Computing-LLC/adk-mimir-memory/issues"
+"Perseus Vault" = "https://github.com/Perseus-Computing-LLC/perseus-vault"

adk_perseus_vault_memory-0.3.0/tests/test_perseus_vault_memory_service.py

@@ -0,0 +1,226 @@
+"""Tests for PerseusVaultMemoryService against a fake Perseus Vault MCP stdio server.
+
+No real ``perseus-vault`` binary is required: ``subprocess.Popen`` is
+monkeypatched to return an in-process fake that speaks JSON-RPC 2.0 over fake
+stdin/stdout pipes and models Perseus Vault's recall OR-semantics, so these
+exercise the real RPC, async, and tenant-isolation code paths.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import queue
+
+import pytest
+
+from google.genai import types
+from google.adk.memory.memory_entry import MemoryEntry
+
+import adk_perseus_vault_memory.perseus_vault_memory_service as svc_mod
+from adk_perseus_vault_memory import PerseusVaultMemoryService
+
+
+# ── Fake Perseus Vault MCP stdio server ─────────────────────────────────────
+
+
+class _FakeStdin:
+    def __init__(self, on_line):
+        self._on_line = on_line
+
+    def write(self, s):
+        for line in s.splitlines():
+            if line.strip():
+                self._on_line(line)
+
+    def flush(self):
+        pass
+
+    def close(self):
+        pass
+
+
+class _FakeStdout:
+    """Blocking, iterable line source fed by the fake server."""
+
+    def __init__(self):
+        self._q = queue.Queue()
+
+    def put(self, line):
+        self._q.put(line)
+
+    def __iter__(self):
+        return self
+
+    def __next__(self):
+        item = self._q.get()
+        if item is None:
+            raise StopIteration
+        return item
+
+    def close(self):
+        self._q.put(None)
+
+
+class FakeVault:
+    """Minimal Popen-compatible fake of the Perseus Vault MCP stdio server.
+
+    Options:
+        answer_tools: if False, tools/call requests get no response (to test
+            the RPC timeout).
+        emit_notification_before_reply: if True, a JSON-RPC notification line is
+            emitted before every tools/call reply (to test id correlation).
+    """
+
+    def __init__(self, *, answer_tools=True, emit_notification_before_reply=False):
+        self.store = {}  # (category, key) -> arguments dict
+        self.stdout = _FakeStdout()
+        self.stdin = _FakeStdin(self._handle)
+        self._alive = True
+        self._answer_tools = answer_tools
+        self._emit_notif = emit_notification_before_reply
+
+    # --- JSON-RPC handling ---
+    def _handle(self, line):
+        req = json.loads(line)
+        rid = req.get("id")
+        method = req.get("method")
+        if rid is None:
+            return  # client notification, no response
+        if method == "initialize":
+            self._respond(rid, {"protocolVersion": "2024-11-05", "capabilities": {}})
+            return
+        if method == "tools/call":
+            if not self._answer_tools:
+                return  # simulate a hung server
+            if self._emit_notif:
+                self.stdout.put(
+                    json.dumps(
+                        {"jsonrpc": "2.0", "method": "notifications/progress", "params": {}}
+                    )
+                    + "\n"
+                )
+            params = req["params"]
+            name = params["name"]
+            args = params["arguments"]
+            if name == "perseus_vault_remember":
+                self.store[(args["category"], args["key"])] = args
+                self._respond(rid, {"structuredContent": {"stored": True}})
+            elif name == "perseus_vault_recall":
+                q = args.get("query", "").lower().split()
+                cat = args.get("category")
+                items = []
+                for (c, _k), rec in self.store.items():
+                    if cat and c != cat:
+                        continue
+                    body = rec["body_json"]
+                    # Model Perseus Vault's OR semantics: match if ANY query word appears.
+                    if any(w in body.lower() for w in q):
+                        items.append({"body_json": body, "created_at_unix_ms": 0})
+                self._respond(rid, {"structuredContent": {"items": items}})
+            else:
+                self._respond(rid, {"structuredContent": {}})
+            return
+        self._respond(rid, {})
+
+    def _respond(self, rid, result):
+        self.stdout.put(json.dumps({"jsonrpc": "2.0", "id": rid, "result": result}) + "\n")
+
+    # --- Popen surface ---
+    def poll(self):
+        return None if self._alive else 0
+
+    def terminate(self):
+        self._alive = False
+        self.stdout.close()
+
+    def kill(self):
+        self._alive = False
+        self.stdout.close()
+
+    def wait(self, timeout=None):
+        return 0
+
+
+def _make_service(monkeypatch, tmp_path, **fake_kwargs):
+    fake = FakeVault(**fake_kwargs)
+    monkeypatch.setattr(svc_mod.subprocess, "Popen", lambda *a, **k: fake)
+    db = tmp_path / "vault.db"
+    # Use a platform-absolute path so __init__ skips the $PATH lookup.
+    fake_bin = str(tmp_path / "fake-perseus-vault")
+    service = PerseusVaultMemoryService(
+        db_path=str(db), vault_binary=fake_bin, timeout_s=1.0
+    )
+    return service, fake
+
+
+def _entry(text):
+    return MemoryEntry(
+        content=types.Content(role="user", parts=[types.Part.from_text(text=text)]),
+        author="user",
+        timestamp="2026-01-01T00:00:00+00:00",
+    )
+
+
+# ── Tests ──────────────────────────────────────────────────────────────────
+
+
+def test_init_completes_handshake(monkeypatch, tmp_path):
+    service, _fake = _make_service(monkeypatch, tmp_path)
+    assert service._request_id >= 1  # initialize consumed an id
+    service._close()
+
+
+def test_tenant_isolation_search(monkeypatch, tmp_path):
+    """A search must never return another app's or user's memories, even though
+    Perseus Vault's recall OR-matches the shared query term."""
+    service, _fake = _make_service(monkeypatch, tmp_path)
+
+    asyncio.run(
+        service.add_memory(
+            app_name="app1", user_id="alice", memories=[_entry("alice likes turtles")]
+        )
+    )
+    asyncio.run(
+        service.add_memory(
+            app_name="app1", user_id="bob", memories=[_entry("bob likes turtles")]
+        )
+    )
+    asyncio.run(
+        service.add_memory(
+            app_name="app2", user_id="alice", memories=[_entry("alice in app2 turtles")]
+        )
+    )
+
+    resp = asyncio.run(
+        service.search_memory(app_name="app1", user_id="alice", query="turtles")
+    )
+    texts = [p.text for m in resp.memories for p in m.content.parts]
+    assert texts == ["alice likes turtles"], texts  # only app1/alice
+    service._close()
+
+
+def test_rpc_timeout_when_server_hangs(monkeypatch, tmp_path):
+    service, _fake = _make_service(monkeypatch, tmp_path, answer_tools=False)
+    with pytest.raises(RuntimeError, match="timed out"):
+        asyncio.run(
+            service.search_memory(app_name="a", user_id="u", query="anything")
+        )
+    service._close()
+
+
+def test_id_correlation_skips_notifications(monkeypatch, tmp_path):
+    service, _fake = _make_service(
+        monkeypatch, tmp_path, emit_notification_before_reply=True
+    )
+    asyncio.run(
+        service.add_memory(
+            app_name="app", user_id="u", memories=[_entry("hello world")]
+        )
+    )
+    resp = asyncio.run(
+        service.search_memory(app_name="app", user_id="u", query="hello")
+    )
+    texts = [p.text for m in resp.memories for p in m.content.parts]
+    assert texts == ["hello world"], texts
+    service._close()