Hindsight 记忆接入选型指南MCP 与 SDK 两种集成路径的源码级对比【免费下载链接】hindsightHindsight: Agent Memory That Learns项目地址: https://gitcode.com/GitHub_Trending/hindsight2/hindsight当你为 AI 应用选择记忆接入方式时真正的分界线在于集成边界放在哪里MCP 适合让现成的客户端或 Agent 以工具服务器的方式连接 HindsightSDK 集成则适合你自己掌握应用逻辑、把记忆直接嵌入代码的场景。本文基于 Hindsight 仓库中的 MCP 工具注册模块、MCP 服务挂载代码与 Python 客户端源码对比这两条路径的适用场景、控制粒度与迁移路径读完你可以直接判断自己的项目该选哪条路、如何起步、以及后续如何演进。结论先行哪种场景选哪种如果你希望现有客户端或 Agent 以最少自定义代码连接 Hindsight选MCP。如果你自己构建应用希望直接掌控 bank ID、请求流程与记忆使用方式选SDK 集成。客户端已经良好支持 MCP 时从 MCP 起步整个应用都由你自己写时从 SDK 起步。两条路径没有绝对的优劣它们解决的是不同的集成问题MCP 提供标准化的协议接口供兼容客户端使用SDK 集成提供对你自己代码库内部路由、提示词与应用行为更紧密的控制。MCP 在实际中意味着什么采用 MCP 时Hindsight 通过标准协议端点暴露 retain、recall、reflect 等工具兼容客户端连接到该端点后即可调用这些工具。当客户端本身已经理解 MCP 时这是理想方案——你无需从零编写一套自定义记忆层。典型适配场景Claude DesktopCursorWindsurfChatGPT 连接器通过其他平台搭建的 MCP 网关源码视角MCP 工具是怎么暴露的从源码结构看Hindsight 的 MCP 工具实现在共享模块 mcp_tools.py 中文件头部注释明确说明它同时服务于两个传输层mcp_local.py面向 Claude Code 的本地 stdio/HTTP 场景api/mcp.pyAPI 服务端的 HTTP 传输基于 FastMCP。mcp_tools.py#L36-L78 中以显式清单无通配符定义了全部 MCP 工具_ALL_TOOLS覆盖面远超原文档提到的三个核心工具包括记忆核心retain、sync_retain、recall、reflect银行管理list_banks、create_bank、get_bank、get_bank_stats、update_bank、delete_bank、clear_memories心智模型list_mental_models、create_mental_model、update_mental_model、refresh_mental_model、clear_mental_model等其他list_directives、list_memories、list_documents、list_operations、list_tags、知识库系列工具search_knowledge_base、get_knowledge_page等工具描述本身也是可配置的模块从 config.py 引入DEFAULT_MCP_RECALL_DESCRIPTION与DEFAULT_MCP_RETAIN_DESCRIPTION作为默认描述说明运营方可以定制客户端看到的工具文案——这对一个端点供多个客户端共享的场景很关键。MCP 端点的两种挂载模式api/mcp.py 将 MCP 服务器以中间件形式挂载到默认前缀/mcp并区分两种模式见 api/mcp.py#L335-L375 的源码注释多银行模式/mcp/根端点客户端可访问多个记忆银行银行路由交给客户端与工具调用参数决定单银行模式/mcp/{bank_id}/端点本身绑定一个银行例如http://localhost:8888/mcp/my-agent-bank/。源码注释中给出的 Claude Code 接入示例# 单银行模式 claude mcp add --transport http my-agent http://localhost:8888/mcp/my-agent-bank/ \ # ... # 多银行模式 claude mcp add --transport http hindsight http://localhost:8888/mcp \ # ...本地快速起步hindsight-local-mcpmcp_local.py 是一个薄封装以本地默认配置内嵌 PostgreSQL via pg0、warning 日志级别启动完整的 hindsight-api 服务默认运行在localhost:8888。其文档字符串给出了可直接复制的配置方式# 多银行模式 claude mcp add --transport http hindsight http://localhost:8888/mcp/ # 固定到某个银行单银行模式 claude mcp add --transport http hindsight http://localhost:8888/mcp/default/启动方式为hindsight-local-mcp或uvx hindsight-apilatest hindsight-local-mcp。相关环境变量见 mcp_local.py#L19-L23环境变量必填说明HINDSIGHT_API_LLM_API_KEY是LLM 提供商的 API keyHINDSIGHT_API_LLM_PROVIDER否LLM 提供商默认openaiHINDSIGHT_API_LLM_MODEL否LLM 模型默认gpt-4o-miniHINDSIGHT_API_DATABASE_URL否覆盖数据库 URL默认pg0://hindsight-mcpMCP 端点还内置了认证机制api/mcp.py 支持环境变量HINDSIGHT_MCP_BANK_ID指定默认银行保留mcp_auth_token作为遗留认证方式并可通过租户扩展tenant extension做更细粒度的鉴权——生产环境多客户端共享一个端点时这一点不可忽视。MCP 路线的优势很直观客户端连上之后记忆能力即可用无需做大量应用特定集成工作。SDK 集成在实际中意味着什么采用 SDK 集成时你的应用通过包或客户端库直接调用 Hindsight。由你决定工具何时创建、使用哪些 bank ID、记忆如何嵌入其余请求管线。当你掌握应用代码、希望记忆成为内部架构的一部分而非外部工具端点时这是更合适的方案。典型适配场景Vercel AI SDK 应用AG2、Paperclip 等框架集成自定义 API 后端请求处理器中需要严格按用户路由的应用源码视角Python 客户端的能力边界Hindsight 的 Python 客户端位于 hindsight-clients/python其中 hindsight_client.py 是人工维护的高层封装文件头注明其构建在自动生成的 OpenAPI 客户端之上而非自动生成。核心方法与 MCP 工具一一对应但把决定何时调用的权力还给了你的代码memory 写入retainL346 起的关键参数def retain( self, bank_id: str, # 记忆银行 ID —— 路由完全由你的代码决定 content: str | list[ContentBlock], # 纯文本或图文混排的 content blocks timestamp: datetime | None None, context: str | None None, document_id: str | None None, metadata: dict[str, str] | None None, entities: list[dict[str, str]] | None None, resolve_entities: bool | None None, tags: list[str] | None None, update_mode: str | None None, # 对已有文档的处理方式replace 或 append retain_async: bool False, # True 时后台异步处理 operation_id: str | None None, # 异步场景下幂等重试的调用方 UUID ) - RetainResponserecallL504 起与 reflectL590 起同样以bank_id为第一参数并暴露了检索细节的完整控制面types事实类型、budget默认mid、max_tokens、tags_matchany/all/any_strict/all_strict/exact、prefer_observations、min_scores、temporal_window等。这些参数意味着什么时候 retain、什么时候 recall、用哪个银行、召回多少全部由应用代码显式决定——这正是原文档所说应用级正确性与隔离保证的落点。此外客户端还附带了文件摄取retain_files自动转换 PDF、DOCX、图片 OCR、音频转写以及create_bank、create_mental_model、create_directive等管理方法均有对应的异步变体aretain、arecall、areflect等。嵌入式部署HindsightEmbedded如果不想单独跑一个服务端进程hindsight-all 包提供 HindsightEmbedded它管理守护进程生命周期首次使用时自动拉起 daemonprofile 数据隔离存储在~/.pg0/instances/hindsight-embed-{profile}/。文档字符串中的示例embedded.py#L8-L33from hindsight import HindsightEmbedded # Daemon 在首次使用时自动启动 client HindsightEmbedded( profilemyapp, llm_providergroq, llm_api_keyyour-api-key, ) # 用法与 HindsightClient 一致 client.retain(bank_idalice, contentAlice loves AI) results client.recall(bank_idalice, queryWhat does Alice like?) # 可选清理 client.close()一个值得注意的继承语义构造时显式传入的设置才会转发给 daemon留空的配置按profile 的 .env 文件 → 父进程环境 → daemon 自身默认值的顺序解析。这使得在不传凭据的情况下也能复用已配置好的 profile避免用占位值覆盖真实配置。并排对比维度MCPSDK最适合现有兼容客户端你自己构建的应用集成工作量低高应用控制力低高协议标准化程度高低银行路由控制中等高适合非编码用户使用工具是较少适合自定义产品逻辑有时是从源码结构看这张表的银行路由控制一行有直接证据MCP 单银行模式把路由固定在 URL 路径上/mcp/{bank_id}/多银行模式则由客户端在每次工具调用中指定银行而 SDK 中bank_id是每次retain/recall/reflect调用的显式参数可以在请求处理器内按用户、租户动态计算——这是 SDK 控制力更高的本质来源。什么时候 MCP 是更好的选择满足以下条件时MCP 更合适你的客户端已经干净利落地支持 MCP你希望有一个标准的工具接口你不想编写记忆胶水代码你希望一个端点被多个工具/客户端共享。这也是 MCP 对桌面 AI 工具和多客户端环境有吸引力的原因配置端点、完成鉴权记忆工具就出现在客户端里。本地部署时前文的hindsight-local-mcp与/mcp/端点是最直接的起步路径。什么时候 SDK 集成是更好的选择满足以下条件时SDK 集成更合适你已经掌控请求处理器或后端代码你需要显式的按用户/按租户银行路由记忆应深度融入你的应用逻辑你想精确决定 retain 或 recall 发生的时机。对应用型产品构建者这通常是更好的路径。自定义逻辑越深直接集成模式的价值就越大。SDK 的retain_asyncoperation_id幂等重试、update_mode文档级 replace/append、temporal_window时间窗口召回这类参数都是把记忆行为当作应用内部状态来精细管理的例子。关键权衡智能住在哪里两条路径最核心的区别是智能决策权所在的位置用MCP时是客户端决定何时、如何调用工具用SDK 集成时是你的应用决定记忆如何嵌入工作流。因此 MCP 往往上手更快而 SDK 集成往往更适合产品级的正确性与隔离要求。常见场景速查选 MCP 的场景要把 Claude Desktop 接入记忆希望 Cursor 或 Windsurf 快速用上 Hindsight要通过网关类平台把记忆暴露给多个客户端希望一套协议面服务多种客户端。选 SDK 的场景你在构建 Vercel AI SDK 产品AG2 或 Paperclip 工作流需要感知请求的银行路由你希望记忆行为由服务端逻辑控制你需要围绕隔离性更紧的保证。迁移说明两条路径可以互相转化很多团队从 MCP 起步因为它验证起来快。之后当记忆成为核心产品能力时会把关键路径迁移到 SDK 集成让银行路由与 retain 时机回归应用所有。反向迁移同样存在构建自定义应用的团队之后仍可以把同一个记忆银行通过 MCP 暴露给开发者工具或支持型客户端。两条路径共享同一套引擎——MCP 工具在 mcp_tools.py 中直接调用MemoryEngineSDK 客户端通过 REST API 命中同一引擎——所以迁移的是决策边界而不是数据或能力。常见问题MCP 的能力不如 SDK 集成吗不完全是。差异更多在控制力而非能力本身MCP 工具清单_ALL_TOOLS覆盖了银行管理、心智模型、记忆单元、文档、操作与知识库等数十个工具能力面相当完整区别在于调用时机与参数决策交给客户端模型。SDK 集成总是更费工吗通常是的但这些额外工作往往换来更好的应用级保证显式路由、幂等重试、时间窗口检索等。可以两者并用吗可以。很多团队在产品内部使用 SDK 集成同时用 MCP 服务周边工具链。应该先从哪个开始客户端已支持 MCP 就从 MCP 开始已经拥有应用后端就从 SDK 开始。延伸阅读路径原始对比文档2026-04-16-comparison-mcp-vs-sdk-memory-with-hindsight.mdMCP 工具共享实现mcp_tools.pyMCP HTTP 传输与端点挂载api/mcp.py本地 MCP 快速起步mcp_local.pyPython 客户端封装hindsight_client.py嵌入式客户端embedded.py文档站源码目录hindsight-docs【免费下载链接】hindsightHindsight: Agent Memory That Learns项目地址: https://gitcode.com/GitHub_Trending/hindsight2/hindsight创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
Hindsight 记忆接入选型指南：MCP 与 SDK 两种集成路径的源码级对比
Hindsight 记忆接入选型指南MCP 与 SDK 两种集成路径的源码级对比【免费下载链接】hindsightHindsight: Agent Memory That Learns项目地址: https://gitcode.com/GitHub_Trending/hindsight2/hindsight当你为 AI 应用选择记忆接入方式时真正的分界线在于集成边界放在哪里MCP 适合让现成的客户端或 Agent 以工具服务器的方式连接 HindsightSDK 集成则适合你自己掌握应用逻辑、把记忆直接嵌入代码的场景。本文基于 Hindsight 仓库中的 MCP 工具注册模块、MCP 服务挂载代码与 Python 客户端源码对比这两条路径的适用场景、控制粒度与迁移路径读完你可以直接判断自己的项目该选哪条路、如何起步、以及后续如何演进。结论先行哪种场景选哪种如果你希望现有客户端或 Agent 以最少自定义代码连接 Hindsight选MCP。如果你自己构建应用希望直接掌控 bank ID、请求流程与记忆使用方式选SDK 集成。客户端已经良好支持 MCP 时从 MCP 起步整个应用都由你自己写时从 SDK 起步。两条路径没有绝对的优劣它们解决的是不同的集成问题MCP 提供标准化的协议接口供兼容客户端使用SDK 集成提供对你自己代码库内部路由、提示词与应用行为更紧密的控制。MCP 在实际中意味着什么采用 MCP 时Hindsight 通过标准协议端点暴露 retain、recall、reflect 等工具兼容客户端连接到该端点后即可调用这些工具。当客户端本身已经理解 MCP 时这是理想方案——你无需从零编写一套自定义记忆层。典型适配场景Claude DesktopCursorWindsurfChatGPT 连接器通过其他平台搭建的 MCP 网关源码视角MCP 工具是怎么暴露的从源码结构看Hindsight 的 MCP 工具实现在共享模块 mcp_tools.py 中文件头部注释明确说明它同时服务于两个传输层mcp_local.py面向 Claude Code 的本地 stdio/HTTP 场景api/mcp.pyAPI 服务端的 HTTP 传输基于 FastMCP。mcp_tools.py#L36-L78 中以显式清单无通配符定义了全部 MCP 工具_ALL_TOOLS覆盖面远超原文档提到的三个核心工具包括记忆核心retain、sync_retain、recall、reflect银行管理list_banks、create_bank、get_bank、get_bank_stats、update_bank、delete_bank、clear_memories心智模型list_mental_models、create_mental_model、update_mental_model、refresh_mental_model、clear_mental_model等其他list_directives、list_memories、list_documents、list_operations、list_tags、知识库系列工具search_knowledge_base、get_knowledge_page等工具描述本身也是可配置的模块从 config.py 引入DEFAULT_MCP_RECALL_DESCRIPTION与DEFAULT_MCP_RETAIN_DESCRIPTION作为默认描述说明运营方可以定制客户端看到的工具文案——这对一个端点供多个客户端共享的场景很关键。MCP 端点的两种挂载模式api/mcp.py 将 MCP 服务器以中间件形式挂载到默认前缀/mcp并区分两种模式见 api/mcp.py#L335-L375 的源码注释多银行模式/mcp/根端点客户端可访问多个记忆银行银行路由交给客户端与工具调用参数决定单银行模式/mcp/{bank_id}/端点本身绑定一个银行例如http://localhost:8888/mcp/my-agent-bank/。源码注释中给出的 Claude Code 接入示例# 单银行模式 claude mcp add --transport http my-agent http://localhost:8888/mcp/my-agent-bank/ \ # ... # 多银行模式 claude mcp add --transport http hindsight http://localhost:8888/mcp \ # ...本地快速起步hindsight-local-mcpmcp_local.py 是一个薄封装以本地默认配置内嵌 PostgreSQL via pg0、warning 日志级别启动完整的 hindsight-api 服务默认运行在localhost:8888。其文档字符串给出了可直接复制的配置方式# 多银行模式 claude mcp add --transport http hindsight http://localhost:8888/mcp/ # 固定到某个银行单银行模式 claude mcp add --transport http hindsight http://localhost:8888/mcp/default/启动方式为hindsight-local-mcp或uvx hindsight-apilatest hindsight-local-mcp。相关环境变量见 mcp_local.py#L19-L23环境变量必填说明HINDSIGHT_API_LLM_API_KEY是LLM 提供商的 API keyHINDSIGHT_API_LLM_PROVIDER否LLM 提供商默认openaiHINDSIGHT_API_LLM_MODEL否LLM 模型默认gpt-4o-miniHINDSIGHT_API_DATABASE_URL否覆盖数据库 URL默认pg0://hindsight-mcpMCP 端点还内置了认证机制api/mcp.py 支持环境变量HINDSIGHT_MCP_BANK_ID指定默认银行保留mcp_auth_token作为遗留认证方式并可通过租户扩展tenant extension做更细粒度的鉴权——生产环境多客户端共享一个端点时这一点不可忽视。MCP 路线的优势很直观客户端连上之后记忆能力即可用无需做大量应用特定集成工作。SDK 集成在实际中意味着什么采用 SDK 集成时你的应用通过包或客户端库直接调用 Hindsight。由你决定工具何时创建、使用哪些 bank ID、记忆如何嵌入其余请求管线。当你掌握应用代码、希望记忆成为内部架构的一部分而非外部工具端点时这是更合适的方案。典型适配场景Vercel AI SDK 应用AG2、Paperclip 等框架集成自定义 API 后端请求处理器中需要严格按用户路由的应用源码视角Python 客户端的能力边界Hindsight 的 Python 客户端位于 hindsight-clients/python其中 hindsight_client.py 是人工维护的高层封装文件头注明其构建在自动生成的 OpenAPI 客户端之上而非自动生成。核心方法与 MCP 工具一一对应但把决定何时调用的权力还给了你的代码memory 写入retainL346 起的关键参数def retain( self, bank_id: str, # 记忆银行 ID —— 路由完全由你的代码决定 content: str | list[ContentBlock], # 纯文本或图文混排的 content blocks timestamp: datetime | None None, context: str | None None, document_id: str | None None, metadata: dict[str, str] | None None, entities: list[dict[str, str]] | None None, resolve_entities: bool | None None, tags: list[str] | None None, update_mode: str | None None, # 对已有文档的处理方式replace 或 append retain_async: bool False, # True 时后台异步处理 operation_id: str | None None, # 异步场景下幂等重试的调用方 UUID ) - RetainResponserecallL504 起与 reflectL590 起同样以bank_id为第一参数并暴露了检索细节的完整控制面types事实类型、budget默认mid、max_tokens、tags_matchany/all/any_strict/all_strict/exact、prefer_observations、min_scores、temporal_window等。这些参数意味着什么时候 retain、什么时候 recall、用哪个银行、召回多少全部由应用代码显式决定——这正是原文档所说应用级正确性与隔离保证的落点。此外客户端还附带了文件摄取retain_files自动转换 PDF、DOCX、图片 OCR、音频转写以及create_bank、create_mental_model、create_directive等管理方法均有对应的异步变体aretain、arecall、areflect等。嵌入式部署HindsightEmbedded如果不想单独跑一个服务端进程hindsight-all 包提供 HindsightEmbedded它管理守护进程生命周期首次使用时自动拉起 daemonprofile 数据隔离存储在~/.pg0/instances/hindsight-embed-{profile}/。文档字符串中的示例embedded.py#L8-L33from hindsight import HindsightEmbedded # Daemon 在首次使用时自动启动 client HindsightEmbedded( profilemyapp, llm_providergroq, llm_api_keyyour-api-key, ) # 用法与 HindsightClient 一致 client.retain(bank_idalice, contentAlice loves AI) results client.recall(bank_idalice, queryWhat does Alice like?) # 可选清理 client.close()一个值得注意的继承语义构造时显式传入的设置才会转发给 daemon留空的配置按profile 的 .env 文件 → 父进程环境 → daemon 自身默认值的顺序解析。这使得在不传凭据的情况下也能复用已配置好的 profile避免用占位值覆盖真实配置。并排对比维度MCPSDK最适合现有兼容客户端你自己构建的应用集成工作量低高应用控制力低高协议标准化程度高低银行路由控制中等高适合非编码用户使用工具是较少适合自定义产品逻辑有时是从源码结构看这张表的银行路由控制一行有直接证据MCP 单银行模式把路由固定在 URL 路径上/mcp/{bank_id}/多银行模式则由客户端在每次工具调用中指定银行而 SDK 中bank_id是每次retain/recall/reflect调用的显式参数可以在请求处理器内按用户、租户动态计算——这是 SDK 控制力更高的本质来源。什么时候 MCP 是更好的选择满足以下条件时MCP 更合适你的客户端已经干净利落地支持 MCP你希望有一个标准的工具接口你不想编写记忆胶水代码你希望一个端点被多个工具/客户端共享。这也是 MCP 对桌面 AI 工具和多客户端环境有吸引力的原因配置端点、完成鉴权记忆工具就出现在客户端里。本地部署时前文的hindsight-local-mcp与/mcp/端点是最直接的起步路径。什么时候 SDK 集成是更好的选择满足以下条件时SDK 集成更合适你已经掌控请求处理器或后端代码你需要显式的按用户/按租户银行路由记忆应深度融入你的应用逻辑你想精确决定 retain 或 recall 发生的时机。对应用型产品构建者这通常是更好的路径。自定义逻辑越深直接集成模式的价值就越大。SDK 的retain_asyncoperation_id幂等重试、update_mode文档级 replace/append、temporal_window时间窗口召回这类参数都是把记忆行为当作应用内部状态来精细管理的例子。关键权衡智能住在哪里两条路径最核心的区别是智能决策权所在的位置用MCP时是客户端决定何时、如何调用工具用SDK 集成时是你的应用决定记忆如何嵌入工作流。因此 MCP 往往上手更快而 SDK 集成往往更适合产品级的正确性与隔离要求。常见场景速查选 MCP 的场景要把 Claude Desktop 接入记忆希望 Cursor 或 Windsurf 快速用上 Hindsight要通过网关类平台把记忆暴露给多个客户端希望一套协议面服务多种客户端。选 SDK 的场景你在构建 Vercel AI SDK 产品AG2 或 Paperclip 工作流需要感知请求的银行路由你希望记忆行为由服务端逻辑控制你需要围绕隔离性更紧的保证。迁移说明两条路径可以互相转化很多团队从 MCP 起步因为它验证起来快。之后当记忆成为核心产品能力时会把关键路径迁移到 SDK 集成让银行路由与 retain 时机回归应用所有。反向迁移同样存在构建自定义应用的团队之后仍可以把同一个记忆银行通过 MCP 暴露给开发者工具或支持型客户端。两条路径共享同一套引擎——MCP 工具在 mcp_tools.py 中直接调用MemoryEngineSDK 客户端通过 REST API 命中同一引擎——所以迁移的是决策边界而不是数据或能力。常见问题MCP 的能力不如 SDK 集成吗不完全是。差异更多在控制力而非能力本身MCP 工具清单_ALL_TOOLS覆盖了银行管理、心智模型、记忆单元、文档、操作与知识库等数十个工具能力面相当完整区别在于调用时机与参数决策交给客户端模型。SDK 集成总是更费工吗通常是的但这些额外工作往往换来更好的应用级保证显式路由、幂等重试、时间窗口检索等。可以两者并用吗可以。很多团队在产品内部使用 SDK 集成同时用 MCP 服务周边工具链。应该先从哪个开始客户端已支持 MCP 就从 MCP 开始已经拥有应用后端就从 SDK 开始。延伸阅读路径原始对比文档2026-04-16-comparison-mcp-vs-sdk-memory-with-hindsight.mdMCP 工具共享实现mcp_tools.pyMCP HTTP 传输与端点挂载api/mcp.py本地 MCP 快速起步mcp_local.pyPython 客户端封装hindsight_client.py嵌入式客户端embedded.py文档站源码目录hindsight-docs【免费下载链接】hindsightHindsight: Agent Memory That Learns项目地址: https://gitcode.com/GitHub_Trending/hindsight2/hindsight创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
