adk-mimir-memory 0.2.0__tar.gz

adk_mimir_memory-0.2.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-mimir-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_mimir_memory-0.2.0/.gitignore

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

adk_mimir_memory-0.2.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_mimir_memory-0.2.0/PKG-INFO

@@ -0,0 +1,143 @@
+Metadata-Version: 2.4
+Name: adk-mimir-memory
+Version: 0.2.0
+Summary: Persistent, local, encrypted cross-session memory for Google ADK agents — backed by Mimir.
+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
+Author-email: Thomas Connally <51974392+tcconnally@users.noreply.github.com>
+License: MIT
+License-File: LICENSE
+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
+Provides-Extra: perseus
+Requires-Dist: perseus-ctx; extra == 'perseus'
+Description-Content-Type: text/markdown
+
+# ADK Mimir Memory
+
+Persistent, local, encrypted cross-session memory for [Google ADK](https://github.com/google/adk-python) agents — backed by [Mimir](https://github.com/Perseus-Computing-LLC/mimir).
+
+## Why Mimir?
+
+| Backend | Dependencies | Encryption | Hybrid Search | Local |
+|---|---|---|---|---|
+| **InMemoryMemoryService** | None | ❌ | ❌ | ✅ |
+| **VertexAiMemoryBankService** | GCP + Gemini | ❌ | Gemini-driven | ❌ |
+| **VertexAiRagMemoryService** | GCP + RAG | ❌ | GCP vector | ❌ |
+| **MimirMemoryService** | **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-mimir-memory
+```
+
+This package requires the `mimir` binary. Download it from:
+https://github.com/Perseus-Computing-LLC/mimir/releases
+
+Or build from source:
+```bash
+cargo install mimir
+```
+
+## Quick Start
+
+```python
+from google.adk.agents import Agent
+from adk_mimir_memory import MimirMemoryService
+
+agent = Agent(
+    name="my_agent",
+    model="gemini-2.5-flash",
+    instruction="You are a helpful assistant with persistent memory.",
+    memory_service=MimirMemoryService(
+        db_path="~/.adk/mimir.db",
+    ),
+)
+```
+
+That's it. Sessions, events, and explicit memories are now persisted across restarts.
+
+### Configuration
+
+```python
+# Custom database location
+MimirMemoryService(db_path="/data/agent_memory.db")
+
+# Custom mimir binary path (if not on $PATH)
+MimirMemoryService(mimir_binary="/usr/local/bin/mimir")
+
+# Both
+MimirMemoryService(
+    db_path="/data/agent_memory.db",
+    mimir_binary="/usr/local/bin/mimir",
+)
+```
+
+## 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 adk_mimir_memory.perseus_context import perseus_context_agent
+
+# The agent resolves @file, @search, @memory directives at inference time
+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?"
+    )]),
+    agent=perseus_context_agent,
+)
+```
+
+```bash
+pip install adk-mimir-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  │ ──────────────────────────▶  │  Mimir   │
+│  (Python)   │ ◀──────────────────────────  │  (Rust)  │
+└─────────────┘                               └────┬─────┘
+                                                   │
+                                              SQLite + FTS5
+                                              (AES-256-GCM)
+```
+
+The `MimirMemoryService` spawns a `mimir` 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 Mimir MCP tool invocation.
+
+## License
+
+MIT — see [Mimir](https://github.com/Perseus-Computing-LLC/mimir) and [Perseus](https://github.com/Perseus-Computing-LLC/perseus) for the backing services.

adk_mimir_memory-0.2.0/README.md

@@ -0,0 +1,118 @@
+# ADK Mimir Memory
+
+Persistent, local, encrypted cross-session memory for [Google ADK](https://github.com/google/adk-python) agents — backed by [Mimir](https://github.com/Perseus-Computing-LLC/mimir).
+
+## Why Mimir?
+
+| Backend | Dependencies | Encryption | Hybrid Search | Local |
+|---|---|---|---|---|
+| **InMemoryMemoryService** | None | ❌ | ❌ | ✅ |
+| **VertexAiMemoryBankService** | GCP + Gemini | ❌ | Gemini-driven | ❌ |
+| **VertexAiRagMemoryService** | GCP + RAG | ❌ | GCP vector | ❌ |
+| **MimirMemoryService** | **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-mimir-memory
+```
+
+This package requires the `mimir` binary. Download it from:
+https://github.com/Perseus-Computing-LLC/mimir/releases
+
+Or build from source:
+```bash
+cargo install mimir
+```
+
+## Quick Start
+
+```python
+from google.adk.agents import Agent
+from adk_mimir_memory import MimirMemoryService
+
+agent = Agent(
+    name="my_agent",
+    model="gemini-2.5-flash",
+    instruction="You are a helpful assistant with persistent memory.",
+    memory_service=MimirMemoryService(
+        db_path="~/.adk/mimir.db",
+    ),
+)
+```
+
+That's it. Sessions, events, and explicit memories are now persisted across restarts.
+
+### Configuration
+
+```python
+# Custom database location
+MimirMemoryService(db_path="/data/agent_memory.db")
+
+# Custom mimir binary path (if not on $PATH)
+MimirMemoryService(mimir_binary="/usr/local/bin/mimir")
+
+# Both
+MimirMemoryService(
+    db_path="/data/agent_memory.db",
+    mimir_binary="/usr/local/bin/mimir",
+)
+```
+
+## 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 adk_mimir_memory.perseus_context import perseus_context_agent
+
+# The agent resolves @file, @search, @memory directives at inference time
+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?"
+    )]),
+    agent=perseus_context_agent,
+)
+```
+
+```bash
+pip install adk-mimir-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  │ ──────────────────────────▶  │  Mimir   │
+│  (Python)   │ ◀──────────────────────────  │  (Rust)  │
+└─────────────┘                               └────┬─────┘
+                                                   │
+                                              SQLite + FTS5
+                                              (AES-256-GCM)
+```
+
+The `MimirMemoryService` spawns a `mimir` 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 Mimir MCP tool invocation.
+
+## License
+
+MIT — see [Mimir](https://github.com/Perseus-Computing-LLC/mimir) and [Perseus](https://github.com/Perseus-Computing-LLC/perseus) for the backing services.

adk_mimir_memory-0.2.0/adk_mimir_memory/__init__.py

@@ -0,0 +1,16 @@
+"""ADK Mimir Memory Service — persistent, local, encrypted cross-session memory.
+
+Mimir (github.com/Perseus-Computing-LLC/mimir) 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 Mimir
+binary via JSON-RPC over stdin/stdout (MCP stdio transport).
+
+Requirements:
+    A ``mimir`` binary must be on ``$PATH`` or passed explicitly via
+    ``mimir_binary``. Download from:
+    https://github.com/Perseus-Computing-LLC/mimir/releases
+"""
+
+from .mimir_memory_service import MimirMemoryService
+
+__all__ = ["MimirMemoryService"]

adk_mimir_memory-0.2.0/adk_mimir_memory/mimir_memory_service.py

@@ -0,0 +1,445 @@
+"""Mimir persistent memory service for ADK.
+
+Mimir (github.com/Perseus-Computing-LLC/mimir) 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 Mimir
+binary via JSON-RPC over stdin/stdout (MCP stdio transport).
+
+Requirements:
+    A ``mimir`` binary must be on ``$PATH`` or passed explicitly via
+    ``mimir_binary``.  Build from source or download a pre-built binary from
+    the Mimir releases page.
+
+Usage::
+
+    from adk_mimir_memory import MimirMemoryService
+    from google.adk.memory import InMemoryMemoryService
+
+    # Swap out the default in-memory service for persistent Mimir
+    agent = Agent(
+        name="my_agent",
+        memory_service=MimirMemoryService(
+            db_path="~/.adk/mimir.db",
+        ),
+    )
+"""
+
+from __future__ import annotations
+
+import atexit
+import json
+import logging
+import os
+import shutil
+import subprocess
+import threading
+from collections.abc import Mapping
+from collections.abc import Sequence
+from datetime import datetime
+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__)
+
+_MIMIR_CATEGORY = "adk-memory"
+
+
+def _format_timestamp(timestamp: float) -> str:
+    """Formats a unix timestamp as an ISO 8601 string."""
+    return datetime.fromtimestamp(timestamp).isoformat()
+
+
+class MimirMemoryService(BaseMemoryService):
+    """Persistent memory service backed by Mimir.
+
+    Talks to a local ``mimir`` 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 Mimir SQLite database.
+        mimir_binary: Path or name of the ``mimir`` executable.
+    """
+
+    def __init__(
+        self,
+        db_path: str = "~/.adk/mimir.db",
+        mimir_binary: str = "mimir",
+    ):
+        """Initializes the Mimir memory service.
+
+        Args:
+            db_path: Path to the Mimir database file.  Defaults to
+                ``~/.adk/mimir.db``.
+            mimir_binary: Name or absolute path of the ``mimir`` executable.
+                Defaults to ``mimir`` (resolved from ``$PATH``).
+
+        Raises:
+            RuntimeError: If the ``mimir`` binary cannot be found or the
+                subprocess fails to start.
+        """
+        self.db_path = os.path.expanduser(db_path)
+
+        # Resolve the mimir binary.
+        if os.path.isabs(mimir_binary):
+            self._mimir_binary = mimir_binary
+        else:
+            resolved = shutil.which(mimir_binary)
+            if resolved is None:
+                raise RuntimeError(
+                    f"mimir binary not found on $PATH (looked for '{mimir_binary}'). "
+                    "Install Mimir from https://github.com/Perseus-Computing-LLC/mimir "
+                    "or pass the absolute path via mimir_binary=."
+                )
+            self._mimir_binary = resolved
+
+        # Ensure the database directory exists.
+        os.makedirs(os.path.dirname(self.db_path) or ".", exist_ok=True)
+
+        # Start the Mimir MCP stdio subprocess.
+        self._proc = subprocess.Popen(
+            [self._mimir_binary, "--db", self.db_path],
+            stdin=subprocess.PIPE,
+            stdout=subprocess.PIPE,
+            stderr=subprocess.PIPE,
+            text=True,
+        )
+        self._lock = threading.Lock()
+        self._request_id = 0
+
+        # Initialize the MCP session.
+        self._rpc(
+            "initialize",
+            {
+                "protocolVersion": "2024-11-05",
+                "capabilities": {},
+                "clientInfo": {"name": "adk-mimir-memory-service", "version": "1.0"},
+            },
+        )
+
+        # Clean up the subprocess on exit.
+        atexit.register(self._close)
+
+    def _close(self) -> None:
+        """Terminates the Mimir 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 Mimir 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.
+        """
+        req = {
+            "jsonrpc": "2.0",
+            "id": self._next_id(),
+            "method": method,
+            "params": params,
+        }
+        payload = json.dumps(req, default=str)
+
+        with self._lock:
+            try:
+                self._proc.stdin.write(payload + "\n")
+                self._proc.stdin.flush()
+                raw = self._proc.stdout.readline()
+            except (BrokenPipeError, OSError) as e:
+                raise RuntimeError(
+                    f"Mimir subprocess communication failed: {e}. "
+                    "The mimir process may have crashed."
+                ) from e
+
+        try:
+            resp = json.loads(raw)
+        except json.JSONDecodeError as e:
+            raise RuntimeError(
+                f"Failed to parse Mimir response: {e}. Raw: {raw[:200]}"
+            ) from e
+
+        if "error" in resp:
+            err = resp["error"]
+            raise RuntimeError(
+                f"Mimir RPC error [{err.get('code')}]: {err.get('message')}"
+            )
+
+        return resp.get("result", {})
+
+    def _call_tool(self, name: str, arguments: dict) -> dict:
+        """Calls a Mimir 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 Mimir.
+
+        Each session is stored as a single Mimir 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
+
+        self._call_tool(
+            "mimir_remember",
+            {
+                "category": _MIMIR_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 Mimir.
+
+        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
+
+        import time
+
+        sid = session_id or "__unknown__"
+        delta_key = f"delta:{app_name}:{user_id}:{sid}:{int(time.time() * 1000)}"
+
+        self._call_tool(
+            "mimir_remember",
+            {
+                "category": _MIMIR_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 Mimir.
+
+        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
+
+            self._call_tool(
+                "mimir_remember",
+                {
+                    "category": _MIMIR_CATEGORY,
+                    "key": f"memory:{app_name}:{user_id}:{entry.id or i}",
+                    "body_json": json.dumps({
+                        "content": content_text,
+                        "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 Mimir for memories matching the query.
+
+        Uses Mimir's FTS5 keyword search.  Results are scoped to the given
+        application and user by filtering on the stored tags and body content.
+
+        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.
+        """
+        scoped_query = f"{query} {app_name} adk-memory {user_id}"
+        result = self._call_tool(
+            "mimir_recall",
+            {
+                "query": scoped_query,
+                "limit": 20,
+                "category": _MIMIR_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 = {}
+
+            # 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 "mimir",
+                    timestamp=body_data.get("timestamp")
+                    or _format_timestamp(
+                        item.get("created_at_unix_ms", 0) / 1000.0
+                    ),
+                )
+            )
+
+        return response

adk_mimir_memory-0.2.0/adk_mimir_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_mimir_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_mimir_memory-0.2.0/pyproject.toml

@@ -0,0 +1,36 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "adk-mimir-memory"
+version = "0.2.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 Mimir."
+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",
+]
+dependencies = [
+    "google-adk>=1.0.0",
+]
+
+[project.optional-dependencies]
+perseus = ["perseus-ctx"]
+
+[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"