企业官网建设流程全解析

Hindsight MCP Server 完全指南：为 AI 助手构建可存储、可检索、可反思的长期记忆接口

【免费下载链接】hindsightHindsight: Agent Memory That Learns项目地址: https://gitcode.com/GitHub_Trending/hindsight2/hindsight

导读

Hindsight 内置了一个符合 Model Context Protocol（MCP）标准的服务器，让任何 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.py（stdio 传输，供 Claude Code 本地使用）与 api/mcp.py（HTTP 传输，供 API 服务器挂载）。这意味着无论通过哪种方式接入，工具语义完全一致。

访问：默认启用，挂载在 /mcp

MCP Server默认开启，挂载在 API 服务器的/mcp路径上，每个记忆库（memory bank）拥有独立的 MCP 端点：

http://localhost:8888/mcp/{bank_id}/

例如连接记忆库alice：

http://localhost:8888/mcp/alice/

对应的源码依据：

• config.py 中DEFAULT_MCP_ENABLED = True（第 1454 行），默认值由环境变量HINDSIGHT_API_MCP_ENABLED控制；
• server.py 在创建应用时传入mcp_api_enabled=config.mcp_enabled与mcp_mount_path="/mcp"，将 MCP 中间件挂到主应用上。

需要关闭时，设置环境变量：

export HINDSIGHT_API_MCP_ENABLED=false

除此之外，仓库还提供几个与服务行为相关的环境变量（见 config.py 第 649-653 行）：

认证：从"完全开放"到"API Key 校验"

默认行为：开放

默认情况下，MCP 端点不要求认证（直接可用）。这在本地开发与内网部署时非常方便，对应源码中的DefaultTenantExtension（见 extensions/builtin/tenant.py），其authenticate()直接返回配置的 schema，不校验任何凭据。

启用认证：ApiKeyTenantExtension

要开启认证，配置 API Key 租户扩展：

export HINDSIGHT_API_TENANT_EXTENSION=hindsight_api.extensions.builtin.tenant:ApiKeyTenantExtension export HINDSIGHT_API_TENANT_API_KEY=your-secret-key

启用后，请求必须在Authorization头中携带 API Key。若 Key 缺失或无效，请求将收到401 Unauthorized响应。

该扩展还有两个可选配置（见ApiKeyTenantExtension源码注释）：

• HINDSIGHT_API_DATABASE_SCHEMA：认证通过后使用的 PostgreSQL schema，默认public；
• HINDSIGHT_API_TENANT_MCP_AUTH_DISABLED=true：为兼容旧版 MCP 服务器而单独关闭 MCP 端点的认证（HTTP API 仍校验）。

两种认证机制的优先级

在 api/mcp.py 的MCPMiddleware中，认证顺序是：

1. 若设置了HINDSIGHT_API_MCP_AUTH_TOKEN（传统模式），先校验该静态令牌，校验通过则标记为"预认证"，跳过租户扩展的再次校验；
2. 否则调用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-bank"

Claude 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）

连接时使用哪个记忆库，按以下优先级解析：

1. URL 路径（优先级最高）：http://localhost:8888/mcp/my-bank/
2. X-Bank-Id 请求头：--header "X-Bank-Id: my-bank"
3. 默认值：使用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_param=False，工具通过bank_id_resolver从当前连接上下文解析库；多库模式下每个工具额外暴露可选的bank_id参数，实现跨库操作。

两种模式：单库（Single-bank）与多库（Multi-bank）

MCP 服务器根据 URL 结构在两种模式下运行：

单库模式（推荐）：所有操作都被限定在 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

把信息存入长期记忆（异步）。

示例：

{ "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

搜索记忆以提供个性化回复。

示例：

{ "name": "recall", "arguments": { "query": "What are the user's programming language preferences?", "tags": ["preferences"], "budget": "high" } }

适用场景：对话开始时回忆相关上下文；做推荐之前；用户询问可能提到过的事情；跨会话保持连续性。

recall是 MCP 工具中标注了readOnlyHint的只读工具（见 mcp_tools.py 中_READ_ONLY_TOOLS集合），客户端可以据此对安全读取做自动放行。

reflect

通过综合已存储记忆与记忆库的"个性"，生成有深度的分析。

示例：

{ "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

创建一个心理模型（异步生成内容）。

示例：

{ "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

列出记忆库中全部心理模型，可按标签过滤。

get_mental_model

按 ID 获取指定心理模型（含完整内容）。

update_mental_model

更新心理模型的元数据或设置。

delete_mental_model

永久删除一个心理模型。

refresh_mental_model

用最新记忆重新生成心理模型内容（异步执行）。

clear_mental_model

清空心理模型内容但保留其定义。清空后调用refresh_mental_model可从最新记忆重建。

记忆库管理类（仅多库模式）

list_banks（仅多库模式）

列出所有可用的记忆库。

create_bank（仅多库模式）

创建新记忆库，或获取已存在的库。

get_bank_stats（仅多库模式）

获取记忆库的统计信息（节点/链接数量）。

指令类（Directives）

指令是指导记忆系统如何处理与响应用户查询的规则。

list_directives

列出记忆库中的全部指令。

create_directive

在记忆库中创建一条新指令。

delete_directive

按 ID 删除指令。

记忆浏览类

list_memories

浏览已存储的记忆，支持过滤与分页。

get_memory

按 ID 获取指定记忆。

文档类

list_documents

列出已摄入记忆库的文档。

get_document

按 ID 获取指定文档（含其元数据）。

delete_document

删除文档及其关联的全部记忆。

异步操作类

list_operations

列出异步操作（retain 处理、心理模型刷新等），可按状态过滤。

get_operation

获取异步操作的状态与详情。

cancel_operation

取消一个 pending 或 running 的异步操作。

标签与记忆库配置类

list_tags

列出记忆库中全部唯一标签，可按模式过滤。

get_bank

获取记忆库信息，包括名称、使命与 disposition（倾向配置）。

update_bank

更新记忆库配置。只更新提供的字段；未提供的字段保持不变。

config_updates对象按 Python 字段名接受任何库级可配置字段，包括：

• reflect_mission— Reflect 操作的使命/上下文
• retain_mission— 引导retain()抽取什么内容
• retain_extraction_mode—concise（默认）、verbose或custom
• retain_custom_instructions— 自定义抽取提示词（模式为custom时生效）
• retain_chunk_size— 每个内容块的最大 token 数
• retain_chunk_batch_size— 并行处理的分块数
• enable_observations— 是否在retain()后开启观察（observation）巩固
• observations_mission— 控制观察综合规则
• disposition_skepticism— 批判性评估等级（1–5）
• disposition_literalism— 字面 vs 抽象解读（1–5）
• disposition_empathy— 情感上下文考量（1–5）
• entity_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

清空记忆库中的全部记忆但不删除库本身。可按事实类型只清理特定种类的记忆。

与 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_tolerant（api/mcp.py）为所有工具做了两层加固：

• 剥离未知参数：LLM 常会给工具调用附加explanation、reasoning等多余字段，会被 Pydantic 拒绝，这里在验证前直接剔除；
• 字符串 JSON 自动转换：LLM 常把tags='["a","b"]'这样的数组/字典参数序列化成字符串，这里会按参数 schema 自动json.loads还原成原生类型。

3. 工具注解与客户端权限提示

所有工具都标注了 MCP 的ToolAnnotations（mcp_tools.py 的_tool_annotations）：

• 只读工具（recall、reflect、各类list_*/get_*）标readOnlyHint=True，便于客户端分组与自动放行；
• 删除/清空类工具（delete_bank、clear_memories、delete_*等）标destructiveHint=True，触发客户端的高风险确认；
• 所有工具openWorldHint=False——Hindsight 是封闭记忆库，不访问开放网络。

4. 审计日志

_apply_audit_logging为retain、recall、reflect、create_bank、各类delete_*等 20 个工具包裹了审计记录，以transport="mcp"写入审计日志（见_AUDITABLE_MCP_TOOLS集合），请求参数与响应都会被记录，便于追溯谁在何时对记忆做了什么。

5. 本地快速启动

仓库提供了本地入口 mcp_local.py，运行hindsight-local-mcp（或uvx hindsight-api@latest hindsight-local-mcp）即可在localhost:8888拉起带默认值的 API 服务（内嵌 PostgreSQL 数据源pg0://hindsight-mcp），随后按上文示例配置 Claude Code：

claude 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