为 Google ADK 智能体接入持久记忆hindsight-google-adk 集成实战指南【免费下载链接】hindsightHindsight: Agent Memory That Learns项目地址: https://gitcode.com/GitHub_Trending/hindsight2/hindsight本指南围绕 Hindsight 项目中的 Google ADK 官方集成hindsight-google-adk包展开讲解如何为 Google ADKAgent Development Kit智能体添加跨会话的长期记忆能力。读完本文你将掌握两种互补的接入模式——基于BaseMemoryService的自动记忆与基于FunctionTool的显式记忆工具并能熟练配置 Bank 划分、标签过滤、全局默认参数与生产部署方式。集成概览两种互补的记忆模式Google ADK 智能体默认只具备单次会话内的上下文能力会话结束后对话内容即被丢弃。Hindsight 提供的hindsight-google-adk包通过 集成文档 中定义的两种模式把 Hindsight 的长期记忆能力嵌入 ADK 的运行时HindsightMemoryService—— 实现 ADK 的BaseMemoryService抽象。将它传给Runner(memory_service...)后会话结束时由 ADK 生命周期自动触发 retain 将整个会话写入 Hindsight当智能体调用search_memory时集成层在同一个 Hindsight Bank 上执行 recall 并把结果转换为 ADK 的MemoryEntry对象返回。create_hindsight_tools(...)—— 返回一组 ADKFunctionToolhindsight_retain、hindsight_recall、hindsight_reflect让模型在单轮对话内部主动决定何时写入或检索记忆。两种模式互补前者零干预地自动沉淀对话后者赋予模型按需操作记忆的自主性二者可同时启用并共享同一个 Bank只要 Bank ID 对齐。推荐使用 Hindsight Cloud集成默认指向生产环境 API无需自行维护本地服务注册即可获得 API Key。安装包已发布到 PyPI使用pip直接安装pip install hindsight-google-adk根据 pyproject.toml 中的声明包依赖google-adk2.0与hindsight-client0.4.0要求 Python 3.10当前版本为0.1.0采用 MIT 许可。模式一自动记忆HindsightMemoryService这是将记忆接入 ADK 最省事的方式仅需三步构造服务、创建 Agent、把服务挂到 Runner 上。import asyncio from google.adk.agents import LlmAgent from google.adk.runners import Runner from google.adk.sessions import InMemorySessionService from hindsight_google_adk import HindsightMemoryService memory HindsightMemoryService.from_url( hindsight_api_urlhttps://api.hindsight.vectorize.io, api_keyhsk_..., ) agent LlmAgent(nameassistant, modelgemini-2.0-flash) runner Runner( app_namemy-app, agentagent, session_serviceInMemorySessionService(), memory_servicememory, ) # ... use runner.run_async(...) as normal. Memory is automatic.HindsightMemoryService实现了 ADK 的BaseMemoryService见 memory.py这意味着它对 ADK 运行时是透明的Runner在会话结束时调用add_session_to_memory把会话的全部事件按作者: 内容逐行拼接retain 到由(app_name, user_id)推导出的 Hindsight Bank智能体调用search_memory时服务在相同 Bank 上执行 recall并把结果包装成带authorhindsight、保留原始时间戳的MemoryEntry列表返回。写入细节事件如何变成记忆文档从 memory.py 的实现可以看到会话文本的组装逻辑遍历会话事件抽取每个事件文本 part跳过无文本内容的事件最终生成多行文本如果会话为空或全部事件无文本则直接跳过 retain对应测试 test_memory.py 中test_empty_session_does_not_retain等用例。retain 时以session.id作为document_id这保证了同一会话的重复写入会覆盖而不是累积避免同一对话内容被反复沉淀造成冗余。除BaseMemoryService的会话级入口外服务还实现了add_events_to_memory按事件增量写入document_id形如{session_id}-{随机8位}并附带session:{session_id}标签与add_memory逐条写入显式MemoryEntry把memory.author与custom_metadata并入元数据覆盖了 ADK 记忆接口的完整调用面。搜索细节recall 到 MemoryEntry 的映射search_memory调用hindsight_client的arecall并固定追加user:{user_id}过滤标签确保用户之间互不可见。每个召回结果被映射为 ADK 的MemoryEntrycontent为包含结果文本的genai.types.Contentauthor固定为hindsightid与timestamp取自结果的occurred_start原样透传。这一映射逻辑与测试 test_memory.py 中test_results_mapped_to_memory_entries的断言完全一致。Bank ID 派生规则默认情况下每个(app_name, user_id)组合对应一个独立 Bank模板为{app_name}::{user_id}。Bank ID 由_bank_id方法对模板做str.format(app_name..., user_id...)得到见 memory.py因此可用bank_id_template灵活定制隔离粒度# 按用户隔离、跨应用共享同一用户在所有 app 中看到同一份记忆 HindsightMemoryService.from_url( hindsight_api_urlhttps://api.hindsight.vectorize.io, api_keyhsk_..., bank_id_templateuser::{user_id}, ) # 静态 Bank所有用户共享一份记忆适合全局知识库场景 HindsightMemoryService.from_url( hindsight_api_urlhttps://api.hindsight.vectorize.io, api_keyhsk_..., bank_id_templatemy-shared-bank, )测试 test_memory.py 验证了默认模板与自定义模板的派生行为如apple::alice、ns::bob。选择模板时务必考虑数据隔离需求默认的app::user模板已实现用户级隔离切勿在生产环境中把多租户数据放进同一个静态 Bank。模式二显式工具FunctionTool当你希望模型在对话中途自主决定记忆的写入与读取时机时使用create_hindsight_toolsfrom google.adk.agents import LlmAgent from hindsight_google_adk import create_hindsight_tools tools create_hindsight_tools( bank_iduser-123, hindsight_api_urlhttps://api.hindsight.vectorize.io, api_keyhsk_..., ) agent LlmAgent( nameassistant, modelgemini-2.0-flash, toolstools, )工厂函数见 tools.py返回三个FunctionTool可用include_retain/include_recall/include_reflect开关按需裁剪对应测试 test_tools.py工具签名职责hindsight_retainhindsight_retain(content)将信息存入长期记忆返回Memory stored successfully.hindsight_recallhindsight_recall(query)检索记忆返回带编号的匹配列表如1. first、2. second无结果时返回友好提示No relevant memories found.hindsight_reflecthindsight_reflect(query)基于记忆综合生成连贯回答而非原始事实列表返回综合文本工具级高级参数除了文档中的基础参数工厂还透传了一批工具级配置见 tools.py 的参数签名retain_metadata/retain_document_id为 retain 操作指定默认元数据与文档 ID可用于把多条记忆归并到同一文档实现覆盖式更新recall_types按事实类型world/experience/observation过滤召回结果recall_include_entities在召回结果中包含实体信息reflect_context/reflect_max_tokens/reflect_response_schema为 reflect 提供额外上下文、独立的 token 上限默认回退到max_tokens以及用 JSON Schema 约束输出结构reflect_tags/reflect_tags_match为 reflect 指定独立的记忆过滤标签默认回退到recall_tags/recall_tags_match。这些参数均可由测试用例印证例如 test_tools.py 验证了reflect_context与reflect_response_schema会被透传到areflect。全局配置configure当应用内多处需要连接 Hindsight 时可在启动时调用一次configure(...)设置全局默认值之后的HindsightMemoryService.from_url()与create_hindsight_tools()调用会自动以此为兜底from hindsight_google_adk import configure configure( hindsight_api_urlhttps://api.hindsight.vectorize.io, api_keyNone, # 不传则回退到 HINDSIGHT_API_KEY 环境变量 budgetmid, max_tokens4096, bank_id_template{app_name}::{user_id}, )从 config.py 的实现看configure的解析优先级为显式参数 HINDSIGHT_API_KEY环境变量 内置默认值并返回一个HindsightAdkConfig数据类实例。客户端解析逻辑见 _client.py则按显式client参数 显式 URL/Key 全局配置 报错的次序解析连接若最终既无 URL 也无全局配置会抛出HindsightError提示先调用configure()或传入连接参数。测试 test_config.py 覆盖了 Key 的优先级与环境变量回退行为。另外HindsightAdkConfig还暴露了verbose开关默认关闭用于开启集成层的详细日志reset_config()可清空全局配置便于测试隔离。配置参考以下配置项同时适用于HindsightMemoryService.from_url()、create_hindsight_tools()与configure()后两者共享同一份默认值见 config.py参数默认值说明hindsight_api_urlhttps://api.hindsight.vectorize.ioHindsight API 地址默认指向云服务api_keyHINDSIGHT_API_KEY环境变量Hindsight Cloud 的 Bearer Tokenbank_id_template{app_name}::{user_id}从 ADK 的app_name/user_id推导 Bank ID 的格式化模板budgetmid召回预算级别low/mid/highmax_tokens4096召回结果的最大 token 数tagsNone附加到每条 retain 文档上的标签app:name与user:id总是会被自动添加recall_tagsNone追加到每次召回查询上的标签user:id总是会被自动添加recall_tags_matchany标签匹配模式any/all/any_strict/all_strictmissionNone若设置首次使用时以该事实抽取使命幂等地创建 Bankcontextgoogle-adk附加到 retain 内容的来源标签即 Hindsight 的 provenance 字段其中mission的行为可在 memory.py 的_ensure_bank中看到只有当 mission 非空且该 Bank 尚未处理过时才调用acreate_bank并缓存 Bank ID保证幂等测试 test_memory.py 验证了同一 Bank 只创建一次、无 mission 时不创建。预置标签与元数据无论采用哪种模式retain 时都会自动写入结构化元数据见 memory.py标签固定包含app:{app_name}与user:{user_id}再加自定义tags元数据固定包含app_name、user_id、source: google-adk可再并入custom_metadata/MemoryEntry.author。recall 时则固定追加user:{user_id}过滤标签。这套设计保证了用户永远只能召回自己的记忆即使多个用户共用同一个 Bank 模板也不会串数据。生产环境实践按环境给记忆打标签利用自动附加的app:/user:标签之外的自定义标签可以按环境隔离记忆并精确控制召回范围HindsightMemoryService.from_url( hindsight_api_urlhttps://api.hindsight.vectorize.io, api_keyhsk_..., tags[env:prod], # retain 时附加 recall_tags[env:prod],# 召回时仅命中该标签 )这样生产环境的记忆不会被开发/预发环境的数据污染app:与user:标签始终在此基础上自动添加见 test_memory.py 的断言。自托管 Hindsight无需认证的本地服务可直接省略api_keyHindsightMemoryService.from_url( hindsight_api_urlhttp://localhost:8888, )如需自托管部署方式可参考仓库中的 docker/docker-compose 目录下的各类编排模板。结合两种模式自动记忆与显式工具并不互斥——Runner(memory_serviceHindsightMemoryService(...))负责会话结束时的自动沉淀toolscreate_hindsight_tools(...)让模型在轮次内主动 recall/reflect。只要两者的 Bank ID 保持一致它们读写的就是同一份记忆。源码级可靠性设计错误处理策略自动模式吞错、工具模式抛错这是一个值得注意的设计差异两处实现分别为 memory.py 与 tools.py自动记忆模式HindsightMemoryService所有add_*与search_memory方法对 Hindsight 失败一律记录日志、不向上抛保证记忆服务故障不会拖垮整个 ADK Runner 主流程search_memory失败时返回空结果而非异常。测试 test_memory.py 与test_recall_failure_returns_empty对此有专门覆盖。显式工具模式create_hindsight_tools底层调用失败时包装为HindsightError抛出让模型感知到工具失败并决定下一步动作如重试或告知用户。连接层细节客户端解析见 _client.py为不同操作设置了差异化超时retain 15 秒、recall 10 秒、reflect 30 秒、Bank 创建 15 秒、默认 30 秒并为所有请求附加hindsight-google-adk/{version}的 User-Agent便于服务端追踪集成来源。端到端验证smoke 脚本仓库提供了完整的端到端冒烟脚本 smoke_runner.py使用真实的 Gemini 模型驱动的Runner验证跨会话记忆是理解集成完整链路的绝佳参考阶段一自动记忆会话 A 中告知 Agent我叫 Ben喜欢 Rust养了条叫 Pixel 的狗会话结束后手动触发add_session_to_memory沉淀会话 B 中询问我的偏好与狗的名字Agent 通过load_memory_tool触发search_memory从 Hindsight 召回并作答。阶段二显式工具会话 C 中让 Agent 调用hindsight_retain存入开 Tesla Model 3、喝燕麦拿铁短暂等待写入提交后会话 D 中让 Agent 调用hindsight_recall检索并回答。脚本要求设置GOOGLE_API_KEY与HINDSIGHT_API_KEY环境变量HINDSIGHT_API_URL默认指向开发云并通过输出中是否命中 rust/pixel/tesla/latte 等关键词判定各阶段 PASS/FAIL。运行要求Python 3.10google-adk2.0hindsight-client0.4.0本文所有结论均可对照 集成文档、集成包源码 及其 单元测试 逐项验证。接入完成后你的 ADK 智能体便拥有了跨会话、跨应用、按用户隔离的长期记忆能力。【免费下载链接】hindsightHindsight: Agent Memory That Learns项目地址: https://gitcode.com/GitHub_Trending/hindsight2/hindsight创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考