ADK 的 Perseus Vault 记忆集成¶

Supported in ADKPython

adk-perseus-vault-memory 集成将你的 ADK 智能体连接到 Perseus Vault，一个持久化、跨会话的记忆后端。它由单个 Rust 二进制文件和嵌入式 SQLite 数据库支持，无需任何云依赖，一切都在本地运行。记忆通过 AES-256-GCM 加密存储，搜索结合了 FTS5 关键词匹配和密集向量检索。

使用场景¶

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

前置条件¶

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

安装¶

安装 Python 包：

pip install adk-perseus-vault-memory

然后安装 perseus-vault 二进制文件：从 releases 页面下载适用于你平台的构建文件，并将其放在你的 PATH 中。默认情况下，服务会查找 perseus-vault，或者将 vault_binary="/absolute/path/to/perseus-vault" 传递给 PerseusVaultMemoryService。

与智能体一起使用¶

创建 PerseusVaultMemoryService，将其传递给你的 Runner，并给智能体提供 load_memory 工具，使其能够回忆过去的会话：

from adk_perseus_vault_memory import PerseusVaultMemoryService
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="You are a helpful assistant with long-term memory.",
    tools=[load_memory],
)

runner = Runner(
    agent=agent,
    app_name="perseus_vault_app",
    session_service=InMemorySessionService(),
    memory_service=PerseusVaultMemoryService(db_path="~/.adk/vault.db"),
)

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

Perseus 实时上下文（可选）¶

要获得实时工作区感知，请安装 perseus 扩展：

pip install adk-perseus-vault-memory[perseus]

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

from adk_perseus_vault_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=PerseusVaultMemoryService(db_path="~/.adk/vault.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 托管	语义（Gemini）	Google Cloud
VertexAiRagMemoryService	Google Cloud	Google 托管	向量相似度	Google Cloud
PerseusVaultMemoryService	`perseus-vault` 二进制文件	本地 AES-256-GCM	混合（FTS5 + 密集向量）	本地