Hindsight MCP Server 深度解析：每银行隔离端点、双模式路由与 Agent 记忆工具集-北京尧图网络

Hindsight MCP Server 深度解析每银行隔离端点、双模式路由与 Agent 记忆工具集【免费下载链接】hindsightHindsight: Agent Memory That Learns项目地址: https://gitcode.com/GitHub_Trending/hindsight2/hindsightHindsightAgent Memory That Learns在 API 服务器内内置了基于 FastMCP 的 Model Context Protocol 服务器让 AI 助手可以直接通过工具调用完成记忆的写入retain/recall/reflect与管理。本文基于仓库中的官方文档 mcp-server.md 展开并结合 api/mcp.py、mcp_tools.py 等源码完整覆盖端点访问、双模式路由、bank 解析优先级、认证机制、工具注解与全部工具的参数细节帮助你在自己的 Agent 接入中正确配置并高效使用 Hindsight 记忆。一、内置 MCP 服务器挂载方式与关闭开关Hindsight 的 MCP 服务器默认启用并挂载在 API 服务器的/mcp路径下。每个 memory bank 都拥有独立的 MCP 端点http://localhost:8888/mcp/{bank_id}/例如连接名为alice的 memory bankhttp://localhost:8888/mcp/alice/从源码看启用逻辑发生在应用装配阶段api/init.py 中的create_app()接收mcp_api_enabled与mcp_mount_path默认/mcp两个参数调用create_mcp_servers(memorymemory)预创建 multi-bank 与 single-bank 两个 FastMCP 实例再通过app.add_middleware(MCPMiddleware, prefixmcp_mount_path, ...)以包装中间件的形式拦截所有/mcp*请求其余请求透传给内部的 FastAPI REST 应用。注释中特别说明了这样做的原因用中间件而不是 StarletteMount可以避免/mcp无尾斜杠时出现 307 重定向。若要关闭 MCP 服务器设置环境变量即可export HINDSIGHT_API_MCP_ENABLEDfalse该开关在 config.py 中定义ENV_MCP_ENABLED HINDSIGHT_API_MCP_ENABLED且DEFAULT_MCP_ENABLED True解析逻辑为os.getenv(ENV_MCP_ENABLED, str(DEFAULT_MCP_ENABLED)).lower() true——也就是说只要未显式设置为falseMCP 端点就处于开放状态。源码中还能看到两个与端点行为相关的补充配置从源码结构看适用于需要精细化部署的场景HINDSIGHT_API_MCP_ENABLED_TOOLSENV_MCP_ENABLED_TOOLS全局工具白名单逗号分隔默认None表示全部工具启用在 api/mcp.py 的create_mcp_server()中会对工具集合做交集过滤mcp_stateless控制http_app(path/, stateless_httpstateless)是否以无状态 HTTP 模式运行影响会话保持行为。二、两种模式单银行端点与多银行端点文档明确区分了两种运行模式取决于 URL模式URL工具bank_id单银行Single-bank/mcp/{bank_id}/27 个工具memory、mental models、directives、documents、operations、tags、bank 管理由 URL 隐式决定多银行Multi-bank/mcp/全部 30 个工具包含list_banks、create_bank、get_bank_stats每个工具需显式传bank_id参数单银行模式推荐把所有操作限定在 URL 中的那个 bank 内工具不暴露bank_id参数多银行模式暴露所有工具每个工具携带可选bank_id参数并额外提供 bank 管理工具。从源码结构看这一设计在 api/mcp.py 中由两个预先创建的 FastMCP 实例实现create_mcp_server(memory, multi_bankTrue)与create_mcp_server(memory, multi_bankFalse)。单银行模式通过_SINGLE_BANK_TOOLS冻结集合排除 bank 管理工具而MCPToolsConfig中的include_bank_id_parammulti_bank决定工具 schema 是否附带bank_id参数。值得注意的是当前代码库中共享的_ALL_TOOLS注册表见 mcp_tools.py已经比文档所述扩展了更多工具——除文档列出的 30 个之外还包含update_memory、invalidate_memory以及一组知识库knowledge base工具_SINGLE_BANK_TOOLS也随之扩展。文档中的 27/30 计数对应 version-0.8 时点的工具面接入时以你部署版本的tools/list实际返回为准。MCPMiddleware的类注释完整记录了路由决策逻辑路径中带有 bank 段时走单银行应用工具无bank_id参数、作用域受限仅通过 header/环境变量指定 bank 时走多银行应用。源码注释给出的两个典型接入命令是# 单银行模式推荐用于 agent 隔离 claude mcp add --transport http my-agent http://localhost:8888/mcp/my-agent-bank/ \ --header Authorization: Bearer token # 多银行模式跨 bank 操作 claude mcp add --transport http hindsight http://localhost:8888/mcp \ --header X-Bank-Id: my-bank --header Authorization: Bearer token这种每银行端点设计带来的收益文档将其总结为三点这也是 Hindsight 与常见 MCP 记忆服务器的差异所在简化工具调用——无需每次调用都传bank_id强制隔离——每条 MCP 连接被限定在单一 bank 内不同 agent 的记忆互不可见支持多租户——把不同用户连接到不同端点即可天然隔离。在源码层面隔离通过ContextVar落实中间件在请求处理前_current_bank_id.set(bank_id)各工具在 mcp_tools.py 中通过config.bank_id_resolver()即get_current_bank_id读取当前 bank例如target_bank bank_id or config.bank_id_resolver()。请求结束后finally块统一 reset 所有上下文变量避免跨请求串扰。三、Bank 选择优先级当请求未走 URL 路径指定 bank 时memory bank 按以下优先级解析URL 路径最高优先级http://localhost:8888/mcp/my-bank/X-Bank-Id 请求头--header X-Bank-Id: my-bank默认值HINDSIGHT_MCP_BANK_ID环境变量默认defaultapi/mcp.py 中的实现与文档完全一致模块级常量DEFAULT_BANK_ID os.environ.get(HINDSIGHT_MCP_BANK_ID, default)请求处理时先剥离/mcp前缀、再尝试从路径第一段提取 bank提取成功即标记bank_id_from_path True并路由到单银行应用路径未命中时读取X-Bank-Idheader最后回落到DEFAULT_BANK_ID并输出 debug 日志。四、认证默认开放与 API Key 租户扩展默认情况下 MCP 端点是开放的不需要任何认证——适合本地开发。要启用认证配置 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响应。源码中的认证流程MCPMiddleware.__call__分三层遗留 token 模式若设置了mcp_auth_tokenlegacyMCP_AUTH_TOKEN则直接比对Authorization头同时支持Bearer token与裸 token比对失败返回401 Invalid authentication token并置mcp_pre_authenticated标志跳过租户扩展的二次校验租户扩展模式调用tenant_extension.authenticate_mcp(RequestContext(api_keyauth_token, extra_headers...))默认DefaultTenantExtension不做校验本地开发ApiKeyTenantExtension则按环境变量校验抛出AuthenticationError时中间件以401及扩展提供的附加响应头返回错误schema 隔离认证结果若携带schema_name会写入_current_schema上下文使后续数据库查询落在正确的 schema 上——这是多租户数据隔离的一环。此外中间件会把认证得到的tenant_id与api_key_id存入上下文供用量计量usage metering使用operator 通过HINDSIGHT_API_EXTENSION_PASSTHROUGH_HEADERS白名单允许转发的请求头collect_passthrough_headers也会随RequestContext传给扩展。客户端接入示例Claude Codeclaude 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 请求发送一个 MCP JSON-RPCtools/listcurl -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}从源码结构看中间件为真实客户端做了两处兼容性修补值得在排查接入问题时知晓GET 探测处理Claude Code 等较新版本客户端会在POST initialize之前发一个无Mcp-Session-Id的 GET 探测中间件对此直接返回200 OK空响应体避免客户端把服务器判定为失败Accept 头补全部分客户端不发送Accept头会导致 SDK 以406 Not Acceptable拒绝中间件会自动改写为application/json, text/event-streamSSE 端点改写单银行模式下服务端会拦截 SSE 响应体把data: /messages重写为data: /{bank_id}/messages确保客户端后续消息仍路由回带 bank 的端点——且仅改写 SSE 响应避免误伤工具结果中恰好包含该字面量的 JSON。五、工具元数据描述注入与安全注解部署级指令注入HINDSIGHT_API_MCP_INSTRUCTIONSHindsight 支持向retain和recall两个 MCP 工具的描述末尾追加部署方自定义指引。在 API 服务器上设置HINDSIGHT_API_MCP_INSTRUCTIONS即可让客户端看到本地规则例如应使用哪些 tag、哪些记忆应当被保留export HINDSIGHT_API_MCP_INSTRUCTIONSUse project:name tags for project-specific memories.实现见 api/mcp.py 的_build_mcp_tool_descriptions()仅当指令是非空字符串时才把\n\nAdditional instructions: instructions追加到DEFAULT_MCP_RETAIN_DESCRIPTION与DEFAULT_MCP_RECALL_DESCRIPTION定义于 config.py之后。这个技巧让 LLM 在看见工具描述时就学会了你的 tag 约定而不需要额外的 system prompt。工具注解annotations读取工具注解的 MCP 客户端还能获得内置工具的安全提示。mcp_tools.py 中的_tool_annotations()依据两个集合打标签只读操作recall、reflect、list_*、get_*等_READ_ONLY_TOOLS集合成员标记readOnlyHint: true客户端可据此分组并自动批准安全读取删除/清空/失效操作delete_bank、clear_memories、clear_mental_model、delete_mental_model、delete_directive、delete_document、invalidate_memory等_DESTRUCTIVE_TOOLS集合成员标记destructiveHint: trueopenWorldHint恒为false——源码注释明确说明Hindsight 是封闭的记忆存储不访问开放互联网写操作retain、create_*、update_*、refresh_mental_model、cancel_operation等不落 destructive 标签即标记为readOnlyHint: false, destructiveHint: false。六、核心工具详解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] } }适用场景用户分享个人事实、偏好、兴趣提及重要事件或里程碑陈述决定、观点或目标讨论工作背景或项目细节。sync_retain写后立即可读的同步写入与retain异步不同sync_retain会阻塞直到记忆完全落库、立即可被 recall 检索——适合写完马上读的流程。参数表与retain完全相同content/context/timestamp/tags/metadata/document_id。{ name: sync_retain, arguments: { content: User prefers Python over JavaScript for backend development, context: programming_preferences, tags: [user:alice, preferences] } }适用场景需要在写入后立即查询该记忆工作流后续步骤依赖该记忆已可用其余情况优先用异步retain避免阻塞。recall检索记忆用于检索记忆以提供个性化回答。参数类型必填说明querystring是自然语言查询max_tokensinteger否返回的最大 token 数默认 4096budgetstring否检索深度low、mid、high默认hightypeslist[string]否按事实类型过滤world、experience、observation默认全部tagslist[string]否按标签过滤记忆省略即不过滤tags_matchstring否any默认、all、any_strict、all_strict或exact。exact时传tags: []可选择无标签/全局作用域tag_groupslist[object]否复合布尔标签过滤。与tags互斥每个叶子节点有各自的match值query_timestampstring否ISO 8601 时间戳——模拟在该时间点提问为相对时间表达锚定基准并影响近因打分min_scoresobject否各阶段分数下限如{reranker: 0.5}。键semantic/keyword检索级截断、reranker/final排序后。全部包含式且 AND 叠加省略则不过滤。reranker 分数跨查询未校准使用前需自行校准{ name: recall, arguments: { query: What are the users programming language preferences?, tags: [preferences], budget: high } }适用场景会话开始时召回相关上下文给出建议之前用户问及可能提过的事情跨对话保持连续性。reflect基于记忆库人格的深度分析综合存储的记忆与 bank 的人格配置生成思考性分析。参数类型必填说明querystring是需要反思的问题或主题contextstring否说明为何需要此次反思的上下文budgetstring否检索预算low、mid、high默认lowmax_tokensinteger否响应最大 token 数默认 4096response_schemaobject否结构化输出的 JSON Schema提供后响应包含structured_output字段tagslist[string]否限定记忆、observations、mental models 及带标签 directives 的作用域。省略 tag 时记忆检索不过滤但只加载无标签 directivestags_matchstring否any默认、all、any_strict、all_strict或exact。无标签 directives 在任何模式下都保持全局可见include_traceboolean否附带tool_trace与llm_trace调试输出默认false以保持响应精简文档特别提示MCP 工具仅在tags存在时才会转发tags_match。传tags: []配合tags_match: exact可选中空的/全局作用域的原始事实、observations 与 mental modelsdirective 加载同样只选中无标签 directives。{ name: reflect, arguments: { query: Based on my past decisions, what architectural style do I prefer?, budget: mid, tags: [architecture] } }适用场景需要推理分析而非单纯事实检索时我该怎么办这类问题而非我说过什么需要跨多条记忆综合模式时。七、Mental Model心智模型工具族Mental model 是一份活的文档——预计算出的反思内容会随新记忆入库自动刷新。create_mental_model参数类型必填说明namestring是模型的可读名称source_querystring是用于生成和刷新模型的查询mental_model_idstring否自定义 ID小写字母数字加连字符缺省自动生成tagslist[string]否组织与过滤模型用的标签tags_matchstring否刷新时模型标签与记忆的匹配方式any、all、any_strict、all_strict、exact注意下方默认值说明max_tokensinteger否模型内容最大 token 数默认 2048trigger_refresh_after_consolidationboolean否记忆固化consolidation后自动刷新该模型默认false带标签模型默认all_strict的坑当模型有tags但未显式传tags_match时刷新按all_strict匹配——记忆必须携带模型标签中的每一个才会被纳入。如果你的记忆用细粒度单主题标签如[project:status]而模型打了宽泛标签如[projects, mental-model]刷新会过滤掉全部内容结果返回空。此时应显式传tags_match: any与recall、reflect的默认一致{ name: create_mental_model, arguments: { name: Current projects, source_query: Which projects is the user currently working on?, tags: [projects, mental-model], tags_match: any } }常规示例{ name: create_mental_model, arguments: { name: Team Directory, source_query: Who works here and what do they do?, tags: [team, people], tags_match: any } }内容生成是异步的响应包含operation_id供追踪进度。从源码结构看tags_match的缺省语义在 mcp_tools.py 的MentalModelTriggerInput字段描述中得到印证Unset means all_strict for a tagged model and any for an untagged one.该数据模型还附带了refresh_cronUTC 五段 cron 定时刷新、min_refresh_interval_seconds两次自动刷新之间的最小间隔突发 retain 会折叠为一次刷新等触发策略字段与 HTTP 侧的MentalModelTrigger保持字段对等——仓库测试tests/test_mcp_tools.py::test_trigger_input_covers_every_http_trigger_field会拦截两者漂移。其余 mental model 工具list_mental_models列出 bank 内所有心智模型可按tagslist[string]可选过滤。get_mental_model按 ID 检索指定模型mental_model_id必填含完整内容。update_mental_model更新元数据/设置。mental_model_id必填之外name、source_query、tags、max_tokens均可选trigger_refresh_after_consolidationboolean可选仅在需要改变该设置时传。refresh_mental_model基于最新记忆重新生成内容mental_model_id必填异步执行。clear_mental_model清空内容但保留定义mental_model_id必填清空后调用refresh_mental_model从最新记忆重建。delete_mental_model永久删除mental_model_id必填。八、Bank、Directive、Memory、Document、Operation 与 Tag 工具list_banks仅多银行模式列出所有可用 memory bank。create_bank仅多银行模式创建新 bank 或获取已存在的 bank。参数类型必填说明bank_idstring是新 bank 的 IDnamestring否人类友好的名称missionstring否描述 agent 是谁、试图达成什么的使命陈述Directives指令工具list_directives列出 bank 内的 directives。注意这是管理工具不走 reflect 的 directive 隔离行为省略tags会列出所有directive含带标签的。参数类型必填说明tagslist[string]否按any语义过滤。提供时返回无标签/全局 directives 加共享至少一个标签的 directives省略或为空则返回全部active_onlyboolean否只返回 active directives默认truecreate_directive参数类型必填说明namestring是可读名称contentstring是指令内容priorityinteger否优先级数值越高越重要is_activeboolean否是否激活默认truetagslist[string]否执行作用域。空/省略默认全局非空 reflect 必须使用匹配的 tag 作用域delete_directive按directive_id必填删除。Memory 浏览工具list_memories带过滤与分页浏览已存记忆。参数类型必填说明typestring否按事实类型过滤world、experience、observationqstring否过滤记忆的搜索查询limitinteger否最大结果数默认 100offsetinteger否跳过的结果数用于分页默认 0get_memory按memory_id必填检索单条记忆。Document 工具list_documents列出已摄取进 bank 的文档。q搜索过滤可选、limit默认 100。get_document按document_id必填检索文档及其元数据。delete_document删除文档及其关联的所有记忆document_id必填。Operation 工具list_operations列出异步操作retain 处理、mental model 刷新等可按状态过滤。statuspending/running/completed/failed/cancelled可选、limit默认 100。get_operation按operation_id必填查询操作状态与详情。cancel_operation取消 pending 或 running 的操作operation_id必填。list_tags列出 bank 内所有去重标签可按 glob 模式过滤。q如project:*可选、limit默认 100。get_bank获取 bank 信息包括名称、mission 与 disposition。get_bank_stats仅多银行模式获取 bank 统计节点/链接计数。update_bank更新 bank 配置。只更新提供的字段省略的字段保持不变。参数类型必填说明namestring否人类友好的显示名missionstring否已弃用——config_updates.reflect_mission的别名config_updatesobject否要更新的配置字段字典支持所有 bank 可配置字段不可配置或凭据类字段会被拒绝config_updates按 Python 字段名接受任意 bank 可配置字段包括reflect_mission— Reflect 操作的 mission/上下文retain_mission— 引导retain()时提取什么retain_extraction_mode—concise默认、verbose或customretain_custom_instructions— 自定义抽取提示词mode 为custom时生效retain_chunk_size— 每个内容块的目标最大字符数retain_structured_chunk_size— 单条 JSONL 行或对话轮次保持完整的最大字符数retain_chunk_batch_size— 并行处理的块数enable_observations—retain()后的 observation 固化开关observations_mission— 控制 observation 合成规则disposition_skepticism— 批判性评估程度1–5disposition_literalism— 字面 vs 抽象解释1–5disposition_empathy— 情绪语境考量1–5entity_labels— 实体分类受控词表entities_allow_free_form— 允许entity_labels之外的标签recall_include_chunks— recall 结果中附带原始 chunksrecall_max_tokens— recall 结果的最大 token 数mcp_enabled_tools— 该 bank 的工具白名单从源码结构看bank 级mcp_enabled_tools白名单在 mcp_tools.py 的过滤逻辑中同时作用于tools/list的展示与工具调用的拦截未启用的工具在列表里不出现直接调用则会抛出Tool {name} is not enabled for bank {bank_id}。这与部署级的HINDSIGHT_API_MCP_ENABLED_TOOLS环境变量形成两级白名单全局 env 级 ∩ bank 级。delete_bank永久删除 bank 及其全部数据memories、documents、entities、mental models。clear_memories清空 bank 的全部记忆但不删除 bank 本身可按事实类型只清特定种类。typeworld/experience/observation可选不指定则全清。九、工具调用的容错机制源码级补充文档未展开、但对接入稳定性很关键的一点是所有 MCP 工具在注册后都会被_make_tools_tolerant()包装见 api/mcp.py。它针对 LLM 客户端的两种常见越界行为做预处理剥离未知参数——LLM 常向工具调用添加explanation、reasoning等额外字段而 FastMCP 的 Pydantic TypeAdapter 会因Unexpected keyword argument报错包装层会先剔除 schema 之外的键字符串化 JSON 的类型强转——LLM 常把 list/dict 参数序列化为 JSON 字符串如tags[a,b]包装层依据工具 schema 中的 array/object 类型含anyOf/oneOf联合类型自动json.loads还原为原生类型原生类型则原样通过。这使得 Hindsight 的 MCP 端点对参数形态更宽容降低了不同 LLM 接入时的失败率。十、与 AI 助手集成每用户一银行MCP 服务器可用于任何 MCP 兼容的 AI 助手Claude Code 与 Claude Desktop 的配置示例见本文第四节的认证部分。每个用户都可以拥有指向个人 memory bank 的独立配置两种指定方式bank 专属 URL 路径推荐如/mcp/alice/——单银行模式工具自动限定作用域X-Bank-Id请求头——多银行模式下的每请求指定。选择建议固定 agent 对应固定记忆空间时优先用单银行端点URL 即隔离边界工具面也更简洁需要一个连接管理多个记忆空间如管理面 agent时再用/mcp/多银行端点并配合 bank 管理工具。部署在暴露网络上时务必启用ApiKeyTenantExtension认证并利用HINDSIGHT_API_MCP_INSTRUCTIONS把 tag 约定与保留策略注入工具描述让 agent 在首次tools/list时就学会你的记忆组织规范。关键文件索引MCP 端点与中间件实现 hindsight-api-slim/hindsight_api/api/mcp.py工具注册与注解 hindsight-api-slim/hindsight_api/mcp_tools.py应用装配 hindsight-api-slim/hindsight_api/api/init.pyMCP 相关配置常量 hindsight-api-slim/hindsight_api/config.py原始文档 hindsight-docs/versioned_docs/version-0.8/developer/mcp-server.md。【免费下载链接】hindsightHindsight: Agent Memory That Learns项目地址: https://gitcode.com/GitHub_Trending/hindsight2/hindsight创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

Hindsight MCP Server 深度解析：每银行隔离端点、双模式路由与 Agent 记忆工具集

相关推荐

正则表达式精准匹配正数的完整指南

PySide6日志管理实战：用Python logging构建控制台、文件与界面三合一日志体系

OpenClaw+腾讯云：广告营销Agent基础设施搭建与成本优化实战

更多资讯

Envoy Mobile Hello World 示例全解析：Java / Kotlin / Objective-C / Swift 四语言上手指南

PTA天梯赛L3-027：Java与C++的算法复杂度优化实战

从 20GB 重复文件到只剩一份：Czkawka 磁盘清理与重复文件查找实测

LangChain SequentialChain构建智能意图识别系统

Telegraf DiskIO 输入插件完全指南：磁盘 I/O 流量与延迟指标采集

Hindsight MCP Server 深度解析：每银行隔离端点、双模式路由与 Agent 记忆工具集

今日更新

51单片机开环控制磁阻传感器的硬件匹配与代码实现

AI Agent安全操作数据库：SQL注入防御与参数化查询实战

Android逆向实战：还原激励类App签到接口的签名算法

本周精选

AI驱动的自动化专利分析平台技术解析

LeetCode-Go 题解：1252. Cells with Odd Values in a Matrix（奇数值单元格计数）双解法剖析

在线答疑系统Java毕设实战：Spring Boot前后端分离与状态流转

本月热门

基于YOLO的焊缝缺陷检测：从数据标注到工业部署全流程实践

分布式服务的决策记录

创业产品的首版范围

读完文章，想聊聊您的网站？