Hindsight × Claude Agent SDK：用 MCP 工具与 Hooks 为 Claude 智能体接入持久化长期记忆

Hindsight × Claude Agent SDK用 MCP 工具与 Hooks 为 Claude 智能体接入持久化长期记忆【免费下载链接】hindsightHindsight: Agent Memory That Learns项目地址: https://gitcode.com/GitHub_Trending/hindsight2/hindsighthindsight-claude-agent-sdk是 HindsightAgent Memory That Learns官方提供的 Claude Agent SDK 集成包它以内置in-processMCP 服务器的形式暴露hindsight_retain/hindsight_recall/hindsight_reflect三个记忆工具让智能体自己决定何时记忆、何时回忆同时提供 Claude Hooks在每轮提示提交前自动召回相关记忆、在会话结束时自动沉淀结果。读完本文你可以从零完成安装掌握「显式工具」「自动钩子」「全局配置」三种接入方式的完整代码并理解参数解析优先级与底层调用链。一、集成定位两条互补的记忆路径该集成的包入口位于 hindsight-integrations/claude-agent-sdk/hindsight_claude_agent_sdk/init.py公开 API 共 9 个符号create_hindsight_server/create_hindsight_tools创建 MCP 记忆服务器/工具显式记忆create_memory_hooks/MemoryHookConfig创建自动记忆钩子隐式记忆configure/get_config/reset_config/HindsightClaudeAgentSDKConfig全局配置管理HindsightError统一异常类型见 errors.py。模块 docstring 中明确了两条路径的分工工具tools用于让 Agent 自行决定何时记忆/召回钩子hooks用于让记忆自动发生。二者可以叠加使用——官方 Quick Start 的 Hooks 示例就同时挂载了mcp_servers与hooks即「Agent 可以主动查记忆系统也在背后自动存取」。二、安装与前提条件安装命令pip install hindsight-claude-agent-sdk从 pyproject.toml 可以确认运行前提Python3.10classifiers 声明支持 3.10–3.13当前版本0.1.0依赖claude-agent-sdk0.1.50与hindsight-client0.4.0因此需要同时安装 Claude Agent SDK需要一个可达的 Hindsight API 服务端示例中的http://localhost:8888指向本地自托管实例也可以使用云 API默认 URL 与 API Key 机制见第五节。三、方式一显式记忆工具MCP Tools官方 Quick Start 的完整用法摘自 READMEfrom claude_agent_sdk import query, ClaudeAgentOptions from hindsight_claude_agent_sdk import create_hindsight_server server create_hindsight_server( bank_idmy-agent, hindsight_api_urlhttp://localhost:8888, ) async for msg in query( promptRemember that I prefer dark mode. Then check what you know about me., optionsClaudeAgentOptions( mcp_servers{hindsight: server}, allowed_tools[mcp__hindsight__*], ), ): print(msg)要点解析create_hindsight_server返回一个McpSdkServerConfig内部通过claude_agent_sdk的create_sdk_mcp_server(namehindsight, version__version__, tools...)包装见 tools.py 中create_hindsight_server。服务器名固定为hindsight所以工具全名是mcp__hindsight__retain等。allowed_tools[mcp__hindsight__*]用通配符授权整组记忆工具Claude 只被允许调用 Hindsight 工具——这是显式模式下「由模型决定何时用记忆」的开关。三个工具的实现细节create_hindsight_tools按include_retain/include_recall/include_reflect三个开关默认全开组装工具工具入参行为源码依据hindsight_retaincontent: str调用client.aretain(bank_id, content, tags?, metadata?, document_id?)成功返回Memory stored successfully.失败返回is_error: Truetools.py#L110-L138hindsight_recallquery: str调用client.arecall(...)把命中记忆渲染成编号列表返回无命中时返回No relevant memories found.tools.py#L142-L185hindsight_reflectquery: str调用client.areflect(...)让 Hindsight 侧基于记忆做合成式回答适合「总结我知道什么」类问题tools.py#L189-L231工具还携带了 MCPToolAnnotations元数据hindsight_retain标记为readOnlyHintFalse写操作hindsight_recall标记为只读且幂等idempotentHintTruehindsight_reflect只读但非幂等。这类注解会被遵循 MCP 语义的客户端用于权限/审批决策。除必填的bank_id外create_hindsight_tools/create_hindsight_server支持的完整参数参数说明直接来自 tools.py 的 docstring参数说明client预配置的Hindsight客户端优先使用hindsight_api_url/api_key未提供client时用于构造客户端budget召回/反思的预算档位low/mid/highmax_tokens召回结果的最大 token 数tagsretain 存储时附带的标签recall_tags/recall_tags_match召回时的标签过滤及匹配模式any/all/any_strict/all_strictretain_metadata/retain_document_idretain 的默认 metadatadocument_id可把多次写入分组/upsert 到同一文档recall_types限定事实类型world、experience、observationrecall_include_entities召回结果中附带实体名渲染为[entities: ...]reflect_context/reflect_max_tokens/reflect_response_schema反思的附加上下文、最大 token默认回落到max_tokens、约束输出格式的 JSON Schemareflect_tags/reflect_tags_match反思的标签过滤默认继承recall_tags四、方式二自动记忆钩子Hooks官方 Quick Start 的完整用法摘自 READMEfrom claude_agent_sdk import query, ClaudeAgentOptions from hindsight_claude_agent_sdk import create_hindsight_server, create_memory_hooks server create_hindsight_server(bank_idmy-agent, hindsight_api_urlhttp://localhost:8888) hooks create_memory_hooks(bank_idmy-agent, hindsight_api_urlhttp://localhost:8888) async for msg in query( promptHelp me refactor the auth module., optionsClaudeAgentOptions( mcp_servers{hindsight: server}, allowed_tools[mcp__hindsight__*], hookshooks, ), ): print(msg)create_memory_hooks返回{事件名: [HookMatcher]}字典直接传给ClaudeAgentOptions(hooks...)。根据 hooks.py 的 docstring最多挂载三类钩子UserPromptSubmitauto_recallTrue时每轮用户提交前以 prompt 为查询词调arecall把命中记忆以systemMessage注入系统上下文无命中则静默返回。Stopauto_retainTrue时会话结束时从transcript_path解析 JSONL 转录提取type result的最终结果找不到则回退到最后一条 assistant 文本块见_extract_result_from_transcripthooks.py#L44-L79长度不足 20 字符的噪音结果直接丢弃超过 4000 字符则截断后调aretain写入。PostToolUse配置了retain_on_tools时对命中的工具如Bash把「工具名 入参摘要前 500 字符 结果摘要前 2000 字符」组织成一条记忆写入并自动附加tool:{tool_name}标签。多个工具名会拼接成正则Bash|Read单元断言见 tests/test_hooks.py 中matcher Bash|Read。所有钩子异常都被捕获并仅记 warning——钩子失败不影响主会话源码注释 non-fatal这是把记忆做「旁路」而非「关键路径」的设计取舍。MemoryHookConfig 全量参数README 展示了核心调优示例from hindsight_claude_agent_sdk import MemoryHookConfig, create_memory_hooks hooks create_memory_hooks( bank_idmy-agent, hook_configMemoryHookConfig( auto_recallTrue, # inject memories before each prompt auto_retainTrue, # save results after each session retain_on_tools[Bash], # also retain notable Bash outputs recall_max_results5, # max memories to inject retain_tags[source:my-app], ), )结合 hooks.py#L82-L108 的 dataclass 定义默认值如下README 未列出的recall_query、recall_prefix、retain_prefix一并补齐字段默认值说明auto_recallTrue每轮UserPromptSubmit前注入相关记忆auto_retainTrueStop事件时沉淀会话结果retain_on_tools[]需要自动记忆其输出的工具名列表如[Bash]空则不挂PostToolUserecall_query$prompt自动召回的查询词$prompt表示用用户实际 prompt写死字符串则用固定查询recall_max_results5注入的记忆条数上限recall_prefix\n\nRelevant memories from previous sessions:\n注入内容前的引导文本retain_tags[source:claude-agent-sdk]自动写入记忆的标签可用于与人工记忆区分来源retain_prefixAgent session result: 自动写入内容的前缀单元测试对「开关 → 事件挂载」的对应关系做了直接验证auto_recallFalse时字典中不再含UserPromptSubmitauto_retainFalse时不再含Stop两者都关则返回空字典tests/test_hooks.py#L51-L84。五、全局配置configure() 与连接解析优先级README 给出的全局配置示例from hindsight_claude_agent_sdk import configure configure( hindsight_api_urlhttp://localhost:8888, api_keyyour-api-key, budgetmid, )configure的全部参数与默认值定义在 config.py参数默认值说明hindsight_api_urlhttps://api.hindsight.vectorize.io云 APIHindsight 服务端地址自托管改为http://localhost:8888api_keyNone回落读环境变量HINDSIGHT_API_KEY鉴权密钥budgetmid召回预算档位可选low/mid/highmax_tokens4096召回结果默认最大 token 数tagsNoneretain 操作默认标签recall_tagsNone召回默认标签过滤recall_tags_matchany标签匹配模式any/all/any_strict/all_strict配置存于模块级单例get_config()读取、reset_config()重置测试中广泛使用以避免串扰。客户端解析优先级连接到底连了哪里真正的连接逻辑在 ​_client.py 的resolve_client优先级从高到低显式传入的client参数Hindsight实例显式传入的hindsight_api_url/api_keyconfigure()写入的全局配置兜底默认云 URL 环境变量HINDSIGHT_API_KEY。两个值得注意的实现细节其一代码直接读取环境变量HINDSIGHT_API_KEY注释说明基础客户端自身不会回退该变量所以「什么都不配、只设环境变量」也能工作其二API Key 缺失时构造不报错只有在真正发起调用时才会失败构造参数为timeout30.0且带user_agenthindsight-claude-agent-sdk/{version}便于服务端识别来源。test_hooks.py中有两个用例分别验证了「无配置时默认连云 URL」与「无 configure 也能读到环境变量 Key」tests/test_hooks.py#L105-L120。六、行为边界与故障模式结合源码几个容易踩坑的行为边界retain 是异步落库的保留后记忆要经过 Hindsight 服务端的事实抽取与索引才能被召回。E2E 测试为此做了轮询等待最多 12 次、每次 1 秒并断言召回内容确实包含写入的事实如 PostgreSQL 16 / us-east-1见 tests/test_e2e.py。工具失败不抛异常三个 MCP 工具内部捕获异常并以is_error: True文本返回让模型自行感知「记忆操作失败」而非中断对话钩子失败则完全静默仅 warning 日志。空召回有固定文案hindsight_recall无命中、hindsight_reflect无可用记忆时均返回No relevant memories found.可据此在应用层做分支判断test_recall_empty_bank即断言此文案。自动写入的截断策略会话结果超过 4000 字符截断、短于 20 字符丢弃工具结果摘要限制在入参 500 输出 2000 字符内防止把冗长噪音灌进记忆库。E2E 测试门槛tests/test_e2e.py标记为requires_real_llm需要先有可达的 Hindsight 实例通过HINDSIGHT_API_URL指定默认http://localhost:8888会先探测/health不可达则整体 skipPR CI 中该组测试被排除、单独/夜间运行。七、选型建议Tools、Hooks 或两者兼用从源码结构看官方推荐的组合方式在 Quick Start 中已给出范式只要显式控制仅挂create_hindsight_server让 Agent 通过mcp__hindsight__*自主决定何时 retain/recall/reflect——适合需要审查记忆操作、或记忆敏感的场景只要自动沉淀仅挂create_memory_hooks无需allowed_tools记忆完全在系统侧发生——适合「会话间自动延续上下文」的多轮助手全量记忆体验README 默认姿势同时挂载 server 与 hooksAgent 可主动查询系统自动兜底存取。此时用retain_tags[source:my-app]区分来源、用recall_max_results控制注入量、用budget控制召回深度是主要调优旋钮。无论哪种方式bank_id是记忆的隔离边界不同 Agent/用户应使用不同 bank避免跨会话记忆串线。参考文件索引集成文档与安装说明hindsight-integrations/claude-agent-sdk/README.md包元数据与依赖声明hindsight-integrations/claude-agent-sdk/pyproject.toml全局配置config.pyMCP 工具工厂tools.py自动记忆钩子hooks.py客户端解析_client.py测试tests/test_hooks.py、tests/test_e2e.py【免费下载链接】hindsightHindsight: Agent Memory That Learns项目地址: https://gitcode.com/GitHub_Trending/hindsight2/hindsight创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考