ADK 的 Mimir Memory 集成¶

Supported in ADKPython

adk-mimir-memory 集成将你的 ADK 智能体连接到 Mimir，一个持久的跨会话记忆后端。它由一个带嵌入式 SQLite 数据库的单个 Rust 二进制文件支持，零云依赖，一切都在本地运行。记忆使用 AES-256-GCM 进行静态加密，搜索结合了 FTS5 关键词匹配和密集向量检索。

使用场景¶

跨重启的持久智能体记忆：会话在进程重启后存活，智能体自动回忆过去的对话
私有、离线部署：无云依赖，Mimir 完全在你的机器上运行，支持可选的 AES-256-GCM 加密
跨记忆的混合搜索：结合关键词（FTS5/BM25）和语义（密集向量）搜索来查找相关的历史交互
工作区感知智能体：与 Perseus 配对，让智能体了解你的项目文件、git 状态和配置

前置条件¶

Python 3.10+
mimir 二进制文件（参见安装）
google-adk>=1.0.0

安装¶

安装 Python 包：

pip install adk-mimir-memory

然后安装 mimir 二进制文件：从 Mimir 发布页面下载适合你平台的构建版本，并将其放在你的 PATH 上。服务默认查找 mimir，或向 MimirMemoryService 传递 mimir_binary="/absolute/path/to/mimir"。

与智能体配合使用¶

创建 MimirMemoryService，将其传递给你的 Runner，并为智能体提供 load_memory 工具，以便它可以回忆过去的会话：

from adk_mimir_memory import MimirMemoryService
from google.adk.agents import Agent
from google.adk.runners import Runner
from google.adk.sessions import InMemorySessionService
from google.adk.tools import load_memory

agent = Agent(
    name="memory_assistant",
    model="gemini-flash-latest",
    instruction="你是一个具有长期记忆的有用助手。",
    tools=[load_memory],
)

runner = Runner(
    agent=agent,
    app_name="mimir_app",
    session_service=InMemorySessionService(),
    memory_service=MimirMemoryService(db_path="~/.adk/mimir.db"),
)

会话完成后，调用 await memory_service.add_session_to_memory(session) 来持久化它。智能体在后续会话中通过 load_memory 工具回忆相关记忆。参见 ADK 记忆了解完整的摄取和回忆流程。

Perseus 实时上下文（可选）¶

要获得实时工作区感知，安装 perseus 附加组件：

pip install adk-mimir-memory[perseus]

然后使用预构建的 perseus_context_agent，它在推理时解析 @file、@search 和 @memory 指令：

from adk_mimir_memory.perseus_context import perseus_context_agent
from google.adk.runners import Runner
from google.adk.sessions import InMemorySessionService

# 预构建的智能体不包含模型；使用前请设置一个。
perseus_context_agent.model = "gemini-flash-latest"

runner = Runner(
    agent=perseus_context_agent,
    app_name="perseus_app",
    session_service=InMemorySessionService(),
    memory_service=MimirMemoryService(db_path="~/.adk/mimir.db"),
)

在创建会话时通过会话状态设置 Perseus 指令（在异步函数内）：

session = await runner.session_service.create_session(
    app_name="perseus_app",
    user_id="user",
    state={
        "_perseus_directives": "@file AGENTS.md @file README.md @memory deployment",
        "_perseus_workspace": "/path/to/project",
    },
)

可用记忆操作¶

方法	描述
`add_session_to_memory(session)`	持久化完整会话的事件
`add_events_to_memory(...)`	追加增量事件
`add_memory(...)`	存储显式记忆条目
`search_memory(...)`	跨记忆的 FTS5 关键词搜索

后端对比¶

后端	依赖项	静态加密	搜索	托管
InMemoryMemoryService	无	不持久化	关键词	本地（临时）
VertexAiMemoryBankService	Google Cloud	Google 托管（可选 CMEK）	语义（Gemini）	Google Cloud
VertexAiRagMemoryService	Google Cloud	Google 托管（可选 CMEK）	向量相似度	Google Cloud
MimirMemoryService	`mimir` 二进制文件	本地 AES-256-GCM（可选）	混合（FTS5 + 密集）	本地