
Hindsight-CrewAI为 CrewAI 智能体团队接入 Hindsight 持久化长期记忆【免费下载链接】hindsightHindsight: Agent Memory That Learns项目地址: https://gitcode.com/GitHub_Trending/hindsight2/hindsightHindsight-CrewAI 是 Hindsight 官方提供的 CrewAI 集成包hindsight-crewai通过实现 CrewAIExternalMemory的Storage接口让多智能体团队Crew获得跨运行的持久化记忆任务产出自动存入 Hindsight任务开始前自动召回相关记忆并可通过 Reflect 工具对记忆做情境化合成推理。读完本文你将掌握该集成的完整安装、配置参数、记忆流转机制、按 Agent 隔离记忆库的方法以及其底层异步兼容实现。集成特性总览根据集成包文档与源码HindsightStorage提供以下能力即插即用的 Storage 后端实现 CrewAIStorage接口的save/search/reset三个方法直接作为ExternalMemory的存储层自动记忆流转CrewAI 在每个任务开始时自动查询记忆、任务完成后自动存储任务输出无需手写读写逻辑按 Agent 隔离的记忆库可选可为每个 Agent 分配独立的 Hindsight memory bank避免不同角色的记忆互相污染Reflect 工具CrewAI 的 Storage 接口只支持存取与重置集成包额外提供HindsightReflectTool让 Agent 显式调用 Hindsight 的reflect能力获得基于 bank 人格/处置disposition的合成式回答而非原始事实列表一次配置全局生效通过configure()全局配置连接与默认参数各 Storage 实例再按需覆盖。安装pip install hindsight-crewai版本前提以 pyproject.toml 为准要求Python 3.10依赖crewai0.86.0,1.10——源码注释明确指出 CrewAI 1.10 已将Storage更名为StorageBackend该集成尚未迁移因此升级 CrewAI 前需留意此约束依赖hindsight-client0.4.0即所有 API 调用retain / recall / reflect / create_bank / delete_bank均走 Hindsight Python Client包内还显式声明了若干传递依赖的安全下限cryptography、pillow、pyjwt、requests用于修复对应上游的安全通告。快速开始集成支持指向 Hindsight Cloud默认或自托管服务。官方快速上手示例from hindsight_crewai import configure, HindsightStorage from crewai.memory.external.external_memory import ExternalMemory from crewai import Agent, Crew, Task # Step 1: 指向 Hindsight Cloud configure( hindsight_api_urlhttps://api.hindsight.vectorize.io, api_keyhsk_..., # 或设置 HINDSIGHT_API_KEY 环境变量 ) # Step 2: 创建带 Hindsight 记忆后端的 crew crew Crew( agents[ Agent(roleResearcher, goalFind information, backstory...), Agent(roleWriter, goalWrite reports, backstory...), ], tasks[ Task(descriptionResearch AI trends, expected_outputReport), ], external_memoryExternalMemory( storageHindsightStorage(bank_idmy-crew) ), ) crew.kickoff()这样就完成了。CrewAI 会自动在每个任务开始时查询记忆调用search在每个任务完成后把任务输出存入 Hindsight调用save。记忆跨 crew 运行持久保留你的团队会随着运行次数积累知识。本地自托管开发场景如果在本地通过./scripts/dev/start-api.sh运行 Hindsight 服务该脚本存在于 scripts/dev/start-api.sh只需把地址指向本地configure(hindsight_api_urlhttp://localhost:8888)自动记忆流转的底层映射HindsightStorage的文档字符串见 storage.py明确了 CrewAI 接口到 Hindsight API 的映射关系CrewAI Storage 方法触定时机映射的 Hindsight 调用save(value, metadata, agent)每个任务完成后client.retain(bank_id, content)search(query, limit)每个任务开始前client.recall(bank_id, query)reset()手动调用client.delete_bank() 重新创建源码层面有几个值得注意的实现细节写入侧。save()会把任务输出连同固定元数据一起retain元数据中强制写入source: crewai如果 CrewAI 提供了产出该输出的 Agent 角色名还会写入agent字段CrewAI 传入的metadata值会被统一str()转成字符串Hindsight 的 retain 要求dict[str, str]。context参数固定为crewai:task_output:{agent或unknown}格式。若 retain 失败会抛出HindsightError定义于 errors.py。读取侧。search()内部调用client.recall(bank_id, query, budget, max_tokens)并按需附加tags/tags_match过滤参数。由于 Hindsight 返回的是按相关性排序的结果而接口需要score字段源码采用合成分数score 1.0 - (i / total)i 为结果下标首条为 1.0、逐条递减低于score_threshold的结果会被截断丢弃同时把 Hindsight 结果的type、source_context、occurred_start、document_id、tags等富元数据透传给 CrewAI。重置侧。reset()是尽力而为best-effort操作删除 bank 失败时只记录警告而不抛异常避免清理逻辑中断主流程。以上行为均有对应的单元测试佐证例如 tests/test_storage.py 中的test_save_stringifies_metadata_values验证元数据字符串化、test_search_synthetic_scores_descend验证合成分数单调递减与test_reset_is_best_effort验证 reset 不抛异常。异步环境下的同步调用兼容CrewAI 运行在 asyncio 事件循环内而 Hindsight Client 的同步方法内部会调用loop.run_until_complete()——在主循环已在运行时这必然失败。集成包为此提供了专门的兼容层 _compat.py全局维护一个max_workers2的专用线程池所有 Hindsight API 调用都通过call_sync()提交到该池执行每个工作线程首次使用时绑定一个持久化的独立事件循环asyncio.new_event_loop()set_event_loop保证底层 aiohttp 会话始终绑定同一个稳定循环规避 Event loop is closed 与跨线程循环引用问题call_sync的future.result(timeout60)提供了 60 秒的整体超时上限。同时HindsightStorage与HindsightReflectTool都采用threading.local()为每个线程维护独立的 Hindsight 客户端实例超时 30 秒User-Agent 为hindsight-crewai/{版本}使连接对象与线程/事件循环一一对应。按 Agent 隔离记忆库默认情况下 crew 内所有 Agent 共享同一个 bank。若希望每个 Agent 拥有独立记忆可启用per_agent_banksstorage HindsightStorage( bank_idmy-crew, per_agent_banksTrue, # Researcher - my-crew-researcher, Writer - my-crew-writer )从源码看_resolve_bank_id()的规则是将 Agent 角色名小写化并把空格替换为连字符再拼接为f{bank_id}-{sanitized_agent}agent为None时回退到基础 bank_id。若需要完全自定义命名规则可传入bank_resolver回调优先级高于per_agent_banksstorage HindsightStorage( bank_idmy-crew, bank_resolverlambda base, agent: f{base}-{agent.lower()} if agent else base, )一个值得注意的细节只有save()写入会按 Agent 解析 banksearch()读取固定使用基础 bank_id。也就是说 per-agent bank 隔离的是谁的记忆写到哪而任务开始时的自动检索仍发生在共享的 crew 级 bank 上——如果需要跨角色共享知识的同时隔离角色私有记忆可结合bank_resolver自行设计读写策略。相关行为可参考 tests/test_storage.py 中test_per_agent_banks_resolves_bank_id与test_save_uses_per_agent_bank两个用例。HindsightReflectTool让 Agent 主动反思记忆CrewAI 的 Storage 接口只有 save/search/reset无法触达 Hindsight 的reflect能力基于 bank 的处置/人格对全部相关记忆做合成式推理。集成包因此把它暴露为 CrewAI 工具from hindsight_crewai import HindsightReflectTool reflect_tool HindsightReflectTool( bank_idmy-crew, budgetmid, reflect_contextYou are helping a software team track decisions., ) agent Agent( roleAnalyst, goalAnalyze project history, backstory..., tools[reflect_tool], )工具参数定义于 tools.py参数说明bank_id要反思的 Hindsight memory bank IDhindsight_api_url/api_key可选覆盖全局配置的地址与密钥budgetReflect 预算档位low/mid/high默认midreflect_context附加给 reflect 推理的上下文说明实现上工具注册名为hindsight_reflect_run(query)调用client.reflect(bank_id, query, budget, context)并返回合成后的文本回答若 Hindsight 未返回任何内容会兜底返回No relevant memories found to reflect on.而不是抛错。当 Agent 调用该工具时得到的是基于全部相关记忆的情境化合成答案而不是原始事实条目。Bank Mission引导记忆的组织方式通过mission参数可以为 bank 设定使命声明指导 Hindsight 处理和整理记忆的方式storage HindsightStorage( bank_idmy-crew, missionTrack software architecture decisions, technical debt, and team preferences., )从源码看mission有两个作用点构造时如果提供了 mission会立即调用client.create_bank(bank_id, namebank_id, missionmission)创建/更新 bank幂等bank 已存在时只记录警告并继续reset()重新创建 bank 时也会带上原 mission。未设置 mission 时bank 会在首次save()时按需惰性创建。配置体系全局配置configure()的完整签名与语义见 config.pyfrom hindsight_crewai import configure configure( hindsight_api_urlhttps://api.hindsight.vectorize.io, # Hindsight Cloud默认 api_keyyour-api-key, # 或设置 HINDSIGHT_API_KEY 环境变量 budgetmid, # 召回预算low/mid/high max_tokens4096, # 召回结果的最大 token 数 tags[env:prod], # 存储记忆时附加的标签 recall_tags[scope:global], # 召回时用于过滤的标签 recall_tags_matchany, # 标签匹配模式any/all/any_strict/all_strict verboseTrue, # 开启详细日志 )实现要点configure()把结果保存为模块级全局单例HindsightCrewAIConfigdataclassapi_key在未显式传入时自动回退读取HINDSIGHT_API_KEY环境变量hindsight_api_url未传入时回退到默认的 Cloud 地址。包还导出get_config()与reset_config()后者常用于测试中清理全局状态。每实例覆盖HindsightStorage的构造参数优先于全局配置逐项回退链为构造参数 → 全局配置 → 内置默认值默认值url 为 Cloud 地址、budgetmid、max_tokens 4096、tags/recall_tags 为 None、matchany、verbose False。例如storage HindsightStorage( bank_idmy-crew, budgethigh, # 覆盖全局 budget max_tokens8192, # 覆盖全局 max_tokens tags[team:alpha], # 覆盖全局 tags )tests/test_storage.py 中test_constructor_overrides_config、test_falls_back_to_config、test_falls_back_to_defaults_without_config三个用例分别验证了这条覆盖链的三层行为。完整参数参考参数默认值说明hindsight_api_urlHindsight Cloudhttps://api.hindsight.vectorize.ioHindsight API 地址api_keyHINDSIGHT_API_KEY环境变量认证用 API Keybudgetmid召回预算档位low/mid/highmax_tokens4096召回结果的最大 token 数tagsNone存储记忆时应用的标签recall_tagsNone检索时用于过滤的标签recall_tags_matchany标签匹配模式per_agent_banksFalse为每个 Agent 分配独立 bankbank_resolverNone自定义 (bank_id, agent) - bank_id 函数missionNone用于记忆组织的 bank 使命声明verboseFalse开启详细日志端到端本地验证仓库提供了可直接运行的手动集成测试 test_manual.py前置条件本地 Hindsight API 运行在localhost:8888./scripts/dev/start-api.sh启动、设置OPENAI_API_KEY或为 CrewAI 配置其他 LLM 提供商、在本目录执行uv pip install -e .然后uv run python test_manual.py。该脚本演示了完整的记忆生命周期冒烟测试不依赖 LLM直接storage.save(...)→storage.search(...)→ 打印带分数的召回结果Run 1Researcher Writer 双 Agent crew 研究函数式编程并生成摘要任务产出自动写入 bankmission 为 Track research findings and summaries for a software team.Run 2新 crew 中要求 Researcher 使用 hindsight_reflect 工具回忆之前研究过的内容验证跨运行记忆召回清理storage.reset()删除整个 bank。小结hindsight-crewai用极小的接口面一个 Storage 类 一个 Tool 类 一个全局configure把 Hindsight 的 retain/recall/reflect 能力接入了 CrewAI 的外部记忆体系并针对 CrewAI 的 asyncio 运行环境做了专用的线程池事件循环隔离。核心路径回顾全局配置与默认值解析hindsight_crewai/config.pyStorage 接口到 retain/recall/delete_bank 的映射hindsight_crewai/storage.pyreflect 工具实现hindsight_crewai/tools.py异步兼容层hindsight_crewai/_compat.py单元与行为测试hindsight-integrations/crewai/tests/test_storage.py端到端手动验证脚本hindsight-integrations/crewai/test_manual.py需要注意的适用前提当前版本锁定crewai1.10因 1.10 接口更名生产引入前请按自身 CrewAI 版本核对兼容性。【免费下载链接】hindsightHindsight: Agent Memory That Learns项目地址: https://gitcode.com/GitHub_Trending/hindsight2/hindsight创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考