Hindsight MCP Server 完全指南为 AI 助手构建可存储、可检索、可反思的长期记忆接口【免费下载链接】hindsightHindsight: Agent Memory That Learns项目地址: https://gitcode.com/GitHub_Trending/hindsight2/hindsight导读Hindsight 内置了一个符合 Model Context ProtocolMCP标准的服务器让任何 MCP 兼容的 AI 助手如 Claude Code、Claude Desktop都能通过统一协议直接向记忆库写入事实、检索上下文、生成反思分析并管理心理模型。本文基于hindsight-docs/versioned_docs/version-0.7/developer/mcp-server.md展开并结合仓库源码hindsight-api-slim/hindsight_api/api/mcp.py、mcp_tools.py、config.py深入讲解访问方式、认证配置、单库/多库两种模式、全部工具的用法与参数以及底层实现原理帮助你完成从看懂文档到上手接入的完整闭环。MCP Server 是什么Hindsight 的 MCP Server 是内置于 API 服务器中的一个端点它把记忆能力以 MCP 工具tools的形式暴露给 AI 助手。助手不再需要了解 Hindsight 的内部 API只要遵循 MCP 协议就能直接retain / sync_retain把事实、偏好、事件写入长期记忆recall用自然语言检索记忆为个性化回复提供上下文reflect基于已存储记忆与记忆库个性生成综合性的思考分析create_mental_model创建会自动随新记忆刷新的心理模型预计算的反思文档管理文档、指令directives、异步操作operations、标签与记忆库本身。从源码看MCP 工具逻辑集中在共享模块 mcp_tools.py同一套实现被两条传输路径复用mcp_local.pystdio 传输供 Claude Code 本地使用与 api/mcp.pyHTTP 传输供 API 服务器挂载。这意味着无论通过哪种方式接入工具语义完全一致。访问默认启用挂载在 /mcpMCP Server默认开启挂载在 API 服务器的/mcp路径上每个记忆库memory bank拥有独立的 MCP 端点http://localhost:8888/mcp/{bank_id}/例如连接记忆库alicehttp://localhost:8888/mcp/alice/对应的源码依据config.py 中DEFAULT_MCP_ENABLED True第 1454 行默认值由环境变量HINDSIGHT_API_MCP_ENABLED控制server.py 在创建应用时传入mcp_api_enabledconfig.mcp_enabled与mcp_mount_path/mcp将 MCP 中间件挂到主应用上。需要关闭时设置环境变量export HINDSIGHT_API_MCP_ENABLEDfalse除此之外仓库还提供几个与服务行为相关的环境变量见 config.py 第 649-653 行环境变量默认值说明HINDSIGHT_API_MCP_ENABLEDtrue是否启用 MCP 服务器HINDSIGHT_API_MCP_ENABLED_TOOLS未设置全部工具全局工具白名单逗号分隔例如retain,recallHINDSIGHT_API_MCP_STATELESSfalsefalse为有状态支持 SSE/GETtrue为无状态仅 POSTHINDSIGHT_API_MCP_INSTRUCTIONS未设置附加指令文本会自动拼接到 retain/recall 工具描述末尾HINDSIGHT_API_MCP_AUTH_TOKEN未设置传统静态令牌认证向后兼容见下文认证认证从完全开放到API Key 校验默认行为开放默认情况下MCP 端点不要求认证直接可用。这在本地开发与内网部署时非常方便对应源码中的DefaultTenantExtension见 extensions/builtin/tenant.py其authenticate()直接返回配置的 schema不校验任何凭据。启用认证ApiKeyTenantExtension要开启认证配置 API Key 租户扩展export HINDSIGHT_API_TENANT_EXTENSIONhindsight_api.extensions.builtin.tenant:ApiKeyTenantExtension export HINDSIGHT_API_TENANT_API_KEYyour-secret-key启用后请求必须在Authorization头中携带 API Key。若 Key 缺失或无效请求将收到401 Unauthorized响应。该扩展还有两个可选配置见ApiKeyTenantExtension源码注释HINDSIGHT_API_DATABASE_SCHEMA认证通过后使用的 PostgreSQL schema默认publicHINDSIGHT_API_TENANT_MCP_AUTH_DISABLEDtrue为兼容旧版 MCP 服务器而单独关闭 MCP 端点的认证HTTP API 仍校验。两种认证机制的优先级在 api/mcp.py 的MCPMiddleware中认证顺序是若设置了HINDSIGHT_API_MCP_AUTH_TOKEN传统模式先校验该静态令牌校验通过则标记为预认证跳过租户扩展的再次校验否则调用TenantExtension.authenticate_mcp()进行认证。从源码看认证结果不仅用于放行/拒绝还会通过RequestContext把tenant_id、api_key_id等传递下去用于用量计量usage metering与租户 schema 隔离。三种客户端配置示例Claude Code命令行方式claude mcp add --transport http hindsight http://localhost:8888/mcp \ --header Authorization: Bearer your-secret-key \ --header X-Bank-Id: my-bankClaude Desktop配置文件方式编辑~/.claude_desktop_config.json{ mcpServers: { hindsight: { url: http://localhost:8888/mcp, headers: { Authorization: Bearer your-secret-key, X-Bank-Id: my-bank } } } }直接 HTTP 请求curl 验证curl -X POST http://localhost:8888/mcp \ -H Authorization: Bearer your-secret-key \ -H X-Bank-Id: my-bank \ -H Content-Type: application/json \ -H Accept: application/json, text/event-stream \ -d {jsonrpc: 2.0, method: tools/list, id: 1}小贴士MCPMiddleware还会主动为请求补上Accept: application/json, text/event-stream头兼容部分不发 Accept 的客户端如某些 Claude Code 版本避免 406 错误对于无会话 ID 的 GET 探测请求则直接返回 200 OK 以便客户端继续发起initialize。记忆库选择Bank Selection连接时使用哪个记忆库按以下优先级解析URL 路径优先级最高http://localhost:8888/mcp/my-bank/X-Bank-Id 请求头--header X-Bank-Id: my-bank默认值使用HINDSIGHT_MCP_BANK_ID环境变量默认default这一逻辑对应 api/mcp.py 中的实现先从 URL path 提取第一段作为 bank_id并标记为路径来源取不到再读X-Bank-Id头最后回落到模块级常量DEFAULT_BANK_ID os.environ.get(HINDSIGHT_MCP_BANK_ID, default)。关键细节bank_id 的解析来源决定了运行模式。从路径解析到 bank_id 时走单库模式通过 header 或环境变量解析时走多库模式见下文。按库端点Per-Bank Endpoints与隔离设计与传统 MCP 服务器所有工具都要求显式传标识符不同Hindsight 采用按库端点设计bank_id属于 URL 路径的一部分工具无需也无法指定操作哪个库——连接本身就已隐含目标。这种设计带来的三个直接好处简化工具调用——每次调用都不必再传bank_id参数强制隔离——每条 MCP 连接只作用于一个记忆库防止越权访问支持多租户——把不同用户连接到不同端点即可天然完成数据隔离。从源码结构看这一设计贯彻到工具注册层MCPToolsConfig.include_bank_id_param决定工具是否带bank_id参数mcp_tools.py 第 270 行。单库模式下include_bank_id_paramFalse工具通过bank_id_resolver从当前连接上下文解析库多库模式下每个工具额外暴露可选的bank_id参数实现跨库操作。两种模式单库Single-bank与多库Multi-bankMCP 服务器根据 URL 结构在两种模式下运行模式URL工具bank_id单库模式/mcp/{bank_id}/27 个工具记忆、心理模型、指令、文档、操作、标签、库管理隐含于 URL多库模式/mcp/全部 30 个工具含list_banks、create_bank、get_bank_stats每个工具显式传bank_id参数单库模式推荐所有操作都被限定在 URL 指定的记忆库内工具不暴露bank_id参数。源码中_SINGLE_BANK_TOOLS明确排除了三个库管理工具list_banks、create_bank、get_bank_stats从根上杜绝了跨库操作的可能。多库模式暴露全部工具并附带可选的bank_id参数同时提供库管理工具list_banks、create_bank、get_bank_stats适合需要在一个连接里管理多个记忆库的场景例如平台型应用的后台管理。从 test_mcp_endpoint_routing.py 的测试可以看出/mcp/my-bank无尾斜杠同样能路由到单库模式SSE 事件流中的/messages地址也会被改写成/my-bank/messages以保证流式会话正确。可用工具详解以下按功能域逐个介绍工具。所有表格参数均以原文档为准并结合 mcp_tools.py 中的工具注册源码核对。记忆写入类retain把信息存入长期记忆异步。参数类型必填说明contentstring是要存储的事实或记忆contextstring否记忆的分类默认generaltimestampstring否事件发生的 ISO 8601 时间戳tagslist[string]否用于组织与过滤记忆的标签metadataobject否附加的键值元数据如{source: slack}document_idstring否将该记忆关联到已有文档示例{ name: retain, arguments: { content: User prefers Python over JavaScript for backend development, context: programming_preferences, tags: [user:alice, preferences] } }适用场景用户分享个人信息/偏好/兴趣提及重要事件或里程碑陈述决策、观点或目标讨论工作上下文或项目细节。从源码看retain通过memory.submit_async_retain()提交异步任务立即返回operation_id响应包含status: accepted记忆的抽取与落库在后台完成。底层还会做内容分块chunking、实体抽取与后续的记忆巩固consolidation等处理。sync_retain把信息存入长期记忆并等待完成。与异步的retain不同sync_retain会阻塞直到记忆完全存储、立即可被检索——适用于写入后立刻查询的读后写read-after-write流程。参数与retain完全一致content、context、timestamp、tags、metadata、document_id。适用场景存储后需要立即查询该记忆工作流下一步依赖该记忆已可用其余情况优先用异步retain以避免阻塞。记忆检索与反思类recall搜索记忆以提供个性化回复。参数类型必填说明querystring是自然语言搜索查询max_tokensinteger否返回结果的最大 token 数默认 4096budgetstring否搜索深度low、mid或high默认hightypeslist[string]否按事实类型过滤world、experience、observation默认全部tagslist[string]否按标签过滤记忆tags_matchstring否标签匹配模式any默认或allquery_timestampstring否ISO 8601 时间戳——以该时间点进行回忆用于锚定相对时间表达与近因打分示例{ name: recall, arguments: { query: What are the users programming language preferences?, tags: [preferences], budget: high } }适用场景对话开始时回忆相关上下文做推荐之前用户询问可能提到过的事情跨会话保持连续性。recall是 MCP 工具中标注了readOnlyHint的只读工具见 mcp_tools.py 中_READ_ONLY_TOOLS集合客户端可以据此对安全读取做自动放行。reflect通过综合已存储记忆与记忆库的个性生成有深度的分析。参数类型必填说明querystring是要反思的问题或主题contextstring否关于为何需要本次反思的上下文budgetstring否搜索预算low、mid或high默认lowmax_tokensinteger否响应的最大 token 数默认 4096response_schemaobject否结构化输出的 JSON Schema。提供时响应会包含structured_output字段tagslist[string]否反思前按标签过滤记忆tags_matchstring否标签匹配模式any默认或all示例{ name: reflect, arguments: { query: Based on my past decisions, what architectural style do I prefer?, budget: mid, tags: [architecture] } }适用场景需要推理分析而非单纯事实检索回答我该怎么做而非我说过什么跨多条记忆归纳模式。心理模型类Mental Models心理模型是会随着记忆自动更新的预计算反思文档是 Hindsight 记忆体系的一大特色。create_mental_model创建一个心理模型异步生成内容。参数类型必填说明namestring是心理模型的可读名称source_querystring是用于生成与刷新模型的查询mental_model_idstring否自定义 ID小写字母数字加连字符缺省自动生成tagslist[string]否用于组织与过滤模型的标签max_tokensinteger否模型内容的最大 token 数默认 2048trigger_refresh_after_consolidationboolean否记忆巩固后自动刷新该模型默认false示例{ name: create_mental_model, arguments: { name: Team Directory, source_query: Who works here and what do they do?, tags: [team, people] } }内容生成异步执行响应包含operation_id用于跟踪进度。在仓库较新版本中刷新策略已被扩展为完整的MentalModelTriggerInput支持refresh_cron定时刷新、min_refresh_interval_seconds最小刷新间隔、fact_types事实类型过滤、exclude_mental_model_ids排除兄弟模型等字段MCP 层保留trigger_refresh_after_consolidation作为旧版简写参数两者并存且互不冲突见 mcp_tools.py 中MentalModelTriggerInput与_mental_model_trigger_patch。list_mental_models列出记忆库中全部心理模型可按标签过滤。参数类型必填说明tagslist[string]否按标签过滤模型get_mental_model按 ID 获取指定心理模型含完整内容。参数类型必填说明mental_model_idstring是要获取的心理模型 IDupdate_mental_model更新心理模型的元数据或设置。参数类型必填说明mental_model_idstring是要更新的心理模型 IDnamestring否新名称source_querystring否新的源查询tagslist[string]否新标签max_tokensinteger否新的最大 token 数trigger_refresh_after_consolidationboolean否巩固后是否自动刷新。仅在需要修改此设置时传入delete_mental_model永久删除一个心理模型。参数类型必填说明mental_model_idstring是要删除的心理模型 IDrefresh_mental_model用最新记忆重新生成心理模型内容异步执行。参数类型必填说明mental_model_idstring是要刷新的心理模型 IDclear_mental_model清空心理模型内容但保留其定义。清空后调用refresh_mental_model可从最新记忆重建。参数类型必填说明mental_model_idstring是要清空的心理模型 ID记忆库管理类仅多库模式list_banks仅多库模式列出所有可用的记忆库。create_bank仅多库模式创建新记忆库或获取已存在的库。参数类型必填说明bank_idstring是新记忆库的 IDnamestring否记忆库的人类友好名称missionstring否描述这个 agent 是谁、想达成什么的使命说明get_bank_stats仅多库模式获取记忆库的统计信息节点/链接数量。指令类Directives指令是指导记忆系统如何处理与响应用户查询的规则。list_directives列出记忆库中的全部指令。参数类型必填说明tagslist[string]否按标签过滤指令active_onlyboolean否只返回激活中的指令默认truecreate_directive在记忆库中创建一条新指令。参数类型必填说明namestring是指令的可读名称contentstring是指令内容/说明priorityinteger否优先级数值越大越重要is_activeboolean否指令是否激活默认truetagslist[string]否用于组织指令的标签delete_directive按 ID 删除指令。参数类型必填说明directive_idstring是要删除的指令 ID记忆浏览类list_memories浏览已存储的记忆支持过滤与分页。参数类型必填说明typestring否按事实类型过滤world、experience或observationqstring否过滤记忆的搜索查询limitinteger否最大结果数默认 100offsetinteger否分页跳过的结果数默认 0get_memory按 ID 获取指定记忆。参数类型必填说明memory_idstring是要获取的记忆 ID文档类list_documents列出已摄入记忆库的文档。参数类型必填说明qstring否过滤文档的搜索查询limitinteger否最大结果数默认 100get_document按 ID 获取指定文档含其元数据。参数类型必填说明document_idstring是要获取的文档 IDdelete_document删除文档及其关联的全部记忆。参数类型必填说明document_idstring是要删除的文档 ID异步操作类list_operations列出异步操作retain 处理、心理模型刷新等可按状态过滤。参数类型必填说明statusstring否按状态过滤pending、running、completed、failed、cancelledlimitinteger否最大结果数默认 100get_operation获取异步操作的状态与详情。参数类型必填说明operation_idstring是要检查的操作 IDcancel_operation取消一个 pending 或 running 的异步操作。参数类型必填说明operation_idstring是要取消的操作 ID标签与记忆库配置类list_tags列出记忆库中全部唯一标签可按模式过滤。参数类型必填说明qstring否过滤标签的 Glob 模式如project:*limitinteger否最大结果数默认 100get_bank获取记忆库信息包括名称、使命与 disposition倾向配置。update_bank更新记忆库配置。只更新提供的字段未提供的字段保持不变。参数类型必填说明namestring否记忆库的人类友好显示名称missionstring否已弃用——config_updates.reflect_mission的别名config_updatesobject否要更新的配置字段字典支持所有库级可配置字段。不可配置字段与凭据字段会被拒绝config_updates对象按 Python 字段名接受任何库级可配置字段包括reflect_mission— Reflect 操作的使命/上下文retain_mission— 引导retain()抽取什么内容retain_extraction_mode—concise默认、verbose或customretain_custom_instructions— 自定义抽取提示词模式为custom时生效retain_chunk_size— 每个内容块的最大 token 数retain_chunk_batch_size— 并行处理的分块数enable_observations— 是否在retain()后开启观察observation巩固observations_mission— 控制观察综合规则disposition_skepticism— 批判性评估等级1–5disposition_literalism— 字面 vs 抽象解读1–5disposition_empathy— 情感上下文考量1–5entity_labels— 实体分类的受控词表entities_allow_free_form— 是否允许entity_labels之外的标签recall_include_chunks— 召回结果中是否包含原始分块recall_max_tokens— 召回结果的最大 token 数mcp_enabled_tokens— 该记忆库的工具白名单即mcp_enabled_tools注意mcp_enabled_tools既支持在update_bank中按库设置也支持全局环境变量HINDSIGHT_API_MCP_ENABLED_TOOLS。按库的过滤逻辑实现在 mcp_tools.py 的_apply_bank_tool_filtering它会同时作用于tools/list与工具实际调用两层且操作校验器OperationValidator只能进一步收窄、不能突破库配置的上限。delete_bank永久删除一个记忆库及其全部数据记忆、文档、实体、心理模型。clear_memories清空记忆库中的全部记忆但不删除库本身。可按事实类型只清理特定种类的记忆。参数类型必填说明typestring否要清理的事实类型world、experience或observation。不指定则清空全部与 AI 助手的集成MCP Server 可与任何 MCP 兼容的 AI 助手配合使用。Claude Code 与 Claude Desktop 的配置示例见上文认证章节。每个用户都可以拥有自己的配置指向各自的个人记忆库两种方式任选其一库专属 URL 路径推荐如/mcp/alice/X-Bank-Id请求头。配合单库模式每个用户 / 每个 agent 独占一个端点天然形成数据隔离是典型的多用户记忆方案的落地形态。源码级实现解析值得了解的四个工程细节1. 工具注册与双形态返回每个 MCP 工具都被注册两次多库形态带显式bank_id参数返回 JSON 文本与单库形态从会话解析库返回 dict。两者共享同一个引擎调用只是包裹逻辑不同见 mcp_tools.py 的_run_tool。这种双形态刻意保留带bank_id的变体声明返回- str调用方会json.loads因此不能擅自统一返回类型。2. 对 LLM 的容错处理_make_tools_tolerantapi/mcp.py为所有工具做了两层加固剥离未知参数LLM 常会给工具调用附加explanation、reasoning等多余字段会被 Pydantic 拒绝这里在验证前直接剔除字符串 JSON 自动转换LLM 常把tags[a,b]这样的数组/字典参数序列化成字符串这里会按参数 schema 自动json.loads还原成原生类型。3. 工具注解与客户端权限提示所有工具都标注了 MCP 的ToolAnnotationsmcp_tools.py 的_tool_annotations只读工具recall、reflect、各类list_*/get_*标readOnlyHintTrue便于客户端分组与自动放行删除/清空类工具delete_bank、clear_memories、delete_*等标destructiveHintTrue触发客户端的高风险确认所有工具openWorldHintFalse——Hindsight 是封闭记忆库不访问开放网络。4. 审计日志_apply_audit_logging为retain、recall、reflect、create_bank、各类delete_*等 20 个工具包裹了审计记录以transportmcp写入审计日志见_AUDITABLE_MCP_TOOLS集合请求参数与响应都会被记录便于追溯谁在何时对记忆做了什么。5. 本地快速启动仓库提供了本地入口 mcp_local.py运行hindsight-local-mcp或uvx hindsight-apilatest hindsight-local-mcp即可在localhost:8888拉起带默认值的 API 服务内嵌 PostgreSQL 数据源pg0://hindsight-mcp随后按上文示例配置 Claude Codeclaude mcp add --transport http hindsight http://localhost:8888/mcp/ # 或锁定到具体库单库模式 claude mcp add --transport http hindsight http://localhost:8888/mcp/default/相关测试用例可在 test_mcp_routing.py全局工具白名单过滤、test_mcp_tool_filtering.py按库工具过滤与 test_mcp_endpoint_routing.py端点路由中找到可作为理解行为边界的参考。总结Hindsight 的 MCP Server 把完整的记忆生命周期——写入retain/sync_retain、检索recall、反思reflect、沉淀mental models、治理directives、documents、operations、bank management——以标准 MCP 工具的形式开放给任意兼容助手。理解单库/多库双模式 按库端点 三级 bank 解析这三个设计要点再配合ApiKeyTenantExtension认证与mcp_enabled_tools白名单即可在生产环境中搭建安全、隔离、可审计的 AI 长期记忆服务。【免费下载链接】hindsightHindsight: Agent Memory That Learns项目地址: https://gitcode.com/GitHub_Trending/hindsight2/hindsight创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Hindsight MCP Server 完全指南：为 AI 助手构建可存储、可检索、可反思的长期记忆接口
Hindsight MCP Server 完全指南为 AI 助手构建可存储、可检索、可反思的长期记忆接口【免费下载链接】hindsightHindsight: Agent Memory That Learns项目地址: https://gitcode.com/GitHub_Trending/hindsight2/hindsight导读Hindsight 内置了一个符合 Model Context ProtocolMCP标准的服务器让任何 MCP 兼容的 AI 助手如 Claude Code、Claude Desktop都能通过统一协议直接向记忆库写入事实、检索上下文、生成反思分析并管理心理模型。本文基于hindsight-docs/versioned_docs/version-0.7/developer/mcp-server.md展开并结合仓库源码hindsight-api-slim/hindsight_api/api/mcp.py、mcp_tools.py、config.py深入讲解访问方式、认证配置、单库/多库两种模式、全部工具的用法与参数以及底层实现原理帮助你完成从看懂文档到上手接入的完整闭环。MCP Server 是什么Hindsight 的 MCP Server 是内置于 API 服务器中的一个端点它把记忆能力以 MCP 工具tools的形式暴露给 AI 助手。助手不再需要了解 Hindsight 的内部 API只要遵循 MCP 协议就能直接retain / sync_retain把事实、偏好、事件写入长期记忆recall用自然语言检索记忆为个性化回复提供上下文reflect基于已存储记忆与记忆库个性生成综合性的思考分析create_mental_model创建会自动随新记忆刷新的心理模型预计算的反思文档管理文档、指令directives、异步操作operations、标签与记忆库本身。从源码看MCP 工具逻辑集中在共享模块 mcp_tools.py同一套实现被两条传输路径复用mcp_local.pystdio 传输供 Claude Code 本地使用与 api/mcp.pyHTTP 传输供 API 服务器挂载。这意味着无论通过哪种方式接入工具语义完全一致。访问默认启用挂载在 /mcpMCP Server默认开启挂载在 API 服务器的/mcp路径上每个记忆库memory bank拥有独立的 MCP 端点http://localhost:8888/mcp/{bank_id}/例如连接记忆库alicehttp://localhost:8888/mcp/alice/对应的源码依据config.py 中DEFAULT_MCP_ENABLED True第 1454 行默认值由环境变量HINDSIGHT_API_MCP_ENABLED控制server.py 在创建应用时传入mcp_api_enabledconfig.mcp_enabled与mcp_mount_path/mcp将 MCP 中间件挂到主应用上。需要关闭时设置环境变量export HINDSIGHT_API_MCP_ENABLEDfalse除此之外仓库还提供几个与服务行为相关的环境变量见 config.py 第 649-653 行环境变量默认值说明HINDSIGHT_API_MCP_ENABLEDtrue是否启用 MCP 服务器HINDSIGHT_API_MCP_ENABLED_TOOLS未设置全部工具全局工具白名单逗号分隔例如retain,recallHINDSIGHT_API_MCP_STATELESSfalsefalse为有状态支持 SSE/GETtrue为无状态仅 POSTHINDSIGHT_API_MCP_INSTRUCTIONS未设置附加指令文本会自动拼接到 retain/recall 工具描述末尾HINDSIGHT_API_MCP_AUTH_TOKEN未设置传统静态令牌认证向后兼容见下文认证认证从完全开放到API Key 校验默认行为开放默认情况下MCP 端点不要求认证直接可用。这在本地开发与内网部署时非常方便对应源码中的DefaultTenantExtension见 extensions/builtin/tenant.py其authenticate()直接返回配置的 schema不校验任何凭据。启用认证ApiKeyTenantExtension要开启认证配置 API Key 租户扩展export HINDSIGHT_API_TENANT_EXTENSIONhindsight_api.extensions.builtin.tenant:ApiKeyTenantExtension export HINDSIGHT_API_TENANT_API_KEYyour-secret-key启用后请求必须在Authorization头中携带 API Key。若 Key 缺失或无效请求将收到401 Unauthorized响应。该扩展还有两个可选配置见ApiKeyTenantExtension源码注释HINDSIGHT_API_DATABASE_SCHEMA认证通过后使用的 PostgreSQL schema默认publicHINDSIGHT_API_TENANT_MCP_AUTH_DISABLEDtrue为兼容旧版 MCP 服务器而单独关闭 MCP 端点的认证HTTP API 仍校验。两种认证机制的优先级在 api/mcp.py 的MCPMiddleware中认证顺序是若设置了HINDSIGHT_API_MCP_AUTH_TOKEN传统模式先校验该静态令牌校验通过则标记为预认证跳过租户扩展的再次校验否则调用TenantExtension.authenticate_mcp()进行认证。从源码看认证结果不仅用于放行/拒绝还会通过RequestContext把tenant_id、api_key_id等传递下去用于用量计量usage metering与租户 schema 隔离。三种客户端配置示例Claude Code命令行方式claude mcp add --transport http hindsight http://localhost:8888/mcp \ --header Authorization: Bearer your-secret-key \ --header X-Bank-Id: my-bankClaude Desktop配置文件方式编辑~/.claude_desktop_config.json{ mcpServers: { hindsight: { url: http://localhost:8888/mcp, headers: { Authorization: Bearer your-secret-key, X-Bank-Id: my-bank } } } }直接 HTTP 请求curl 验证curl -X POST http://localhost:8888/mcp \ -H Authorization: Bearer your-secret-key \ -H X-Bank-Id: my-bank \ -H Content-Type: application/json \ -H Accept: application/json, text/event-stream \ -d {jsonrpc: 2.0, method: tools/list, id: 1}小贴士MCPMiddleware还会主动为请求补上Accept: application/json, text/event-stream头兼容部分不发 Accept 的客户端如某些 Claude Code 版本避免 406 错误对于无会话 ID 的 GET 探测请求则直接返回 200 OK 以便客户端继续发起initialize。记忆库选择Bank Selection连接时使用哪个记忆库按以下优先级解析URL 路径优先级最高http://localhost:8888/mcp/my-bank/X-Bank-Id 请求头--header X-Bank-Id: my-bank默认值使用HINDSIGHT_MCP_BANK_ID环境变量默认default这一逻辑对应 api/mcp.py 中的实现先从 URL path 提取第一段作为 bank_id并标记为路径来源取不到再读X-Bank-Id头最后回落到模块级常量DEFAULT_BANK_ID os.environ.get(HINDSIGHT_MCP_BANK_ID, default)。关键细节bank_id 的解析来源决定了运行模式。从路径解析到 bank_id 时走单库模式通过 header 或环境变量解析时走多库模式见下文。按库端点Per-Bank Endpoints与隔离设计与传统 MCP 服务器所有工具都要求显式传标识符不同Hindsight 采用按库端点设计bank_id属于 URL 路径的一部分工具无需也无法指定操作哪个库——连接本身就已隐含目标。这种设计带来的三个直接好处简化工具调用——每次调用都不必再传bank_id参数强制隔离——每条 MCP 连接只作用于一个记忆库防止越权访问支持多租户——把不同用户连接到不同端点即可天然完成数据隔离。从源码结构看这一设计贯彻到工具注册层MCPToolsConfig.include_bank_id_param决定工具是否带bank_id参数mcp_tools.py 第 270 行。单库模式下include_bank_id_paramFalse工具通过bank_id_resolver从当前连接上下文解析库多库模式下每个工具额外暴露可选的bank_id参数实现跨库操作。两种模式单库Single-bank与多库Multi-bankMCP 服务器根据 URL 结构在两种模式下运行模式URL工具bank_id单库模式/mcp/{bank_id}/27 个工具记忆、心理模型、指令、文档、操作、标签、库管理隐含于 URL多库模式/mcp/全部 30 个工具含list_banks、create_bank、get_bank_stats每个工具显式传bank_id参数单库模式推荐所有操作都被限定在 URL 指定的记忆库内工具不暴露bank_id参数。源码中_SINGLE_BANK_TOOLS明确排除了三个库管理工具list_banks、create_bank、get_bank_stats从根上杜绝了跨库操作的可能。多库模式暴露全部工具并附带可选的bank_id参数同时提供库管理工具list_banks、create_bank、get_bank_stats适合需要在一个连接里管理多个记忆库的场景例如平台型应用的后台管理。从 test_mcp_endpoint_routing.py 的测试可以看出/mcp/my-bank无尾斜杠同样能路由到单库模式SSE 事件流中的/messages地址也会被改写成/my-bank/messages以保证流式会话正确。可用工具详解以下按功能域逐个介绍工具。所有表格参数均以原文档为准并结合 mcp_tools.py 中的工具注册源码核对。记忆写入类retain把信息存入长期记忆异步。参数类型必填说明contentstring是要存储的事实或记忆contextstring否记忆的分类默认generaltimestampstring否事件发生的 ISO 8601 时间戳tagslist[string]否用于组织与过滤记忆的标签metadataobject否附加的键值元数据如{source: slack}document_idstring否将该记忆关联到已有文档示例{ name: retain, arguments: { content: User prefers Python over JavaScript for backend development, context: programming_preferences, tags: [user:alice, preferences] } }适用场景用户分享个人信息/偏好/兴趣提及重要事件或里程碑陈述决策、观点或目标讨论工作上下文或项目细节。从源码看retain通过memory.submit_async_retain()提交异步任务立即返回operation_id响应包含status: accepted记忆的抽取与落库在后台完成。底层还会做内容分块chunking、实体抽取与后续的记忆巩固consolidation等处理。sync_retain把信息存入长期记忆并等待完成。与异步的retain不同sync_retain会阻塞直到记忆完全存储、立即可被检索——适用于写入后立刻查询的读后写read-after-write流程。参数与retain完全一致content、context、timestamp、tags、metadata、document_id。适用场景存储后需要立即查询该记忆工作流下一步依赖该记忆已可用其余情况优先用异步retain以避免阻塞。记忆检索与反思类recall搜索记忆以提供个性化回复。参数类型必填说明querystring是自然语言搜索查询max_tokensinteger否返回结果的最大 token 数默认 4096budgetstring否搜索深度low、mid或high默认hightypeslist[string]否按事实类型过滤world、experience、observation默认全部tagslist[string]否按标签过滤记忆tags_matchstring否标签匹配模式any默认或allquery_timestampstring否ISO 8601 时间戳——以该时间点进行回忆用于锚定相对时间表达与近因打分示例{ name: recall, arguments: { query: What are the users programming language preferences?, tags: [preferences], budget: high } }适用场景对话开始时回忆相关上下文做推荐之前用户询问可能提到过的事情跨会话保持连续性。recall是 MCP 工具中标注了readOnlyHint的只读工具见 mcp_tools.py 中_READ_ONLY_TOOLS集合客户端可以据此对安全读取做自动放行。reflect通过综合已存储记忆与记忆库的个性生成有深度的分析。参数类型必填说明querystring是要反思的问题或主题contextstring否关于为何需要本次反思的上下文budgetstring否搜索预算low、mid或high默认lowmax_tokensinteger否响应的最大 token 数默认 4096response_schemaobject否结构化输出的 JSON Schema。提供时响应会包含structured_output字段tagslist[string]否反思前按标签过滤记忆tags_matchstring否标签匹配模式any默认或all示例{ name: reflect, arguments: { query: Based on my past decisions, what architectural style do I prefer?, budget: mid, tags: [architecture] } }适用场景需要推理分析而非单纯事实检索回答我该怎么做而非我说过什么跨多条记忆归纳模式。心理模型类Mental Models心理模型是会随着记忆自动更新的预计算反思文档是 Hindsight 记忆体系的一大特色。create_mental_model创建一个心理模型异步生成内容。参数类型必填说明namestring是心理模型的可读名称source_querystring是用于生成与刷新模型的查询mental_model_idstring否自定义 ID小写字母数字加连字符缺省自动生成tagslist[string]否用于组织与过滤模型的标签max_tokensinteger否模型内容的最大 token 数默认 2048trigger_refresh_after_consolidationboolean否记忆巩固后自动刷新该模型默认false示例{ name: create_mental_model, arguments: { name: Team Directory, source_query: Who works here and what do they do?, tags: [team, people] } }内容生成异步执行响应包含operation_id用于跟踪进度。在仓库较新版本中刷新策略已被扩展为完整的MentalModelTriggerInput支持refresh_cron定时刷新、min_refresh_interval_seconds最小刷新间隔、fact_types事实类型过滤、exclude_mental_model_ids排除兄弟模型等字段MCP 层保留trigger_refresh_after_consolidation作为旧版简写参数两者并存且互不冲突见 mcp_tools.py 中MentalModelTriggerInput与_mental_model_trigger_patch。list_mental_models列出记忆库中全部心理模型可按标签过滤。参数类型必填说明tagslist[string]否按标签过滤模型get_mental_model按 ID 获取指定心理模型含完整内容。参数类型必填说明mental_model_idstring是要获取的心理模型 IDupdate_mental_model更新心理模型的元数据或设置。参数类型必填说明mental_model_idstring是要更新的心理模型 IDnamestring否新名称source_querystring否新的源查询tagslist[string]否新标签max_tokensinteger否新的最大 token 数trigger_refresh_after_consolidationboolean否巩固后是否自动刷新。仅在需要修改此设置时传入delete_mental_model永久删除一个心理模型。参数类型必填说明mental_model_idstring是要删除的心理模型 IDrefresh_mental_model用最新记忆重新生成心理模型内容异步执行。参数类型必填说明mental_model_idstring是要刷新的心理模型 IDclear_mental_model清空心理模型内容但保留其定义。清空后调用refresh_mental_model可从最新记忆重建。参数类型必填说明mental_model_idstring是要清空的心理模型 ID记忆库管理类仅多库模式list_banks仅多库模式列出所有可用的记忆库。create_bank仅多库模式创建新记忆库或获取已存在的库。参数类型必填说明bank_idstring是新记忆库的 IDnamestring否记忆库的人类友好名称missionstring否描述这个 agent 是谁、想达成什么的使命说明get_bank_stats仅多库模式获取记忆库的统计信息节点/链接数量。指令类Directives指令是指导记忆系统如何处理与响应用户查询的规则。list_directives列出记忆库中的全部指令。参数类型必填说明tagslist[string]否按标签过滤指令active_onlyboolean否只返回激活中的指令默认truecreate_directive在记忆库中创建一条新指令。参数类型必填说明namestring是指令的可读名称contentstring是指令内容/说明priorityinteger否优先级数值越大越重要is_activeboolean否指令是否激活默认truetagslist[string]否用于组织指令的标签delete_directive按 ID 删除指令。参数类型必填说明directive_idstring是要删除的指令 ID记忆浏览类list_memories浏览已存储的记忆支持过滤与分页。参数类型必填说明typestring否按事实类型过滤world、experience或observationqstring否过滤记忆的搜索查询limitinteger否最大结果数默认 100offsetinteger否分页跳过的结果数默认 0get_memory按 ID 获取指定记忆。参数类型必填说明memory_idstring是要获取的记忆 ID文档类list_documents列出已摄入记忆库的文档。参数类型必填说明qstring否过滤文档的搜索查询limitinteger否最大结果数默认 100get_document按 ID 获取指定文档含其元数据。参数类型必填说明document_idstring是要获取的文档 IDdelete_document删除文档及其关联的全部记忆。参数类型必填说明document_idstring是要删除的文档 ID异步操作类list_operations列出异步操作retain 处理、心理模型刷新等可按状态过滤。参数类型必填说明statusstring否按状态过滤pending、running、completed、failed、cancelledlimitinteger否最大结果数默认 100get_operation获取异步操作的状态与详情。参数类型必填说明operation_idstring是要检查的操作 IDcancel_operation取消一个 pending 或 running 的异步操作。参数类型必填说明operation_idstring是要取消的操作 ID标签与记忆库配置类list_tags列出记忆库中全部唯一标签可按模式过滤。参数类型必填说明qstring否过滤标签的 Glob 模式如project:*limitinteger否最大结果数默认 100get_bank获取记忆库信息包括名称、使命与 disposition倾向配置。update_bank更新记忆库配置。只更新提供的字段未提供的字段保持不变。参数类型必填说明namestring否记忆库的人类友好显示名称missionstring否已弃用——config_updates.reflect_mission的别名config_updatesobject否要更新的配置字段字典支持所有库级可配置字段。不可配置字段与凭据字段会被拒绝config_updates对象按 Python 字段名接受任何库级可配置字段包括reflect_mission— Reflect 操作的使命/上下文retain_mission— 引导retain()抽取什么内容retain_extraction_mode—concise默认、verbose或customretain_custom_instructions— 自定义抽取提示词模式为custom时生效retain_chunk_size— 每个内容块的最大 token 数retain_chunk_batch_size— 并行处理的分块数enable_observations— 是否在retain()后开启观察observation巩固observations_mission— 控制观察综合规则disposition_skepticism— 批判性评估等级1–5disposition_literalism— 字面 vs 抽象解读1–5disposition_empathy— 情感上下文考量1–5entity_labels— 实体分类的受控词表entities_allow_free_form— 是否允许entity_labels之外的标签recall_include_chunks— 召回结果中是否包含原始分块recall_max_tokens— 召回结果的最大 token 数mcp_enabled_tokens— 该记忆库的工具白名单即mcp_enabled_tools注意mcp_enabled_tools既支持在update_bank中按库设置也支持全局环境变量HINDSIGHT_API_MCP_ENABLED_TOOLS。按库的过滤逻辑实现在 mcp_tools.py 的_apply_bank_tool_filtering它会同时作用于tools/list与工具实际调用两层且操作校验器OperationValidator只能进一步收窄、不能突破库配置的上限。delete_bank永久删除一个记忆库及其全部数据记忆、文档、实体、心理模型。clear_memories清空记忆库中的全部记忆但不删除库本身。可按事实类型只清理特定种类的记忆。参数类型必填说明typestring否要清理的事实类型world、experience或observation。不指定则清空全部与 AI 助手的集成MCP Server 可与任何 MCP 兼容的 AI 助手配合使用。Claude Code 与 Claude Desktop 的配置示例见上文认证章节。每个用户都可以拥有自己的配置指向各自的个人记忆库两种方式任选其一库专属 URL 路径推荐如/mcp/alice/X-Bank-Id请求头。配合单库模式每个用户 / 每个 agent 独占一个端点天然形成数据隔离是典型的多用户记忆方案的落地形态。源码级实现解析值得了解的四个工程细节1. 工具注册与双形态返回每个 MCP 工具都被注册两次多库形态带显式bank_id参数返回 JSON 文本与单库形态从会话解析库返回 dict。两者共享同一个引擎调用只是包裹逻辑不同见 mcp_tools.py 的_run_tool。这种双形态刻意保留带bank_id的变体声明返回- str调用方会json.loads因此不能擅自统一返回类型。2. 对 LLM 的容错处理_make_tools_tolerantapi/mcp.py为所有工具做了两层加固剥离未知参数LLM 常会给工具调用附加explanation、reasoning等多余字段会被 Pydantic 拒绝这里在验证前直接剔除字符串 JSON 自动转换LLM 常把tags[a,b]这样的数组/字典参数序列化成字符串这里会按参数 schema 自动json.loads还原成原生类型。3. 工具注解与客户端权限提示所有工具都标注了 MCP 的ToolAnnotationsmcp_tools.py 的_tool_annotations只读工具recall、reflect、各类list_*/get_*标readOnlyHintTrue便于客户端分组与自动放行删除/清空类工具delete_bank、clear_memories、delete_*等标destructiveHintTrue触发客户端的高风险确认所有工具openWorldHintFalse——Hindsight 是封闭记忆库不访问开放网络。4. 审计日志_apply_audit_logging为retain、recall、reflect、create_bank、各类delete_*等 20 个工具包裹了审计记录以transportmcp写入审计日志见_AUDITABLE_MCP_TOOLS集合请求参数与响应都会被记录便于追溯谁在何时对记忆做了什么。5. 本地快速启动仓库提供了本地入口 mcp_local.py运行hindsight-local-mcp或uvx hindsight-apilatest hindsight-local-mcp即可在localhost:8888拉起带默认值的 API 服务内嵌 PostgreSQL 数据源pg0://hindsight-mcp随后按上文示例配置 Claude Codeclaude mcp add --transport http hindsight http://localhost:8888/mcp/ # 或锁定到具体库单库模式 claude mcp add --transport http hindsight http://localhost:8888/mcp/default/相关测试用例可在 test_mcp_routing.py全局工具白名单过滤、test_mcp_tool_filtering.py按库工具过滤与 test_mcp_endpoint_routing.py端点路由中找到可作为理解行为边界的参考。总结Hindsight 的 MCP Server 把完整的记忆生命周期——写入retain/sync_retain、检索recall、反思reflect、沉淀mental models、治理directives、documents、operations、bank management——以标准 MCP 工具的形式开放给任意兼容助手。理解单库/多库双模式 按库端点 三级 bank 解析这三个设计要点再配合ApiKeyTenantExtension认证与mcp_enabled_tools白名单即可在生产环境中搭建安全、隔离、可审计的 AI 长期记忆服务。【免费下载链接】hindsightHindsight: Agent Memory That Learns项目地址: https://gitcode.com/GitHub_Trending/hindsight2/hindsight创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考