Hindsight 集成 LiteLLM：为 100+ LLM 供应商接入持久化记忆的通用方案与版本演进解析

Hindsight 集成 LiteLLM为 100 LLM 供应商接入持久化记忆的通用方案与版本演进解析【免费下载链接】hindsightHindsight: Agent Memory That Learns项目地址: https://gitcode.com/GitHub_Trending/hindsight2/hindsight本文以 hindsight-docs/src/pages/changelog/integrations/litellm.md 的 LiteLLM 集成 Changelog 为时间轴骨架结合 hindsight-integrations/litellm 的完整源码与 README系统讲解hindsight-litellm的安装配置、记忆注入/存储机制、reflect 与 recall 双模式、原生客户端封装以及 0.5.x 各版本的修复与演进。读完本文你将能够在任意 LiteLLM 支持的 LLM 应用中接入 Hindsight 持久化记忆并理解其底层实现与调试手段。一、hindsight-litellm 是什么一条连接 LLM 与持久化记忆的通用通道Hindsight 是一个会学习的 Agent 记忆系统而hindsight-litellm是它面向 LiteLLM 生态的官方集成包。由于 LiteLLM 本身屏蔽了 100 供应商OpenAI、Anthropic、Groq、Azure、AWS Bedrock、Google Vertex AI 等的接口差异hindsight-litellm因此获得通用性——只需几行代码就能让任何基于 LiteLLM 的 LLM 应用拥有自动记忆注入与对话存储能力。在仓库中该集成位于 hindsight-integrations/litellm包结构如下hindsight_litellm/init.py对外主入口configure/set_defaults/enable/disable及completion/acompletion包装器hindsight_litellm/config.pyHindsightConfig与HindsightCallSettings两级配置模型hindsight_litellm/wrappers.pyrecall/reflect/retain直接记忆 API 与 OpenAI/Anthropic 原生客户端封装hindsight_litellm/callbacks.py基于 LiteLLMCustomLogger的回调实现与HindsightError异常hindsight_litellm/_async.py事件循环管理工具tests配置、注入、流式、异步与端到端测试从 pyproject.toml 看包当前版本为0.5.4要求 Python 3.10依赖hindsight-client0.4.0与litellm1.93.0macOS 上为litellm1.91.3,1.92并对aiohttp、filelock、urllib3、requests等传递依赖做了安全版本下限约束。二、版本演进时间线0.5.0 → 0.5.4 的完整 ChangelogChangelog 页面记录了该集成从首次发布到当前版本的演进是理解能力边界与坑位修复的最佳入口各版本内部修正详见 hindsight-docs/src/pages/changelog/integrations/litellm.md。0.5.0功能首发0.5.0 是hindsight-litellm的首个正式实现版本奠定了能力基调流式支持使用 LiteLLM 包装器集成时可处理流式响应异步 retain 与 reflect提供aretain、areflect等异步记忆 API同时清理了整体 API 形态标签与 mission 元数据支持将 tags 与 mission 元数据随调用下发改善记忆的组织与检索两个关键修复当未显式提供 Hindsight 查询时自动使用最近一条用户消息作为查询避免空查询导致记忆查不到对应源码init.py 中 custom_query defaults.query 最后一条 user 消息 的解析顺序将配置的api_key正确传递到 Hindsight 客户端修复鉴权缺失。0.5.1类型信息与依赖安全加固打包内置类型信息py.typed为类型化 Python 项目提供更好的 type-check 支持收紧 LiteLLM 依赖版本并排除一个已确认存在安全问题的版本对应 pyproject.toml 中针对多个 GHSA 漏洞的版本下限注释在所有 HTTP 请求上设置可识别的 User-Agent 头改善与供应商、代理的兼容性源码中由USER_AGENT fhindsight-litellm/{_VERSION}统一生成见 config.py。0.5.2流式对话存储修复修复使用 LiteLLM 流式响应时的对话存储问题——即流式场景下对话内容未被正确写入记忆库。在源码层面这一修复由_LiteLLMStreamWrapper/_LiteLLMAsyncStreamWrapper承担它们逐块收集choices[0].delta.content在流迭代结束StopIteration/StopAsyncIteration或上下文退出时统一落库见init.py。0.5.3内部维护该版本仅包含内部维护与基础设施变更不涉及面向用户的功能改动。0.5.4注入行为与状态恢复修复当前版本聚焦集成可靠性修正注入模式行为确保system_message与prepend_user两种注入模式行为正确上下文管理器状态恢复确保hindsight_memory()退出后全局状态被正确还原源码中由_restore_config原子性恢复快照实现见 config.py验证与错误处理一致性统一校验逻辑与异常抛出路径。三、四步接入Quick Start 与完整配置体系3.1 安装与最小可用示例pip install hindsight-litellm四个步骤即可启用记忆集成import 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: 调用时显式传入 hindsight_queryinject_memoriesTrue 时必填 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来指明要从记忆中检索什么。从源码看若不提供集成会自动退回使用最后一条用户消息作为查询init.py但显式查询能让记忆检索更有意图性。3.2 两级配置configure() 与 set_defaults()配置模型刻意拆成两个函数源码见 config.pyconfigure()—— 静态连接设置通常会话中不变hindsight_litellm.configure( # 必填 hindsight_api_urlhttp://localhost:8888, # Hindsight API 服务地址 # 可选 - 认证 api_keyyour-api-key, # 不传则读取 HINDSIGHT_API_KEY 环境变量 # 可选 - 记忆行为 store_conversationsTrue, # 调用后存储对话 inject_memoriesTrue, # 调用前注入相关记忆 sync_storageFalse, # False 异步存储默认性能更好 # True 同步存储阻塞立即抛错 # 可选 - 高级 injection_modesystem_message, # 注入方式system_message 或 prepend_user excluded_models[gpt-3.5*], # 按 glob 排除某些模型如 gpt-3.5* 前缀匹配 verboseTrue, # 开启详细日志与调试信息 )set_defaults()—— 每次调用的默认值可被单次调用的hindsight_*参数覆盖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, # recall 时包含实体观测 # 可选 - Reflect 模式 use_reflectTrue, # 用 reflect API综合而非 recall原始记忆 reflect_include_factsFalse, # 调试信息中是否包含来源事实 reflect_contextI am a delivery agent finding recipients., # 影响推理而非检索 reflect_response_schema{...}, # reflect 结构化输出的 JSON Schema # 可选 - 调试 traceFalse, # 开启 trace 信息 session_idconversation-1, # 会话 ID映射到 Hindsight 的 document_id )单次调用覆盖任何默认值都可通过hindsight_*前缀参数在单次调用中覆盖如hindsight_bank_idother-bank。源码中_merge_call_settings会自动把hindsight_开头的 kwargs 与默认值合并config.py新增字段会自动生效。3.3 用 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, # 可选显示名 )从源码看这会通过hindsight_client的create_bank创建或原地更新记忆库config.py若未指定bank_id则回退到当前默认库缺失时会抛出HindsightError。四、两种记忆模式Recall原始检索与 Reflect综合上下文use_reflect决定注入到 prompt 中的记忆形态模式行为适用场景Recalluse_reflectFalse默认检索原始记忆事实以编号列表注入如1. [WORLD] User prefers Python需要精确、独立的单条记忆Reflectuse_reflectTrue用 LLM 将记忆综合为连贯的上下文段落追求自然、对话式的记忆上下文# Recall 模式 - 原始记忆 hindsight_litellm.set_defaults(bank_idmy-agent, use_reflectFalse) # 注入内容1. [WORLD] User prefers Python\n2. [OPINION] 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 - 影响 LLM 推理不影响检索 hindsight_litellm.set_defaults( bank_idmy-agent, use_reflectTrue, reflect_contextI am a delivery agent looking for package recipients., )源码层面的实现差异非常清晰init.pyreflect 路径调用client.reflect(bank_id, query, budget)将单条综合文本包装为# Relevant Context from Memory\n{text}注入recall 路径调用client.recall(bank_id, query, budget, max_tokens, types)将每条结果格式化为N. [TYPE] text再包进# Relevant Memories头部若reflect_include_factsTrue则通过hindsight_client_api底层请求带上include.facts把based_on中的来源事实提取进调试信息。五、记忆注入的完整生命周期一次 completion 调用发生了什么集成的工作流可以用下面的链路概括记忆检索LLM 调用前以hindsight_query或最后一条用户消息为查询调用 recall/reflect 从记忆库取回相关内容Prompt 注入按injection_mode将记忆上下文写入 system message默认不存在则新建一条 system 消息或前置到最后一条 user 消息prepend_user实现见init.pyLLM 调用把增强后的消息列表交给litellm.completionLLM 因此能给出个性化回复对话存储LLM 调用后将用户消息与助手回复格式化为文本通过retain写入记忆库默认异步后台线程执行Hindsight 随后从中抽取事实响应返回调用方像使用普通completion一样拿到ModelResponse。enable()的实现方式是猴子补丁保存原始litellm.completion/litellm.acompletion替换为_wrapped_completion/_wrapped_acompletioninit.py。disable()则恢复原始函数并关闭缓存的 HTTP 连接。严格错误处理是本集成与 LiteLLM 原生回调的关键区别LiteLLM 的 callback 体系会静默吞掉异常而hindsight-litellm在inject_memoriesTrue或store_conversationsTrue时若操作失败会抛出HindsightError并传播到调用方代码。enable()还会检测litellm.callbacks中是否已注册HindsightCallback——两者是互斥的注入路径同时启用会导致记忆被注入两次。对话存储的细节值得一提同步 vs 异步sync_storageFalse默认时存储放入 daemon 后台线程用get_pending_storage_errors()定期检查失败True时同步执行并立即抛错init.py会话聚合设置session_id后存储前会先读取已有 document 内容再追加实现同一会话的连续对话聚合到同一文档init.py存储清洗格式化时会跳过 system 消息、跳过已注入的# Relevant Memories块并把 tool 调用规范化为ASSISTANT_TOOL_CALLS: func(args)与TOOL_RESULT: ...文本init.py。六、跨供应商接入一套代码通吃所有 LiteLLM 模型hindsight-litellm的通用性来自 LiteLLM 的模型前缀约定。只需更换model字符串即可切换供应商记忆逻辑完全不变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[...])中配置 glob 模式源码中_is_model_excluded用fnmatch做大小写不敏感匹配命中则直接透传原始调用init.py。七、直接记忆 APIrecall / reflect / retain 及其异步版本即使不做 LLM 调用也可以手动查询、综合与写入记忆——这对调试、构建自定义 UI 或预过滤记忆非常有用。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}) # 输出示例 # - [world] User is building a FastAPI project # - [observation] User prefers Python over JavaScriptrecall返回RecallResponse可像列表一样迭代开启verbose时附带.debug调试信息wrappers.py。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) # Based on our conversations, the user prefers Python for backend development... # 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, ) # result.success 立即为 True真实错误由 get_pending_retain_errors 收集 # 同步 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)八、原生客户端封装不经过 LiteLLM 也能接入记忆对于直接使用官方 SDK 的场景集成提供了 OpenAI 与 Anthropic 客户端封装作为 LiteLLM 回调的替代路径wrappers.pyfrom 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!}] )封装对象同样支持hindsight_*单次调用覆盖并实现流式收集OpenAI 的choices[0].delta.content与 Anthropic 的content_block_delta文本在流结束时统一落库还支持with wrap_openai(...) as client:上下文管理自动关闭连接。九、调试与生命周期管理调试模式看清到底注入了什么开启verboseTrue后可用get_last_injection_debug()检查最近一次注入的完整信息init.pyfrom 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})上下文管理器临时启用记忆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, ) # 退出上下文后记忆集成自动关闭且全局状态被原子还原关闭与清理from hindsight_litellm import disable, cleanup disable() # 临时禁用记忆集成恢复原始 litellm.completion cleanup() # 应用退出时调用禁用 关闭连接 重置配置函数速查表分类函数说明主流程configure/set_defaults/enable/disable/is_enabled/cleanup配置与启停配置查询get_config/get_defaults/is_configured/reset_config/set_document_id/set_bank_mission配置读写记忆操作recall/arecall/reflect/areflect/retain/aretain查询、综合、存储含异步错误追踪get_pending_retain_errors/get_pending_storage_errors获取并清除后台操作错误调试get_last_injection_debug/clear_injection_debug注入信息检查客户端封装wrap_openai/wrap_anthropic原生 SDK 记忆化十、运行前提与源码验证Python 3.10litellm1.93.0macOS 平台为1.91.3,1.92因 LiteLLM 未发布 macOS wheel以及一个运行中的 Hindsight API 服务器hindsight-litellm自身不内嵌 Hindsight 服务端。本地部署可参考 docker/docker-compose 下的编排文件如local-llm、external-pg等搭建 API 服务集成行为的正确性有测试覆盖配置合并、enable/disable 状态机、记忆注入、流式存储与异步错误收集见 tests/test_integration.py 与 tests/test_async.py需要真实外部服务的端到端用例标记为requires_real_llm可从确定性 CI 桶中隔离运行见 pyproject.toml。结语从 0.5.0 的功能首发到 0.5.4 的可靠性修复hindsight-litellm在短短四个版本内补齐了流式支持、异步 API、类型标注、依赖安全与严格错误处理。它的价值在于用configure → set_defaults → enable → completion四步将自动记忆注入 对话自动存储这一横切能力无侵入地注入到任何 LiteLLM 应用同时通过hindsight_query、session_id、tags 与set_bank_mission提供了从查询意图到多租户隔离、从会话聚合到心智模型塑造的精细化控制。无论你的应用跑在 OpenAI、Anthropic 还是 Bedrock 上记忆层都可以完全复用——这正是通用 LLM 记忆集成的题中之义。【免费下载链接】hindsightHindsight: Agent Memory That Learns项目地址: https://gitcode.com/GitHub_Trending/hindsight2/hindsight创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考