Hindsight Python Client 完全指南用 Retain / Recall / Reflect 驾驭 Agent 记忆【免费下载链接】hindsightHindsight: Agent Memory That Learns项目地址: https://gitcode.com/GitHub_Trending/hindsight2/hindsight本指南以 Hindsight 官方 Python 客户端hindsight-client为核心讲解如何在一个已运行的 Hindsight 服务本地、Docker 或托管实例之上用类型化的 Python 接口完成记忆的存储Retain、检索Recall与上下文应答Reflect。读完本文你将掌握客户端的安装方式、核心 API 的完整参数含义、异步编程模型、Bank 管理以及底层扩展接口并能直接照抄示例投入自己的 Agent 应用中。适用场景与安装hindsight-client是 Hindsight 的官方 HTTP 客户端面向「服务端已在运行」的场景——无论是本地进程、Docker 容器还是托管服务只要拿到一个 API 地址就能用这套类型化的 Python 接口与之对话。如果你希望在 Python 进程内直接内嵌并运行一个 Hindsight 服务无需任何外部服务器应改用嵌入式方案参见 嵌入式 Pythonhindsight-all。安装只需要一条命令pip install hindsight-client从 pyproject.toml 可以看到该包要求requires-python 3.10其依赖包括urllib3、python-dateutil、aiohttp、aiohttp-retry与pydantic2——pydantic用于承载所有请求/响应模型aiohttp支撑异步 HTTP 调用。快速开始连接默认运行在localhost:8888的 Hindsight 服务后三个核心操作各一行代码即可完成from hindsight_client import Hindsight client Hindsight(base_urlhttp://localhost:8888) # 1. Retain —— 存储一条记忆 client.retain(bank_idmy-bank, contentAlice works at Google) # 2. Recall —— 按语义检索记忆 results client.recall(bank_idmy-bank, queryWhat does Alice do?) for r in results.results: print(r.text) # 3. Reflect —— 基于记忆生成上下文应答 answer client.reflect(bank_idmy-bank, queryTell me about Alice) print(answer.text)这里出现了一个核心概念Bank记忆库。Hindsight 的所有记忆都以bank_id为命名空间隔离存储retain / recall / reflect 三个操作都必须指定它。客户端初始化Hindsight类的构造函数定义在 hindsight_client.py签名如下from hindsight_client import Hindsight client Hindsight( base_urlhttp://localhost:8888, # Hindsight API URL timeout30.0, # 请求超时秒默认 300.0 # api_keyyour-api-key, # 可选Bearer Token 认证 # user_agentmy-app/1.0, # 可选覆盖默认 User-Agent )四个初始化参数的作用参数默认值说明base_url必填Hindsight API 地址内部会去掉末尾斜杠所有请求都拼接到该地址上api_keyNone可选。传入后自动设置Authorization: Bearer api_key请求头timeout300.0请求超时秒数所有底层 HTTP 调用都会带上_request_timeoutself._timeoutuser_agenthindsight-client-python/version覆盖默认 UA第三方集成如hindsight-crewai/1.2.0应设置它以便服务端识别来源从源码实现看初始化时Hindsight会基于base_url与api_key构造 OpenAPI 自动生成的Configuration与ApiClient并一次性实例化全部低层 API 客户端MemoryApi、BanksApi、MentalModelsApi、DirectivesApi、OperationsApi、WebhooksApi 等挂到实例属性上因此一个Hindsight对象就是通往整个 API 表面的入口。除了核心的 retain / recall / reflect客户端还以「组织化的 API 命名空间」形式暴露低层接口例如client.banks.create(bank_idtest, nameTest Bank) # Bank 管理 models client.mental_models.list(bank_idtest) # 心智模型列表 directives client.directives.list(bank_idtest) # 指令列表 memories client.memory.list_memories(bank_idtest) # 记忆列表注意源码中记忆相关的低层属性名为client.memoryMemoryApi文档示例中的client.memories.list是文档早期命名实际可用属性以源码为准详见下文「低层 API 与扩展能力」一节。核心操作一Retain存储记忆Retain 负责把一段内容「存入」记忆库。服务端会对其进行事实抽取、实体解析与分块最终以结构化记忆memory unit的形式落库。基础用法# 最简形式 client.retain( bank_idmy-bank, contentAlice works at Google as a software engineer, )带选项的用法from datetime import datetime client.retain( bank_idmy-bank, contentAlice got promoted, contextcareer update, # 上下文描述辅助事实抽取 timestampdatetime(2024, 1, 15), # 事件发生时间 document_idconversation_001, # 文档分组 ID同批记忆可归属同一文档 metadata{source: slack}, # 用户自定义元数据 retain_asyncFalse, # True 则后台异步处理 )对照 源码中retain的完整签名除上述参数外还支持entities预置实体列表形如[{text: Alice, type: person}]用于显式指定本条记忆涉及的实体resolve_entities是否将传入实体与 Bank 内已有实体做解析合并默认TrueFalse则原样存储tags标签列表recall / reflect 时可按标签过滤update_modereplace或append决定对已有文档的写入方式operation_id调用方提供的 UUID用于异步 retain 的幂等重试。注意源码中有明确警告逻辑operation_id在同步 retain 下会被静默忽略只有retain_asyncTrue时才会生效误用时客户端会发出UserWarning提示见 _warn_if_operation_id_dropped。多模态内容ContentBlockcontent参数既可以是纯字符串也可以是有序的内容块列表让图片/文件内联出现在它实际对应的位置抽取器会结合上下文一起理解client.retain( bank_idmy-bank, content[ {type: text, text: click the button shown:}, {type: image, source: {type: base64, media_type: image/png, data: ...}}, {type: file, source: {type: base64, media_type: application/pdf, data: ...}, filename: policy.pdf}, ], )源码注释hindsight_client.py明确提醒块形式需要服务端具备视觉能力的 retain LLM否则 retain 会以 422 拒绝而不会静默丢弃附件。批量存储 retain_batch一次写入多条记忆服务端可共享同一document_id归属client.retain_batch( bank_idmy-bank, items[ {content: Alice works at Google, context: career}, {content: Bob is a data scientist, context: career}, ], document_idconversation_001, retain_asyncFalse, # True 则后台处理 )items中每个元素是字典支持的键包括content必填、timestamp、context、metadata、document_id、entities、resolve_entities、tags、observation_scopes字符串或list[list[str]]、strategy、update_mode。此外retain_batch还支持document_tags——批量级标签会与每条 item 自己的标签合并。源码中retain本身也是包装为单元素列表后调用retain_batch实现的aretain同理。实现细节底层会把每个 item 构造为MemoryItem其中content由于同时接受字符串与内容块列表会被包装进Content联合模型aretain_batch 实现最终调用MemoryApi.retain_memories发送到/v1/default/banks/{bank_id}/memories。核心操作二Recall检索记忆Recall 基于语义相似度从记忆库中检索与查询最相关的事实。基础用法# 返回 RecallResponse其 .results 是 RecallResult 列表 results client.recall( bank_idmy-bank, queryWhat does Alice do?, ) for r in results.results: print(f{r.text} (type: {r.type}))带选项的用法results client.recall( bank_idmy-bank, queryWhat does Alice do?, types[world, observation], # 按事实类型过滤world / experience / observation max_tokens4096, # 结果最大 token 预算 budgethigh, # low / mid / high )对照recall的完整签名其余常用参数trace开启检索链路追踪输出默认Falsequery_timestampISO 格式日期字符串作为相对时间表达式的「查询时刻」锚点并参与近期性评分例如2023-05-30T23:40:00include_entities/max_entity_tokens是否在结果中附带实体观察默认False/500include_chunks/max_chunk_tokens是否附带原始文本块便于回溯来源默认False/8192include_source_facts/max_source_facts_tokens对 observation 类型结果附带其来源事实默认False/4096tags/tags_match按标签过滤。tags_match取值anyOR含未打标签、allAND含未打标签、any_strictOR排除未打标签、all_strictAND排除未打标签、exact集合相等排除未打标签默认anytag_groups高级布尔标签匹配元素为标签组节点叶节点 / AND / OR / NOT例如[{tags: [customer], match: all}, {not: {tags: [internal]}}]prefer_observations当同时检索原始事实world/experience与observation时丢弃那些已被返回的 observation 合并吸收的原始事实避免重复内容min_scores各阶段分数下限如{semantic: 0.2, final: 0.5}。semantic/keyword是检索级截断reranker/final作用于重排后的结果未指定的阶段不设下限。未知键会直接抛出ValueError源码校验逻辑而不是静默忽略避免调用方误以为过滤生效temporal_window时间检索臂的窗口{start: ..., end: ...}ISO 字符串或 datetime用于替代从查询中抽取日期。注意它只提高窗口内记忆的排名不会剔除窗口外记忆因此不能当作时间范围硬过滤Bank 未启用时间检索时该参数被忽略。Recall 响应与来源追溯recall返回RecallResponse。从其模型定义recall_response.py可知结构为字段类型说明resultslist[RecallResult]命中的记忆entitiesdict[str, EntityStateResponse]实体观察开启 include_entities 时chunksdict[str, ChunkData]按 chunk_id 索引的原始文本块source_factsdict[str, RecallResult]observation 的来源事实tracedict检索追踪信息source_facts_truncatedbool来源事实是否被截断单个RecallResultrecall_result.py除id、text、type外还包含entities、context、occurred_start/occurred_end/mentioned_at时间字段、document_id、metadata、chunk_id、tags、source_fact_ids、scores、attachments——这意味着你不仅能拿到命中文本还能追溯到其原始文档、分块与评分。携带来源分块的检索response client.recall( bank_idmy-bank, queryWhat does Alice do?, types[world, experience], budgetmid, max_tokens4096, include_chunksTrue, max_chunk_tokens500, ) print(fFound {len(response.results)} memories) for r in response.results: print(f - {r.text}) if r.chunks: print(f Source: {r.chunks[0].text[:100]}...)面向 LLM 的便捷方法hindsight_client/__init__.py对RecallResponse做了一系列 REPL 友好的增强见源码len(response)/response[i]/for r in response直接按结果列表操作response.to_prompt_string()把结果序列化为适合拼进 LLM prompt 的文本——每条事实以 JSON 呈现含text、context与时间字段若有对应 chunk 则附带source_chunk实体观察单独成节。该格式与 Hindsight reflect 内部使用的格式一致非常适合做 Agent 的上下文组装。核心操作三Reflect生成应答Reflect 不满足于「检索出记忆」而是基于 Bank 的身份设定与检索到的记忆生成一段有上下文感的应答。answer client.reflect( bank_idmy-bank, queryWhat should I know about Alice?, budgetlow, # low / mid / high contextpreparing for a meeting, # 附加上下文 ) print(answer.text) # 生成的应答文本reflect的完整签名 还提供以下高级能力max_tokens应答 token 上限服务端默认 4096response_schemaJSON Schema 结构化输出。传入后响应会带structured_output字段由 LLM 按该 Schema 输出并被解析。官方测试test_main_operations.py展示了与 pydantic 配合的完整用法from pydantic import BaseModel class RecommendationResponse(BaseModel): recommendation: str reasons: list[str] confidence: str | None None response client.reflect( bank_idmy-bank, queryWhat programming language should I learn for data science?, response_schemaRecommendationResponse.model_json_schema(), max_tokens10000, ) result RecommendationResponse.model_validate(response.structured_output) print(result.recommendation)include_facts响应携带based_on字段列出构建答案所依据的记忆、心智模型与指令include_tool_calls/include_tool_call_output在trace字段中暴露反射过程中的工具调用与 LLM 调用链可用于调试与审计include_tool_call_outputFalse可减小载荷tags/tags_match/tag_groups与 recall 相同的标签过滤体系apply_all_directives默认指令按标签作用于记忆未打标签的指令始终生效设为True则无论标签如何所有激活指令都生效fact_types限定参与应答的事实类型world/experience/observationexclude_mental_models/exclude_mental_model_ids排除全部或指定 ID 的心智模型避免其影响应答。Bank 管理与记忆列表创建 Bankcreate_bank是一个「创建或更新」语义的接口。最常用来设置 Bank 的身份与性格client.create_bank( bank_idmy-bank, nameAssistant, missionYoure a helpful AI assistant - keep track of user preferences and conversation history., disposition{ skepticism: 3, # 1-5信任到怀疑 literalism: 3, # 1-5灵活到字面 empathy: 3, # 1-5疏离到共情 }, )对照 源码中的create_bank签名该接口远不止此还可配置reflect_missionReflect 的身份与推理框架mission已标记为 Deprecated推荐使用此项retain_mission/retain_extraction_mode/retain_custom_instructions控制 retain 抽取什么、抽取模式concise/verbose/custom/verbatim/chunks以及自定义抽取提示词retain_chunk_size/retain_structured_chunk_size/retain_max_attachments_per_chunk分块与附件预算控制enable_observations/observations_mission是否在 retain 后自动合并生成 observation以及其合成规则enable_text_search/enable_temporal_retrieval/enable_graph_retrieval/enable_reranking四个检索臂的开关BM25 关键词 / 时间 / 实体图 / 交叉编码器重排backgroundBank 的背景上下文。源码实现上create_bank走的是PUT /v1/default/banks/{bank_id}见 _acreate_bank且三个 disposition 维度支持单独的disposition_skepticism/disposition_literalism/disposition_empathy参数优先级高于disposition字典。列出记忆client.list_memories( bank_idmy-bank, typeworld, # 可选按事实类型过滤 search_queryAlice, # 可选文本搜索 limit100, # 分页大小 offset0, # 分页偏移 )底层对应MemoryApi.list_memories额外支持entity_id参数——只返回与该实体 ID 存在存储级链接而非文本/语义匹配的记忆单元见 alist_memories。异步支持全部方法均有 a 前缀版本所有便捷方法都有对应的异步版本前缀为aaretain、arecall、areflect、aretain_batch、acreate_bank、alist_memories等。客户端源码明确指出类文档在异步上下文async def、事件循环、FastAPI/LangGraph/CrewAI 等框架中应优先使用a*方法同步版本内部通过loop.run_until_complete包装协程实现适合脚本与 REPL若事件循环已在运行会直接报错。import asyncio from hindsight_client import Hindsight async def main(): client Hindsight(base_urlhttp://localhost:8888) # 异步 retain await client.aretain(bank_idmy-bank, contentHello world) # 异步 recall results await client.arecall(bank_idmy-bank, queryHello) for r in results: print(r.text) # 异步 reflect answer await client.areflect(bank_idmy-bank, queryWhat did I say?) print(answer.text) await client.aclose() # 异步关闭 asyncio.run(main())注意示例中await client.arecall(...)后直接for r in results是合法的——RecallResponse被增强了__iter__可直接迭代结果。异步测试用例TestAsyncRecall验证了arecall返回的是RecallResponse而非列表且include_chunks、include_entities、trace等参数在异步路径下行为与同步一致。上下文管理器与资源释放Hindsight实现了上下文管理器协议源码退出时自动关闭底层 HTTP 连接from hindsight_client import Hindsight with Hindsight(base_urlhttp://localhost:8888) as client: client.retain(bank_idmy-bank, contentHello) results client.recall(bank_idmy-bank, queryHello) # 客户端自动关闭在异步代码中请使用await client.aclose()同步close()会智能判断若事件循环正在运行则调度后台关闭任务否则同步执行关闭。低层 API 与扩展能力Hindsight类在便捷方法之外以属性形式暴露了完整的 OpenAPI 自动生成接口全部为 async 方法覆盖便捷方法未触及的能力属性对应 API典型能力client.memoryMemoryApiretain/recall/reflect、记忆列表、标签、图client.banksBanksApiBank 增删改、统计、合并consolidation、配置client.documentsDocumentsApi文档 CRUD 与分块列表client.entitiesEntitiesApi实体浏览与观察再生client.mental_modelsMentalModelsApi心智模型创建/列表/刷新/历史client.knowledge_baseKnowledgeBaseApi知识库文件夹/页面树、页面 CRUD、搜索、导出client.directivesDirectivesApi指令管理client.operationsOperationsApi异步操作状态/取消/重试client.webhooksWebhooksApiWebhook 与投递记录client.filesFilesApi文件上传与 retainclient.monitoringMonitoringApi健康检查、版本、指标client.document_transferDocumentTransferApi跨 Bank 文档导出/导入示例用法import asyncio # 列出 Bank 内文档 docs asyncio.run(client.documents.list_documents(alice)) # 查询异步操作状态 status asyncio.run(client.operations.get_operation_status(alice, op-456)) # 读取服务端版本与能力 ver client.get_version() # 或 await client.aget_version() print(ver.api_version, ver.features)对于整库迁移场景客户端还提供了export_documents阻塞式便捷方法——提交导出任务、轮询操作状态、下载 ZIP 归档并直接返回字节实现见 aexport_documents可通过client.document_transfer.import_documents在目标 Bank 导入。源码结构与测试佐证hindsight-client的代码组织体现了「手工维护 自动生成」的分层设计高层包装层hindsight_client/hindsight_client.py手工维护、非自动生成提供简洁易用的Hindsight类与全部便捷方法低层生成层hindsight_client_api/由 OpenAPI Generator 从服务端规范生成覆盖全部 API 端点与 pydantic 模型包入口hindsight_client/init.py导出Hindsight及RetainResponse、RecallResponse、RecallResult、ReflectResponse、ListMemoryUnitsResponse、BankProfileResponse、DispositionTraits、VersionResponse等响应类型并对响应对象做 REPL 增强。源码中多处体现工程细节例如_trigger_input帮助函数hindsight_client.py确保更新心智模型/知识页触发器时只携带调用方指定的字段避免生成模型把默认值一并序列化而意外覆盖服务端配置min_scores的未知键校验会「响亮失败」而非静默放行。测试方面tests/test_main_operations.py 提供了一整套基于真实服务默认http://localhost:8888可用环境变量HINDSIGHT_API_URL覆盖的集成测试覆盖 retain/recall/reflect 全流程、标签过滤五种匹配模式、结构化输出、异步方法参数对等性以及 Bank 生命周期。若要本地复现需先按仓库的 Docker 编排docker/docker-compose或 Helm 方案helm/hindsight拉起服务端再设置HINDSIGHT_API_URL运行测试。小结hindsight-client为 Python 开发者提供了一条从「存储记忆」到「检索记忆」再到「生成上下文应答」的完整通路retain负责写入与事实抽取recall提供多臂检索与可追溯的来源分块reflect输出带身份设定的应答并支持结构化输出而统一的a*异步前缀与上下文管理器让它在异步框架中同样顺手。配合低层 API 属性这个客户端可以覆盖 Hindsight 的绝大部分管理面Bank、心智模型、指令、文档、Webhook、监控是构建带持久记忆能力的 Agent 应用时的首选入口。【免费下载链接】hindsightHindsight: Agent Memory That Learns项目地址: https://gitcode.com/GitHub_Trending/hindsight2/hindsight创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考