https://github.com/perseus-computing-llc/adk-mimir-memory
Persistent, local, encrypted cross-session memory for Google ADK agents — backed by Mimir.
https://github.com/perseus-computing-llc/adk-mimir-memory
Last synced: 2 days ago
JSON representation
Persistent, local, encrypted cross-session memory for Google ADK agents — backed by Mimir.
- Host: GitHub
- URL: https://github.com/perseus-computing-llc/adk-mimir-memory
- Owner: Perseus-Computing-LLC
- License: mit
- Created: 2026-06-26T03:36:32.000Z (3 days ago)
- Default Branch: main
- Last Pushed: 2026-06-26T17:52:31.000Z (3 days ago)
- Last Synced: 2026-06-26T18:21:53.407Z (3 days ago)
- Language: Python
- Homepage: https://perseus.observer/mimir/
- Size: 12.7 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# 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.