hindsight-litellm 集成完全指南Hindsight 记忆体系接入 LiteLLM 的架构、配置与版本演进【免费下载链接】hindsightHindsight: Agent Memory That Learns项目地址: https://gitcode.com/GitHub_Trending/hindsight2/hindsight本篇技术指南围绕 Hindsight 官方 LiteLLM 集成hindsight-litellm展开系统讲解它如何在任意 LiteLLM 支持的 LLM 应用之上叠加持久记忆能力并完整梳理 0.5.0 → 0.5.4 的版本演进脉络。读完本文你将掌握该集成的安装配置、configure/set_defaults/逐调用覆盖三层配置体系、reflect 与 recall 两种记忆模式、直接记忆 API、原生客户端包装器与流式响应支持并能在源码层面理解每次版本修复背后的实现细节。该集成属于 Hindsight 生态中的hindsight-integrations/litellm包源码位于 hindsight-integrations/litellm其完整使用文档见 LiteLLM 集成文档版本变更记录即本文所述内容对应 changelog。集成定位为什么要在 LiteLLM 之上再建一层记忆LiteLLM 是业界常用的统一 LLM 网关一套 API 对接 OpenAI、Anthropic、Groq、Azure OpenAI、AWS Bedrock、Google Vertex AI 等 100 提供方。hindsight-litellm的价值在于在不改变你现有 LiteLLM 调用方式的前提下为任何 LLM 应用加上会学习、可召回的持久记忆——这正是 Hindsight Agent Memory That Learns 项目愿景在 LiteLLM 生态中的落地形态。从包描述pyproject.toml可以看到它的核心卖点Universal LLM memory integration via LiteLLM - works with 100 providers。你只需配置 → 设默认值 → 启用 → 调用hindsight_litellm.completion()四步记忆的注入与存储便自动发生。五分钟上手安装与 Quick Start安装pip install hindsight-litellm集成依赖两个核心包见 pyproject.tomlhindsight-client0.4.0提供 Hindsight 的 API 客户端litellm1.93.0非 macOSmacOS 上无对应 wheel放宽为litellm1.91.3,1.92。文档要求的最低版本为litellm 1.83.0当前仓库已为供应链安全把下限提高到 1.93.0并额外锁定aiohttp3.14.3、filelock3.20.3、urllib32.6.3、requests2.33.0等传递依赖的安全修复版本。Quick Startimport hindsight_litellm # Step 1: 配置静态设置 hindsight_litellm.configure( hindsight_api_urlhttp://localhost:8888, verboseTrue, ) # Step 2: 设置默认值bank_id 必填 hindsight_litellm.set_defaults( bank_idmy-agent, use_reflectTrue, # 使用 reflect 获取综合上下文 ) # Step 3: 启用记忆集成 hindsight_litellm.enable() # Step 4: 带记忆调用 completion response hindsight_litellm.completion( modelgpt-4o-mini, messages[{role: user, content: What did we discuss about AI?}], hindsight_queryWhat do I know about AI discussions?, )关键点当inject_memoriesTrue默认开启时hindsight_query用于指定从记忆中检索什么。若不提供集成会自动回退使用最近一条用户消息作为查询——这个回退行为正是 0.5.0 版本修复项之一详见下文版本演进。从源码看_inject_memories查询解析顺序为hindsight_query参数 →defaults.query默认值 → 反向扫描 messages 中最后一条 user 消息同时支持纯文本与多模态结构化 content 列表。核心工作流记忆注入与对话存储的完整链路当调用completion()时集成自动完成五步记忆检索LLM 调用前——向 Hindsight 查询与对话相关的记忆use_reflectFalse时走 recall 返回原始事实use_reflectTrue时走 reflect 返回综合上下文提示注入——把记忆写进 system message默认或拼到最后一条 user 消息前LLM 调用——将增强后的 prompt 发给模型对话存储LLM 调用后——对话内容异步写入 Hindsight 供未来召回返回响应——你拿到的响应与普通 LiteLLM 调用完全一致。注入的两种形态Recall 模式原始事实列表hindsight_litellm.set_defaults(bank_idmy-agent, use_reflectFalse) # 注入形如 # 1. [WORLD] User prefers Python # 2. [OBSERVATION] User dislikes Java...Reflect 模式综合上下文段落hindsight_litellm.set_defaults(bank_idmy-agent, use_reflectTrue) # 注入形如 # Based on previous conversations, the user is a Python developer who...Reflect context塑造推理而非影响检索hindsight_litellm.set_defaults( bank_idmy-agent, use_reflectTrue, reflect_contextI am a delivery agent looking for package recipients., )从源码看注入内容的组装逻辑位于_inject_memoriesrecall 模式下每条记忆被格式化为序号. [类型] 文本统一加上# Relevant Memories标题reflect 模式则生成# Relevant Context from Memory段落。注入位置由injection_mode决定——system_message会追加到已有 system message 或新建一条prepend_user则逆序找到最后一条 user 消息把记忆上下文拼到其内容之前字符串或结构化 content 列表均兼容。对话存储的细节全量 UPSERT 而非增量追加回调实现callbacks.py中的_plan_store有一段重要设计说明每次存储发送的是完整对话历史而非新增片段。原因在于 Hindsight 的 retain API 配合document_id执行的是 UPSERT整体替换语义如果只发送增量Hindsight 只会看到最新片段而丢失前文上下文。通过每次携带完整对话配合session_id/document_id对会话分组最终文档始终包含完整对话供事实抽取。此外存储前还会计算user_input|assistant_output的 MD5 哈希做去重_compute_conversation_hash避免重复写入同一轮对话。存储的消息会做角色归一化处理system 消息与注入的记忆上下文会被跳过避免把记忆本身当对话存回记忆tool 消息转为TOOL_RESULT:带tool_calls的助手消息转为ASSISTANT_TOOL_CALLS:最终以USER:/ASSISTANT:分段拼接。配置体系configure / set_defaults / 逐调用覆盖集成将 API 拆成两个层级再加上逐调用覆盖共三层配置对应源码 config.py 中的HindsightConfig与HindsightCallSettings两个 dataclass。1.configure()——静态设置连接级配置会话中通常不变hindsight_litellm.configure( # 必填 hindsight_api_urlhttp://localhost:8888, # Hindsight API 服务地址 # 可选 - 认证 api_keyyour-api-key, # Hindsight 认证密钥 # 可选 - 记忆行为 store_conversationsTrue, # LLM 调用后是否存储对话 inject_memoriesTrue, # 是否把相关记忆注入 prompt sync_storageFalse, # False 异步存储默认性能更好 # True 同步存储阻塞立即抛出错误 # 可选 - 高级 injection_modesystem_message, # 注入方式system_message 或 prepend_user excluded_models[gpt-3.5*], # 排除被拦截的模型fnmatch 通配符 verboseTrue, # 开启详细日志与调试信息 )源码细节补充hindsight_api_url默认指向https://api.hindsight.vectorize.io云端默认地址见 config.pyapi_key不传时会自动读取HINDSIGHT_API_KEY环境变量HINDSIGHT_API_KEY_ENV额外支持mission与bank_name参数——传入时会立即调用 Hindsight 创建/更新 memory bank_create_or_update_bankconfigure()还接受全部逐调用默认值参数bank_id、budget、session_id等一套调用即可完成全部初始化。2.set_defaults()——逐调用默认值hindsight_litellm.set_defaults( # 必填 bank_idmy-agent, # 记忆银行 ID # 可选 - 记忆检索 budgetmid, # 预算级别low、mid、high fact_types[world, observation], # 过滤要检索的事实类型 max_memories10, # 最多注入的记忆条数None 不限制 max_memory_tokens4096, # 记忆上下文的最大 token 数 include_entitiesTrue, # 检索时是否包含实体观察 # 可选 - Reflect 模式 use_reflectTrue, # 用 reflect API综合还是 recall原始记忆 reflect_include_factsFalse, # 是否在调试信息中包含源事实 reflect_contextI am a delivery agent finding recipients., # reflect 推理上下文 reflect_response_schema{...}, # reflect 结构化输出的 JSON Schema # 可选 - 调试 traceFalse, # 开启 trace 信息 document_idconversation-1, # 用于对话分组的文档 ID )源码细节补充budget的合法值由VALID_BUDGETS {low, mid, high}校验传入其他值会直接抛ValueErrorfact_types可取值world、experience、observation关于document_id新版推荐改用session_id两者都设置时session_id优先见effective_document_id属性设置后 Hindsight 走 UPSERT 语义实现会话分组set_defaults()仅更新传入字段、保留其余默认值未配置时还会自动触发一次默认configure()。3. 逐调用覆盖hindsight_*kwargs任意默认值都能在单次调用中用hindsight_前缀参数覆盖response hindsight_litellm.completion( modelgpt-4o-mini, messages[...], hindsight_queryWhere is Alice located?, # 自定义记忆检索查询 hindsight_reflect_contextCurrently on floor 3, # 本次调用的 reflect 上下文 # hindsight_bank_idother-bank, # 覆盖本次调用的 bank_id )该机制的通用性来自_merge_call_settingsconfig.py它读取HindsightCallSettingsdataclass 的全部字段自动把hindsight_*kwargs 合并进默认设置——新增字段无需改动合并逻辑。Bank 任务配置set_bank_mission用set_bank_mission()告诉记忆银行该学习和记住什么用于心理模型 mental model 的生成hindsight_litellm.set_bank_mission( missionThis agent routes customer support requests to the appropriate team. Remember which types of issues should go to which teams (billing, technical, sales). Track customer preferences for communication channels and past issue resolutions., nameCustomer Support Router, # 可选显示名 )源码中该方法config.py会先解析bank_id参数 → 当前默认值 → 报错然后调用hindsight_client的create_bank创建或原地更新银行。多 Provider 支持一套记忆百种模型由于注入与存储发生在 LiteLLM 层任何 LiteLLM 支持的提供方都直接可用无需额外适配import hindsight_litellm hindsight_litellm.configure(hindsight_api_urlhttp://localhost:8888) hindsight_litellm.set_defaults(bank_idmy-agent) hindsight_litellm.enable() messages [{role: user, content: Hello!}] # OpenAI hindsight_litellm.completion(modelgpt-4o, messagesmessages, hindsight_querygreeting) # Anthropic hindsight_litellm.completion(modelclaude-sonnet-4-20250514, messagesmessages, hindsight_querygreeting) # Groq hindsight_litellm.completion(modelgroq/llama-3.1-70b-versatile, messagesmessages, hindsight_querygreeting) # Azure OpenAI hindsight_litellm.completion(modelazure/gpt-4, messagesmessages, hindsight_querygreeting) # AWS Bedrock hindsight_litellm.completion(modelbedrock/anthropic.claude-3, messagesmessages, hindsight_querygreeting) # Google Vertex AI hindsight_litellm.completion(modelvertex_ai/gemini-pro, messagesmessages, hindsight_querygreeting)如果某些模型不想被记忆逻辑拦截可用configure(excluded_models[gpt-3.5*])排除——_is_model_excludedinit.py用fnmatch通配符匹配模型名命中则直接透传原始 LiteLLM 调用。直接记忆 API不调 LLM 也能读写记忆集成提供与注入链路同源的底层 API可手动查询、综合、存储记忆Recall——查询原始记忆from hindsight_litellm import configure, set_defaults, recall configure(hindsight_api_urlhttp://localhost:8888) set_defaults(bank_idmy-agent) memories recall(what projects am I working on?, budgetmid) for m in memories: print(f- [{m.fact_type}] {m.text})Reflect——获取综合上下文from hindsight_litellm import configure, set_defaults, reflect configure(hindsight_api_urlhttp://localhost:8888) set_defaults(bank_idmy-agent) result reflect(what do you know about the users preferences?) print(result.text) # 用 context 塑造回答不影响检索 result reflect( querywhat do I know about Alice?, contextI am a delivery agent looking for package recipients., )Retain——存储记忆from hindsight_litellm import configure, set_defaults, retain, get_pending_retain_errors configure(hindsight_api_urlhttp://localhost:8888) set_defaults(bank_idmy-agent) # 异步 retain默认- 快速、不阻塞实际存储发生在后台 result retain( contentUser mentioned theyre working on a machine learning project, contextDiscussion about current projects, ) # 同步 retain - 阻塞直到完成出错立即抛出 result retain( contentCritical information that must be stored, contextImportant data, syncTrue, ) # 定期检查异步 retain 的错误 errors get_pending_retain_errors() if errors: for e in errors: print(fBackground retain failed: {e})异步 APIfrom hindsight_litellm import arecall, areflect, aretain memories await arecall(what do you know about me?) context await areflect(summarize user preferences) result await aretain(contentNew information to remember)异步能力0.5.0 加入背后是 wrappers.py 的实现recall/reflect/retain等同步 API 通过_async.py中的ensure_loop/run_sync桥接到hindsight-client的异步接口。_async.py采用每线程一个自有事件循环的设计显式new_event_loopset_event_loop既规避了 Python 3.12 对get_event_loop()的 DeprecationWarning3.14 起直接移除又保证 client 缓存的 aiohttp 会话始终绑定在存活的事件循环上跨多次同步调用可复用详见 _async.py。原生客户端包装器wrap_openai 与 wrap_anthropic不想经过 LiteLLM 时可以直接包装 OpenAI / Anthropic 原生 SDKfrom openai import OpenAI from hindsight_litellm import wrap_openai client OpenAI() wrapped wrap_openai( client, bank_idmy-agent, hindsight_api_urlhttp://localhost:8888, ) response wrapped.chat.completions.create( modelgpt-4, messages[{role: user, content: What do you know about me?}] )from anthropic import Anthropic from hindsight_litellm import wrap_anthropic client Anthropic() wrapped wrap_anthropic( client, bank_idmy-agent, hindsight_api_urlhttp://localhost:8888, ) response wrapped.messages.create( modelclaude-sonnet-4-20250514, max_tokens1024, messages[{role: user, content: Hello!}] )流式响应支持streamTrue完全受支持。检测到流式响应时集成会把响应自动包装起来边消费边收集 chunk当流被完整消费或上下文管理器退出后整段对话才写入 Hindsight。三种模式下的行为差异对应 0.5.2 修复的流式存储问题Monkeypatch 包装enable()/completion()/acompletion()流式响应被透明包装。同步侧由_LiteLLMStreamWrapper、异步侧由_LiteLLMAsyncStreamWrapper均在init.py负责收集 chunk在StopIteration/StopAsyncIteration或__exit__/close时把累积的助手输出与消息历史拼接后存储原生客户端包装器wrap_openai()、wrap_anthropic()同样的 chunk 收集行为回调处理器流式响应会被跳过回调无法控制返回值拿不到完整流因此需要流式 存储时请使用 monkeypatch 或原生包装器模式。调试模式与错误追踪查看注入了什么记忆开启verboseTrue后可用get_last_injection_debug()检查最近一次注入的细节from hindsight_litellm import configure, set_defaults, enable, completion, get_last_injection_debug configure(hindsight_api_urlhttp://localhost:8888, verboseTrue) set_defaults(bank_idmy-agent, use_reflectTrue) enable() response completion( modelgpt-4o-mini, messages[{role: user, content: Whats my favorite color?}], hindsight_queryWhat is the users favorite color?, ) debug get_last_injection_debug() if debug: print(fMode: {debug.mode}) # reflect 或 recall print(fInjected: {debug.injected}) # True/False print(fResults: {debug.results_count}) print(fMemory context:\n{debug.memory_context}) if debug.error: print(fError: {debug.error})对应的InjectionDebugInfodataclass 定义在init.py除上述字段外还包含query、bank_id、reflect_text、reflect_facts当reflect_include_factsTrue时从 reflect 响应的based_on中抽取、recall_results等。可用clear_injection_debug()清空。严格错误处理与 LiteLLM 原生回调静默吞异常不同本集成采用严格错误处理模块 docstring 明确说明当inject_memoriesTrue且 recall/reflect 失败或store_conversationsTrue且存储失败时会抛出HindsightError并传播到你的代码。同时提供get_pending_retain_errors()与get_pending_storage_errors()两个函数分别收集后台 retain 与后台对话存储的异步错误。上下文管理器与清理hindsight_memory 上下文管理器from hindsight_litellm import hindsight_memory import litellm with hindsight_memory(bank_iduser-123): response litellm.completion( modelgpt-4, messages[{role: user, content: Hello!}], hindsight_querygreeting context, ) # 上下文退出后记忆集成自动关闭这里正是 0.5.4 修复的重点上下文管理器退出时必须原子地恢复全局配置快照。源码中_restore_configconfig.py专门用于此场景——直接还原保存的配置对象绕过configure()的副作用告警、bank 创建等确保with块内设置的bank_id等配置不会泄漏到块外。禁用与清理from hindsight_litellm import disable, cleanup # 临时禁用记忆集成恢复原始 litellm.completion / acompletion disable() # 关闭时清理所有资源 cleanup()enable()在实现上会猴子补丁litellm.completion与litellm.acompletion保存原函数引用后替换为_wrapped_completion/_wrapped_acompletiondisable()则恢复原函数并关闭缓存的 HTTP 客户端。cleanup()依次执行disable()、清理回调、重置配置。需要特别注意的是enable()与HindsightCallback是互斥的注入路径——enable()检测到litellm.callbacks中已有HindsightCallback时会发出RuntimeWarning因为两者并存会导致记忆被重复注入两次。API 速查表主函数函数说明configure(...)配置静态 Hindsight 设置API URL、认证、存储选项set_defaults(...)设置逐调用默认值bank_id、budget、reflect 选项enable()启用 LiteLLM 记忆集成disable()禁用记忆集成is_enabled()检查记忆集成是否启用cleanup()清理所有资源配置函数函数说明get_config()获取当前静态配置get_defaults()获取当前逐调用默认值is_configured()检查是否已配置 bank_idreset_config()将所有配置重置为默认set_document_id(id)便捷更新 document_idset_bank_mission(...)设置记忆银行的任务用于心理模型记忆函数函数说明recall(query, ...)查询原始记忆同步arecall(query, ...)查询原始记忆异步reflect(query, ...)获取综合记忆上下文同步areflect(query, ...)获取综合记忆上下文异步retain(content, syncFalse, ...)存储记忆默认异步syncTrue阻塞aretain(content, ...)存储记忆异步错误追踪与调试函数说明get_pending_retain_errors()获取并清除后台 retain 的错误get_pending_storage_errors()获取并清除后台对话存储的错误get_last_injection_debug()获取最近一次记忆注入的调试信息clear_injection_debug()清空已存调试信息客户端包装器函数说明wrap_openai(client, ...)为 OpenAI 客户端包装记忆能力wrap_anthropic(client, ...)为 Anthropic 客户端包装记忆能力版本演进时间线0.5.0 → 0.5.4以下内容完整继承自 集成变更日志并结合当前仓库源码逐条展开说明。v0.5.4 —— 注入行为与状态恢复的可靠性修复Bug Fixes修正注入模式injection mode行为确保上下文管理器状态能被正确恢复并使校验/错误处理保持一致。对应代码层面即MemoryInjectionModesystem_message/prepend_user两种路径的注入实现与_restore_config原子恢复逻辑的校正该版本同时体现了校验与错误一致的工程原则budget与recall_tags_match在configure()/set_defaults()双入口都做VALID_BUDGETS/VALID_TAGS_MATCH校验保证错误在任何配置路径下行为一致。v0.5.3 —— 内部维护该版本仅包含内部维护与基础设施变更无面向用户的 API 或行为改动。v0.5.2 —— 流式对话存储修复Bug Fixes修复使用 LiteLLM 流式响应时对话存储失效的问题。这正是前文流式响应支持一节描述的_LiteLLMStreamWrapper/_LiteLLMAsyncStreamWrapper引入的背景——流式响应没有.choices属性早期实现包括回调路径的_plan_store无法从中提取助手输出0.5.2 通过包装流、边消费边收集 chunk 的方式在流完全消费后再把完整对话写入 Hindsight。v0.5.1 —— 类型信息、依赖安全与请求标识Improvements打包内置类型信息py.typed文件在类型化 Python 工程中使用集成时获得更好的类型检查支持更新并约束 LiteLLM 依赖包括排除一个被攻陷的版本——对应 pyproject.toml 中把litellm下限提到 1.93.0非 macOS并注释了 GHSA-* 系列供应链安全公告的处理。Bug Fixes在所有 HTTP 请求上设置可识别的 User-Agent 头提升与各 Provider 和代理的兼容性。对应 config.py 中的USER_AGENT fhindsight-litellm/{_VERSION}该值通过Hindsight(base_url..., user_agentUSER_AGENT)传入客户端。v0.5.0 —— 集成首版流式、异步与 API 清理Features新增 LiteLLM 包装集成下的流式支持见上文流式一节新增异步 retain 与 reflect 支持并清理 LiteLLM 集成 API——即aretain/areflect以及arecall与_async.py的同步→异步桥接层Hindsight LiteLLM 集成实现的首个发布版本。Improvements支持通过 LiteLLM 集成发送 tags 与 mission 元数据改善记忆的组织与检索——对应HindsightCallSettings.tags存储时附加标签与recall_tags/recall_tags_match检索时按标签过滤支持any/all/any_strict/all_strict四种匹配模式以及set_bank_mission()的记忆银行任务配置。Bug Fixes未提供显式 Hindsight 查询时改用最近一条用户消息作为查询避免记忆检索为空——即前文所述查询解析回退链hindsight_query→defaults.query→ 最后一条 user 消息修复 API key 处理把配置的api_key正确传递给 Hindsight 客户端——对应init.py 中创建客户端时显式传递config.api_key的注释说明托管后端对无 key 的 recall/reflect 会以 401 拒绝。运行前提Python 3.10litellm 1.83.0当前仓库实际要求非 macOS 平台1.93.0macOS 为1.91.3,1.92详见 pyproject.toml一个运行中的 Hindsight API 服务本地http://localhost:8888或云端默认地址。测试与验证仓库在 hindsight-integrations/litellm/tests 下提供了覆盖完整的测试套件包括test_integration.py配置管理、enable/disable 生命周期、注入行为等、test_config.py、test_async.py、test_callback_async_http.py与test_e2e.py。其中端到端测试通过 pytest markerrequires_real_llm标记需要真实 Hindsight 服务与真实 LLM Provider 密钥可用-m not requires_real_llm在确定性 CI 中排除、用-m requires_real_llm单独运行见 pyproject.toml 的 marker 定义。测试覆盖了configure全参数、is_configured的三种判定路径、reset_config等关键行为可作为集成接入时的回归验证参考。【免费下载链接】hindsightHindsight: Agent Memory That Learns项目地址: https://gitcode.com/GitHub_Trending/hindsight2/hindsight创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考