MCP 集成

将 Hindsight 连接到任何兼容 MCP 的 AI 客户端——Claude Desktop、Claude Code、ChatGPT、Cursor、Windsurf、VS Code 或你自己的客户端。

什么是 MCP？

Model Context Protocol（MCP，模型上下文协议）是一个开放标准，允许 AI 应用通过 HTTP 连接到外部工具。Hindsight 将其记忆操作以 MCP 工具的形式对外暴露，因此任何兼容 MCP 的客户端都可以使用你的记忆库执行 retain、recall 和 reflect。

前置条件

一个 Hindsight Cloud 账户（参见快速开始）
一个兼容 MCP 的客户端

认证

Hindsight 为 MCP 连接支持两种认证方式：

OAuth（推荐）

Claude Code、Claude Desktop、ChatGPT、Cursor 和 Windsurf 都支持 OAuth 认证。使用 OAuth：

从 Connect 页面复制配置——无需 API 密钥
客户端连接时，会打开浏览器让你登录 Hindsight Cloud
客户端会自动接收令牌——无需管理或轮换密钥

OAuth 使用带 PKCE 的 MCP 授权规范（RFC 9728）进行安全认证。

API 密钥

对于不支持 OAuth 的客户端（如 VS Code），或作为备用方案：

在 Connect 页面创建一个 API 密钥
该密钥作为 Bearer 令牌嵌入到你的配置中

你可以在 Connect 页面通过认证模式切换在 OAuth 与 API 密钥认证之间切换。

快速设置

Claude Code（OAuth — 推荐）

最快上手方式：

claude mcp add --transport http hindsight \
  https://api.hindsight.vectorize.io/mcp/YOUR_BANK/

然后在 Claude Code 中输入 /mcp 进行连接。浏览器窗口会打开，让你登录 Hindsight Cloud。登录后即可使用记忆工具。无需 API 密钥。

其他客户端

在 Hindsight Cloud 中前往 Connect 选项卡
选择你的 MCP 客户端
选择认证模式（对于支持的客户端推荐使用 OAuth）
复制生成的配置
将其粘贴到客户端的配置文件中
重启客户端——对于 OAuth 客户端，首次连接时会打开浏览器登录

连接模式

Hindsight 支持两种 MCP 连接模式。Connect 页面默认生成 单库（single-bank） 配置。

单库模式（推荐）

你的代理通过 URL 路径连接到一个特定的记忆库：

https://api.hindsight.vectorize.io/mcp/{bank_id}/

代理被限定在该记忆库——所有操作（retain、recall、reflect）都会自动使用它
不需要 X-Bank-Id 标头
可用 27 个工具（记忆操作、心智模型、指令、文档、操作、标签、记忆库管理 + search_docs）
适用于：专用代理、项目专属记忆、团队隔离

多库模式

你的代理连接到根 MCP 端点，并通过标头指定记忆库：

https://api.hindsight.vectorize.io/mcp

带标头：X-Bank-Id: {bank_id}

暴露 30 个工具（增加了 list_banks、create_bank 和 get_bank_stats）
每个限定于记忆库的工具都包含一个可选的 bank_id 参数，因此代理可以在单次会话中跨多个记忆库操作
X-Bank-Id 标头设置默认记忆库——如果工具调用省略了 bank_id，则使用此默认值
如果省略 X-Bank-Id 标头，则默认记忆库为 "default"
适用于：跨库工作流、需要管理或查询多个记忆库的代理

默认记忆库行为

在多库模式下，如果你不设置 X-Bank-Id 标头，所有操作都会默认指向一个名为 "default" 的记忆库。该库会在首次使用时自动创建。如果你之后切换到其他记忆库，之前存入默认库的记忆仍会留在那里——查询新库时不会出现这些记忆。

为避免混乱，请始终将 X-Bank-Id 设置为一个有意义的名称，或使用在 URL 中明确指定记忆库的单库模式。

客户端配置

以下示例使用 单库模式。请将 YOUR_BANK 替换为你的记忆库名称。

对于 OAuth 客户端，无需 API 密钥——客户端会通过浏览器登录处理认证。对于使用 API 密钥的客户端，请将 YOUR_API_KEY 替换为 Connect 页面中的密钥。

OAuth（推荐）

claude mcp add --transport http hindsight \
  https://api.hindsight.vectorize.io/mcp/YOUR_BANK/

然后在 Claude Code 中输入 /mcp 进行连接。浏览器窗口会打开让你登录 Hindsight Cloud。登录后即可使用记忆工具——无需 API 密钥。

API 密钥（备用）

claude mcp add --transport http hindsight \
  https://api.hindsight.vectorize.io/mcp/YOUR_BANK/ \
  --header "Authorization: Bearer YOUR_API_KEY"

或添加到 .mcp.json（项目级）或 ~/.claude.json（用户级）：

{
  "mcpServers": {
    "hindsight": {
      "type": "http",
      "url": "https://api.hindsight.vectorize.io/mcp/YOUR_BANK/",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

OAuth（推荐）— Connectors UI

打开 Claude Desktop
前往 Settings → Connectors → Add custom connector

输入此 URL：

https://api.hindsight.vectorize.io/mcp/YOUR_BANK/

点击 Connect — 浏览器会打开让你登录 Hindsight Cloud

无需 API 密钥、Node.js 或配置文件。需要 HTTPS。

备注

Connectors 是官方支持的方式将 Claude Desktop 连接到远程 MCP 服务器。直接在 claude_desktop_config.json 中配置的远程服务器无法原生连接。

变通方案：通过 JSON 配置使用 mcp-remote

如果 Connectors 不适用于你的环境，可以使用 mcp-remote（一个社区工具）将 stdio 桥接到 HTTP。将以下内容添加到 ~/Library/Application Support/Claude/claude_desktop_config.json（macOS）或 %APPDATA%\Claude\claude_desktop_config.json（Windows）：

{
  "mcpServers": {
    "hindsight": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://api.hindsight.vectorize.io/mcp/YOUR_BANK/"
      ]
    }
  }
}

需要 Node.js。Claude Desktop 启动时，mcp-remote 会打开浏览器让你登录。这是社区变通方案，并未由 Anthropic 官方记录。

API 密钥（备用）

{
  "mcpServers": {
    "hindsight": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://api.hindsight.vectorize.io/mcp/YOUR_BANK/",
        "--header",
        "Authorization:${HINDSIGHT_API_KEY}"
      ],
      "env": {
        "HINDSIGHT_API_KEY": "Bearer YOUR_API_KEY"
      }
    }
  }
}

需要 Node.js。env 块将认证令牌排除在参数之外，以避免一个已知的 Windows 问题，即参数中的空格会被 cmd.exe 破坏。

OAuth（推荐）

添加到 .cursor/mcp.json（项目级）或 ~/.cursor/mcp.json（全局）：

{
  "mcpServers": {
    "hindsight": {
      "type": "http",
      "url": "https://api.hindsight.vectorize.io/mcp/YOUR_BANK/"
    }
  }
}

Cursor 连接时会打开浏览器让你登录。

API 密钥（备用）

{
  "mcpServers": {
    "hindsight": {
      "type": "http",
      "url": "https://api.hindsight.vectorize.io/mcp/YOUR_BANK/",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

OAuth（推荐）

添加到 ~/.codeium/windsurf/mcp_config.json：

{
  "mcpServers": {
    "hindsight": {
      "serverUrl": "https://api.hindsight.vectorize.io/mcp/YOUR_BANK/"
    }
  }
}

Windsurf 连接时会打开浏览器让你登录。

备注

Windsurf 使用 serverUrl 而不是 url。

API 密钥（备用）

{
  "mcpServers": {
    "hindsight": {
      "serverUrl": "https://api.hindsight.vectorize.io/mcp/YOUR_BANK/",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

添加到 .vscode/mcp.json：

{
  "servers": {
    "hindsight": {
      "type": "http",
      "url": "https://api.hindsight.vectorize.io/mcp/YOUR_BANK/",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

备注

VS Code 使用 servers 而不是 mcpServers。VS Code 目前不支持 MCP 的 OAuth，因此必须使用 API 密钥。

OAuth（必需）

启用开发者模式：Settings → Apps & Connectors → Advanced settings
创建 Connector：Settings → Connectors → Create

输入名称（例如 "Hindsight"）和此 URL：

https://api.hindsight.vectorize.io/mcp/YOUR_BANK/

点击 Create — 浏览器会打开让你登录 Hindsight Cloud
在聊天中使用：在消息编辑器中点击 + → More → 选择 Hindsight

备注

ChatGPT 仅支持 OAuth 进行 MCP 连接——不支持 API 密钥认证。需要 HTTPS。

查看 ChatGPT 文档

OAuth — 需要 Perplexity Pro

前往 Settings → Connectors → + Custom Connector
输入：
- Name：Hindsight（或你的偏好名称）
- MCP server URL：
```
https://api.hindsight.vectorize.io/mcp/YOUR_BANK/
```
点击 Add — 浏览器会打开让你登录 Hindsight Cloud
登录后，Hindsight 工具即可使用

就是这么简单。OAuth 自动发现机制会自动处理认证。

备注

需要 Perplexity Pro。远程 MCP 连接器是 Pro 功能。

配置你的 AI 工具以使用 Hindsight

连接器现已激活，但你需要告诉 ChatGPT 和 Perplexity 实际使用它们。在每个平台上添加自定义指令，以启用自动记忆捕获和召回。

ChatGPT 自定义指令

前往 Settings → Personalization → Custom instructions
复制并粘贴以下指令：

After every response, automatically use the Hindsight tool to retain key information from our conversation:
- Important facts, decisions, or learnings we discussed
- Your preferences, goals, or constraints mentioned
- Code patterns, architecture decisions, or technical insights
- Any information that might be useful in future conversations

Before generating each response, automatically use the Hindsight tool to recall relevant memories that might apply to the current conversation. Include recalled memories in your reasoning.

Retain and recall aggressively—assume everything is valuable. The Hindsight tool will handle deduplication and relevance filtering.

保存并关闭设置

从现在起，ChatGPT 会自动存储对话中的洞察，并在无需你额外要求的情况下浮现相关记忆。

Perplexity 自定义指令

前往 Settings → Personalization → Custom instructions
复制并粘贴以下指令：

After every search and response, automatically use the Hindsight tool to retain:
- Key research findings and sources
- Facts and data points we've discovered
- Your preferences or research patterns
- Methodologies or search strategies that worked well

Before each new search, automatically use Hindsight to recall relevant research and context from previous conversations. Use recalled memories to inform your search strategy and answer.

Retain and recall everything—Hindsight handles filtering and deduplication.

保存并关闭设置

Perplexity 现在会自动保留研究发现，并在未来的搜索中召回它们，从你的研究中构建持久化知识库。

提示

你可以自由调整指令以确保获得理想的行为。

多库配置

要改用多库模式，请指向 /mcp 并添加 X-Bank-Id 标头：

Claude Code（OAuth）
API 密钥

claude mcp add --transport http hindsight \
  https://api.hindsight.vectorize.io/mcp

除非代理在工具调用中指定 bank_id，否则将使用 "default" 记忆库。

claude mcp add --transport http hindsight \
  https://api.hindsight.vectorize.io/mcp \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --header "X-Bank-Id: YOUR_BANK"

或采用 JSON：

{
  "mcpServers": {
    "hindsight": {
      "type": "http",
      "url": "https://api.hindsight.vectorize.io/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY",
        "X-Bank-Id": "YOUR_BANK"
      }
    }
  }
}

可用工具

单库模式（27 个工具）

核心记忆

工具	说明
`retain`	将信息存储到长期记忆中（支持标签、元数据、文档关联）
`recall`	使用自然语言搜索记忆（可配置预算、按类型/标签过滤、可指定时间范围）
`reflect`	使用你的记忆作为上下文获取 AI 驱动的答案（支持结构化输出）

心智模型

工具	说明
`create_mental_model`	创建一个随你的记忆保持最新的活文档
`list_mental_models`	列出记忆库中所有的心智模型
`get_mental_model`	检索特定心智模型
`update_mental_model`	更新心智模型的名称、查询或设置
`delete_mental_model`	永久删除心智模型
`refresh_mental_model`	基于最新的记忆重新生成心智模型

指令

工具	说明
`list_directives`	列出用于指导记忆处理的指令
`create_directive`	创建新指令
`delete_directive`	删除指令

记忆浏览

工具	说明
`list_memories`	通过过滤和分页浏览记忆
`get_memory`	通过 ID 获取特定记忆
`delete_memory`	删除特定记忆

文档

工具	说明
`list_documents`	列出已摄入的文档
`get_document`	获取特定文档
`delete_document`	删除文档及其关联记忆

操作

工具	说明
`list_operations`	列出异步操作并按状态过滤
`get_operation`	查询操作状态和进度
`cancel_operation`	取消挂起或正在运行的操作

标签与记忆库管理

工具	说明
`list_tags`	列出记忆库中使用的唯一标签
`get_bank`	获取记忆库资料（名称、使命、性格）
`update_bank`	更新记忆库名称或使命
`delete_bank`	删除整个记忆库及其所有数据
`clear_memories`	清空记忆但不删除记忆库

云端

工具	说明
`search_docs`	搜索 Hindsight 文档

多库模式（30 个工具）

包含上述所有单库工具，外加：

工具	说明
`list_banks`	列出你组织中的所有记忆库
`create_bank`	创建新的记忆库
`get_bank_stats`	获取记忆库统计（节点/链接数量）

在多库模式下，每个限定于记忆库的工具还接受可选的 bank_id 参数，以针对特定记忆库执行。

验证连接

向你的 AI 代理询问：

"你有哪些可用的记忆工具？"

它应当列出上面的 Hindsight 工具。如果没有任何工具显示出来，请检查：

你的 API 密钥是否有效且处于活动状态
配置文件语法是否适合你的客户端
你是否在添加配置后重启了客户端

记忆库

记忆库是隔离的存储——每一个都是独立的记忆空间。为不同上下文使用不同的记忆库：

my-project 用于特定项目的上下文
team-knowledge 用于共享团队信息
每个代理一个记忆库以实现代理隔离

首次使用时（当你 retain 到一个新记忆库名称时），记忆库会自动创建。无需提前创建。

要在单库模式下切换记忆库，请更新 MCP 配置中的 URL（例如，将 /mcp/project-a/ 改为 /mcp/project-b/），然后重启客户端。

用量与计费

MCP 操作和 SDK 或 API 调用一样消耗额度：

操作	计费内容
`retain`	输入 Token（存储的内容）
`recall`	查询 + 输出 Token
`reflect`	查询 + 上下文 + 输出 Token
`get_mental_model`	输出 Token（轻量）
`refresh_mental_model`	查询 + 上下文 + 输出 Token

可在使用分析页面查看用量。

故障排查

OAuth 登录页面未打开

确保你使用的是支持 OAuth 的客户端（Claude Code、Claude Desktop、ChatGPT、Cursor、Windsurf）
检查 MCP URL 是否正确且可访问
对于 Claude Desktop，确保已安装 Node.js（npx 必须可用）

"Failed to connect" 或未发现任何工具

OAuth：再次尝试连接——浏览器登录可能已超时
API 密钥：确认 API 密钥未被撤销（查看 Connect 页面）
检查 Authorization 标头使用了 Bearer 前缀（带空格）
URL 中的记忆库名称只应包含字母数字字符、连字符和下划线

工具出现但操作失败

确认你的组织还有可用额度（参见账单）
检查你的记忆库名称是否有效（字母数字和连字符）

retain 之后记忆未出现

记忆处理是异步的。调用 retain 后，事实提取和索引会在后台进行。等几秒后再 recall。

连接后 "0 tools discovered"

这通常意味着认证已悄然失败。再次检查 API 密钥是否正确，且 Authorization 标头已包含。对于 OAuth，尝试移除并重新添加 MCP 服务器以触发新的登录。

什么是 MCP？​

前置条件​

认证​

OAuth（推荐）​

API 密钥​

快速设置​

Claude Code（OAuth — 推荐）​

其他客户端​

连接模式​

单库模式（推荐）​

多库模式​

客户端配置​

配置你的 AI 工具以使用 Hindsight​

ChatGPT 自定义指令​

Perplexity 自定义指令​

多库配置​

可用工具​

单库模式（27 个工具）​

多库模式（30 个工具）​

验证连接​

记忆库​

用量与计费​

故障排查​

OAuth 登录页面未打开​

"Failed to connect" 或未发现任何工具​

工具出现但操作失败​

retain 之后记忆未出现​

连接后 "0 tools discovered"​

什么是 MCP？

前置条件

认证

OAuth（推荐）

API 密钥

快速设置

Claude Code（OAuth — 推荐）

其他客户端

连接模式

单库模式（推荐）

多库模式

客户端配置

配置你的 AI 工具以使用 Hindsight

ChatGPT 自定义指令

Perplexity 自定义指令

多库配置

可用工具

单库模式（27 个工具）

多库模式（30 个工具）

验证连接

记忆库

用量与计费

故障排查

OAuth 登录页面未打开

"Failed to connect" 或未发现任何工具

工具出现但操作失败

retain 之后记忆未出现

连接后 "0 tools discovered"