Skip to content

用于 ADK 的 GoodMem 插件 (GoodMem)

Supported in ADKPython

GoodMem ADK 插件 将你的 ADK 智能体连接到 GoodMem（一种基于向量的语义记忆服务）。此集成使你的智能体拥有跨对话的持久、可搜索记忆，使其能够回忆起过去的交互历史、用户偏好以及上传的文档内容。

共有两种集成方式：

方式 描述
插件 (GoodmemPlugin) 隐式的、确定性的记忆，通过 ADK 回调在每一轮对话中实现。自动保存所有对话回合和文件附件。
工具 (GoodmemSaveTool, GoodmemFetchTool) 显式的、由智能体自主控制的记忆。智能体自行决定何时保存和检索信息。

使用场景

  • 智能体的持久化记忆：赋予你的智能体可以在跨对话中依赖的长期记忆。
  • 自动化的多模态记忆管理：自动保存并检索对话中的信息，包括用户消息、智能体响应以及文件附件（PDF、DOCX 等）。
  • 延续上下文：智能体可以回忆起你是谁、曾经讨论过的内容以及已解决的方案，从而节省 Token 消耗并避免重复劳动。

先决条件

  • 拥有一个 GoodMem 实例（自托管或云端）。
  • 获取 GoodMem API 密钥。
  • 准备好 Gemini API 密钥（用于利用 Gemini 自动创建向量嵌入）。

安装

pip install goodmem-adk

在智能体中使用

import os
from google.adk.agents import LlmAgent
from google.adk.apps import App
from goodmem_adk import GoodmemPlugin

plugin = GoodmemPlugin(
    base_url=os.getenv("GOODMEM_BASE_URL"),  # 例如 "http://localhost:8080"
    api_key=os.getenv("GOODMEM_API_KEY"),
    top_k=5,  # 每轮检索的记忆条数
)

agent = LlmAgent(
    name="memory_agent",
    model="gemini-2.0-flash",
    instruction="你是一个具有持久记忆的得力助手。",
)

app = App(name="GoodmemPluginDemo", root_agent=agent, plugins=[plugin])

import os
from google.adk.agents import LlmAgent
from google.adk.apps import App
from goodmem_adk import GoodmemSaveTool, GoodmemFetchTool

save_tool = GoodmemSaveTool(
    base_url=os.getenv("GOODMEM_BASE_URL"),  # 例如 "http://localhost:8080"
    api_key=os.getenv("GOODMEM_API_KEY"),
)
fetch_tool = GoodmemFetchTool(
    base_url=os.getenv("GOODMEM_BASE_URL"),
    api_key=os.getenv("GOODMEM_API_KEY"),
    top_k=5,
)

agent = LlmAgent(
    name="memory_agent",
    model="gemini-2.0-flash",
    instruction="你是一个具有持久记忆的得力助手。",
    tools=[save_tool, fetch_tool],
)

app = App(name="GoodmemToolsDemo", root_agent=agent)

可用工具

插件回调

GoodmemPlugin 使用 ADK 回调机制来自动管理记忆：

回调 描述
on_user_message_callback 将用户消息和文件附件保存到记忆中
before_model_callback 检索相关记忆并将其注入到提示词（Prompt）中
after_model_callback 将智能体的响应内容保存到记忆中

这些回调是确定性的，在每次智能体交互期间运行，将所有通过智能体传递的信息保存到记忆中。智能体本身不需要决定何时保存或检索信息。

工具

当使用工具方式集成时，智能体可以访问：

工具 描述
goodmem_save 将文本内容和文件附件保存到持久记忆中
goodmem_fetch 使用语义相似度查询搜索记忆

这些工具由智能体按需调用，智能体可以根据对话上下文灵活选择何时保存（可能包含重写内容）或检索信息。

配置

环境变量

变量 是否必填 描述
GOODMEM_BASE_URL 是 GoodMem 服务器 URL（不带 /v1 后缀）
GOODMEM_API_KEY 是 GoodMem 的 API 密钥
GOOGLE_API_KEY 是 用于自动创建 Gemini 向量嵌入的 API 密钥
GOODMEM_EMBEDDER_ID 否 指定特定的嵌入器 ID（必须已存在）
GOODMEM_SPACE_ID 否 指定特定的记忆空间 ID（必须已存在）
GOODMEM_SPACE_NAME 否 覆盖默认空间名称（如果缺失则自动创建）

空间解析

如果没有手动配置空间，系统将为每个用户自动创建一个空间：

  • 插件方式：adk_chat_{user_id}
  • 工具方式：adk_tool_{user_id}

其他资源