Hermes桌面版安装Hindsight详细完整指南含踩坑经验分享

一、Hindsight 是什么

先来说说 Hindsight 到底是什么。它本质上是一个为 AI Agent 量身打造的长期记忆系统（Long-term Memory），通过知识图谱、实体解析和多策略检索，让 AI 能够跨会话记住东西，不再跟“金鱼”一样聊完就忘。

核心能力其实就三招：

• hindsight_retain：把信息存进长期记忆
• hindsight_recall：用语义搜索历史记忆
• hindsight_reflect：跨记忆做合成推理

架构上分三层：

hindsight-api                ← 后端引擎（数据平面）
    ↓                           http://localhost:8888
hindsight-control-plane      ← Web 管理界面（控制平面）
    ↓                           http://localhost:9998
Hermes Desktop               ← 客户端集成

二、前置条件

三、安装 hindsight-api（后端引擎）

3.1 安装 Hindsight 包

# 全局安装 hindsight-api（推荐）
npm install -g hindsight-api

# 或者本地安装
npm install hindsight-api

3.2 配置环境变量（永久生效）

关键一步：用 setx 命令永久设置，设置后必须重新打开终端才能生效！

这里有个坑得提醒一下：set 命令只在当前 CMD 窗口生效，窗口一关全丢；setx 会写入注册表永久保存。之前用 set 配置完觉得万事大吉，结果重启终端后所有变量丢失，直接糊一脸 401/400 错误。

REM ===== LLM 配置（DeepSeek）=====
setx HINDSIGHT_API_LLM_PROVIDER "deepseek"
setx DEEPSEEK_API_KEY "sk-你的deepseek密钥"
setx HINDSIGHT_API_LLM_MODEL "deepseek-v4-flash"

REM ===== Embedding 配置（SiliconFlow）=====
setx HINDSIGHT_API_EMBEDDINGS_PROVIDER "openai"
setx HINDSIGHT_API_EMBEDDINGS_OPENAI_API_KEY "sk-你的硅基流动密钥"
setx HINDSIGHT_API_EMBEDDINGS_OPENAI_BASE_URL "https://api.siliconflow.cn/v1"
setx HINDSIGHT_API_EMBEDDINGS_OPENAI_MODEL "Qwen/Qwen3-Embedding-0.6B"

REM ===== Reranker 配置（SiliconFlow）=====
setx HINDSIGHT_API_RERANKER_PROVIDER "siliconflow"
setx HINDSIGHT_API_RERANKER_SILICONFLOW_API_KEY "sk-你的硅基流动密钥"
setx HINDSIGHT_API_RERANKER_MODEL "BAAI/bge-reranker-v2-m3"

REM 设置后需重新打开终端

3.3 启动 hindsight-api

# 直接启动（前台）
hindsight-api
# 指定参数启动
hindsight-api --host 0.0.0.0 --port 8888 --log-level info

验证启动成功：

curl http://localhost:8888/health
# 返回: {"status":"healthy","database":"connected"}

四、安装 Control Plane（Web 管理界面）

# 通过 npx 启动（无需全局安装）
npx @vectorize-io/hindsight-control-plane --api-url http://localhost:8888 --port 9998

启动后访问：http://localhost:9998

五、Hermes Desktop 集成配置

5.1 方式一：通过 Hermes Desktop 客户端界面配置（推荐）

Hermes Desktop 支持直接在客户端界面中配置 Hindsight，无需手动编辑配置文件，这对新手友好很多。

操作步骤：

1. 打开 Hermes Desktop 客户端
2. 进入设置页面：点击左下角 ⚙️ 设置图标
3. 找到「记忆提供方」或「Memory Provider」选项卡
4. 选择 Provider：从右上角下拉菜单中选择 Hindsight
5. 展开 Hindsight settings：点击向下的箭头展开配置区域
6. 填写配置参数：

注意：API key 字段在 Local External 模式下通常不需要填写（本地服务无认证），但如果看到 API key not set 红色提示，留空或填任意值都行。

7. 点击右下角「Sa ve」按钮保存配置
8. 重启 Hermes Desktop 使配置生效

配置界面截图参考：

验证配置：

• 重启后，尝试发送一条消息，检查是否能正常存储到 Hindsight
• 访问 http://localhost:9998 查看 Control Plane「记忆」页面是否有新内容

5.2 方式二：手动编辑配置文件（备用）

如果客户端界面配置没生效，或者你习惯手动操作，可以直接编辑配置文件：

memory:
  provider: hindsight
  memory_enabled: true
  user_profile_enabled: true

同时创建 hindsight/config.json：

{
  "mode": "local_external",
  "api_url": "http://0.0.0.0:8888",
  "bank_id": "hermes",
  "recall_budget": "mid"
}

5.3 验证 Hermes 集成

无论通过哪种方式配置，重启 Hermes Desktop 后都需要验证：

1. 检查工具列表：在对话界面中应该能看到以下三个工具

   • hindsight_retain — 存储信息到长期记忆
   • hindsight_recall — 语义搜索历史记忆
   • hindsight_reflect — 跨记忆合成推理

2. 测试存储功能：发送一条消息，检查是否能正常存储到 Hindsight

3. 验证 Control Plane：访问 http://localhost:9998，查看「记忆」页面是否有新内容

六、踩坑记录（重点！）

❌ 坑 1：MCP 包名错误 —@hindsight/mcp-servervshindsight-mcp

现象：
配置 Hindsight MCP 时，需要参数的工具（retain、recall、reflect 等）全部返回 422 错误，因为工具定义中 properties 为空导致无法传参；而 getBankStats 等不需要参数的只读工具却能正常工作。

根因：
用错了 npm 包名 @hindsight/mcp-server，这个包跟 Hindsight 服务端 API 不匹配。

解决：

# 错误的
npm install -g @hindsight/mcp-server

# 正确的
npm install -g hindsight-mcp

正确包信息：

• 包名：hindsight-mcp
• 版本：1.1.3
• 维护者：jeanibarz
• GitHub：hindsight-ai/hindsight-ai

❌ 坑 2：Embedding 模型兼容性问题 — BAAI/bge-large-zh-v1.5 返回 20015 错误

现象：
Mental Model（tech-stack、ops-playbook）刷新失败，content 始终为空。SiliconFlow 的 BAAI/bge-large-zh-v1.5 模型返回 20015 错误（参数无效）。

排查过程：

1. 最初怀疑是 SiliconFlow 账户欠费（余额 -29.30）
2. 实际测试发现：同一 API Key 下，Qwen/Qwen3-Embedding-0.6B 模型完全正常
3. 确认是模型兼容性问题，不是欠费的问题

解决：

方案 A：更换 embedding 模型（永久生效）

setx HINDSIGHT_API_EMBEDDINGS_OPENAI_MODEL "Qwen/Qwen3-Embedding-0.6B"
REM 设置后需重新打开终端

关键参数：

• 维度：1024（与原有数据库兼容，无需迁移数据）
• API 端点：保持 https://api.siliconflow.cn/v1
• Provider：保持 openai

关键教训：之前用 set 临时设置，重启终端后失效导致问题复发，改成 setx 才永久生效。

修复验证：

• tech-stack：成功生成 4775 字符
• ops-playbook：成功生成 5856 字符

❌ 坑 3：DeepSeek-v4-flash 在 structured reflect 路径下返回空内容

现象：
Mental Model 刷新时，user-profile 和 hindsight-setup 成功，但 tech-stack 和 ops-playbook 的 content 为空。

根因分析：

• 成功的模型走同步路径
• 失败的模型走异步 Worker 路径（structured reflect）
• DeepSeek-v4-flash 在 structured reflect 路径下返回空内容（finish_reason=length）
• 而 plain reflect 路径正常工作

解决：

方案 A：更换 reflect LLM 模型（永久生效）

setx HINDSIGHT_API_LLM_MODEL "xopglm52"
REM 或其他支持 structured output 的模型
REM 设置后需重新打开终端

方案 B：分离 LLM 配置（永久生效）

REM retain 继续使用 DeepSeek-v4-flash（简单事实提取）
setx HINDSIGHT_API_LLM_MODEL "deepseek-v4-flash"

REM reflect 换用其他模型（需要 structured output 支持）
setx HINDSIGHT_API_REFLECT_LLM_MODEL "xopglm52"
REM 注意：此配置需 Hindsight v0.8.4+ 支持

关键教训：set 命令只在当前终端会话生效，重启后丢失；setx 才能永久保存到系统环境变量。之前用 set 配置后重启终端导致失效，改用 setx 解决。

❌ 坑 4：环境变量传递问题导致 SiliconFlow Reranker/Embeddings 401/400 错误

现象：
Hindsight API 的 SiliconFlow Reranker 和 Embeddings 因环境变量传递问题导致 401/400 错误，LLM reflect 正常。日常对话和记忆存储不受影响，但 mental model 自动刷新和深度搜索受影响。

解决：

编写专用启动脚本 start-hindsight.bat，确保环境变量正确传递（永久生效）：

@echo off
REM start-hindsight.bat
REM 确保所有环境变量正确设置后启动 hindsight-api
REM 注意：以下变量已通过 setx 永久设置，此处仅为保险起见

set HINDSIGHT_API_LLM_PROVIDER=deepseek
set DEEPSEEK_API_KEY=sk-xxx
set HINDSIGHT_API_LLM_MODEL=deepseek-v4-flash

set HINDSIGHT_API_EMBEDDINGS_PROVIDER=openai
set HINDSIGHT_API_EMBEDDINGS_OPENAI_API_KEY=sk-xxx
set HINDSIGHT_API_EMBEDDINGS_OPENAI_BASE_URL=https://api.siliconflow.cn/v1
set HINDSIGHT_API_EMBEDDINGS_OPENAI_MODEL=Qwen/Qwen3-Embedding-0.6B

set HINDSIGHT_API_RERANKER_PROVIDER=siliconflow
set HINDSIGHT_API_RERANKER_SILICONFLOW_API_KEY=sk-xxx
set HINDSIGHT_API_RERANKER_MODEL=BAAI/bge-reranker-v2-m3

hindsight-api

永久设置环境变量（推荐先用 setx）：

setx HINDSIGHT_API_LLM_PROVIDER "deepseek"
setx DEEPSEEK_API_KEY "sk-xxx"
setx HINDSIGHT_API_LLM_MODEL "deepseek-v4-flash"
setx HINDSIGHT_API_EMBEDDINGS_PROVIDER "openai"
setx HINDSIGHT_API_EMBEDDINGS_OPENAI_API_KEY "sk-xxx"
setx HINDSIGHT_API_EMBEDDINGS_OPENAI_BASE_URL "https://api.siliconflow.cn/v1"
setx HINDSIGHT_API_EMBEDDINGS_OPENAI_MODEL "Qwen/Qwen3-Embedding-0.6B"
setx HINDSIGHT_API_RERANKER_PROVIDER "siliconflow"
setx HINDSIGHT_API_RERANKER_SILICONFLOW_API_KEY "sk-xxx"
setx HINDSIGHT_API_RERANKER_MODEL "BAAI/bge-reranker-v2-m3"
REM 设置后需重新打开终端

关键教训：set 只在当前 CMD 窗口生效，关闭后全部丢失；setx 写入注册表永久保存。之前用 set 配置后新开 CMD 窗口启动 hindsight-api，导致所有变量丢失，出现 401/400 错误。

❌ 坑 5：attrs模块未安装导致no attribute 'models'错误

现象：
Hermes 启动时报错 module has no attribute 'models'。

解决：

# 必须在 Hermes 的 venv 中安装，不能装在系统 Python 中
pip install attrs

# 然后重启 Hermes Desktop

永久生效方案（Windows）：

setx PATH "%PATH%;C:UsersgongcAppDataLocalhermesvenvScripts"
REM 设置后需重新打开终端

设置后需重新打开终端，确保 Hermes 的 venv 在 PATH 中优先。

关键教训：set 只在当前终端生效；setx 才能永久保存到系统环境变量。之前用 set 配置 PATH 后重启终端失效，改用 setx 解决。

❌ 坑 6：Mental Model 刷新异步路径 Bug（Worker 队列问题）

现象：
tech-stack 和 ops-playbook 的 Mental Model 刷新失败，执行 11 次 refresh 全部失败，而 user-profile 和 hindsight-setup 成功。

排查过程：

1. 最初怀疑是 Worker 异步路径存在 bug——任务被 queued 但从未执行或结果未保存
2. 后续确认根因是 SiliconFlow embedding 模型问题（见坑 2）
3. LLM 请求 875 次全部成功，排除 LLM 问题

解决：

1. 修复 embedding 模型（更换为 Qwen/Qwen3-Embedding-0.6B）
2. 重启 hindsight-api 服务
3. 重新触发 Mental Model 刷新

❌ 坑 7：Windows CMD 中 curl 命令操作 Mental Model

清空并刷新 Mental Model：

REM 清空 tech-stack
curl -X PATCH http://localhost:8888/banks/hermes/mental-models/tech-stack -H "Content-Type: application/json" -d "{"content":"","history":[]}"}

REM 清空 ops-playbook
curl -X PATCH http://localhost:8888/banks/hermes/mental-models/ops-playbook -H "Content-Type: application/json" -d "{"content":"","history":[]}"}

REM 触发刷新
curl -X POST http://localhost:8888/banks/hermes/mental-models/tech-stack/refresh
curl -X POST http://localhost:8888/banks/hermes/mental-models/ops-playbook/refresh

注意： setx 设置的环境变量需要重新打开终端才能生效。

七、Mental Model 配置最佳实践

7.1 推荐配置参数

基于踩坑经验，以下配置组合最稳定：

{
  "source_query": "技术栈与工具配置",
  "max_tokens": 2048,
  "mode": "delta",
  "tags": ["config", "tech-stack"]
}

关键发现：

• 所有成功刷新的 Mental Model 都使用了 delta 模式 + tags 筛选
• delta 模式有空内容时自动回退到 full 的 fallback 机制
• max_tokens 2048 比 4096 更稳定

7.2 四个 Mental Model 配置示例

八、Cherry Studio MCP 配置

8.1 方案一：使用 stdio wrapper（推荐，已验证）

适用场景：Cherry Studio 通过 Python 脚本直接连接本地 Hindsight API，无需 npm 包。

创建 wrapper 脚本：

文件：C:UsersgongcAppDataLocalProgramsPythonPython311Scriptshindsight-mcp-stdio.py

#!/usr/bin/env python3
"""
Hindsight MCP stdio wrapper for Cherry Studio
Connects to local Hindsight API via HTTP and exposes MCP tools via stdio
"""
import sys
import json
import requests
API_BASE = "http://localhost:8888"
BANK_ID = "cherry"
def handle_request(req):
    method = req.get("method")
    params = req.get("params", {})
    if method == "tools/list":
        # Return a vailable tools
        return {
            "tools": [
                {
                    "name": "retain",
                    "description": "Store information to long-term memory",
                    "inputSchema": {
                        "type": "object",
                        "properties": {
                            "items": {
                                "type": "array",
                                "items": {
                                    "type": "object",
                                    "properties": {
                                        "content": {"type": "string"},
                                        "context": {"type": "string"},
                                        "tags": {"type": "array", "items": {"type": "string"}}
                                    },
                                    "required": ["content"]
                                }
                            }
                        },
                        "required": ["items"]
                    }
                },
                {
                    "name": "recall",
                    "description": "Search long-term memory",
                    "inputSchema": {
                        "type": "object",
                        "properties": {
                            "query": {"type": "string"},
                            "limit": {"type": "integer", "default": 10}
                        },
                        "required": ["query"]
                    }
                },
                {
                    "name": "reflect",
                    "description": "Synthesize reasoning across memories",
                    "inputSchema": {
                        "type": "object",
                        "properties": {
                            "query": {"type": "string"},
                            "budget": {"type": "string", "default": "mid"}
                        },
                        "required": ["query"]
                    }
                },
                {
                    "name": "getBankStats",
                    "description": "Get memory bank statistics",
                    "inputSchema": {
                        "type": "object",
                        "properties": {}
                    }
                }
            ]
        }
    elif method == "tools/call":
        tool_name = params.get("name")
        arguments = params.get("arguments", {})
        if tool_name == "retain":
            items = arguments.get("items", [])
            response = requests.post(
                f"{API_BASE}/banks/{BANK_ID}/memories",
                json={"items": items}
            )
            return {"content": [{"type": "text", "text": json.dumps(response.json())}]}
        elif tool_name == "recall":
            query = arguments.get("query")
            limit = arguments.get("limit", 10)
            response = requests.post(
                f"{API_BASE}/banks/{BANK_ID}/recall",
                json={"query": query, "limit": limit}
            )
            return {"content": [{"type": "text", "text": json.dumps(response.json())}]}
        elif tool_name == "reflect":
            query = arguments.get("query")
            budget = arguments.get("budget", "mid")
            response = requests.post(
                f"{API_BASE}/banks/{BANK_ID}/reflect",
                json={"query": query, "budget": budget}
            )
            return {"content": [{"type": "text", "text": json.dumps(response.json())}]}
        elif tool_name == "getBankStats":
            response = requests.get(f"{API_BASE}/banks/{BANK_ID}/stats")
            return {"content": [{"type": "text", "text": json.dumps(response.json())}]}
    return {"error": {"code": -32601, "message": "Method not found"}}
def main():
    for line in sys.stdin:
        try:
            req = json.loads(line)
            result = handle_request(req)
            response = {
                "jsonrpc": "2.0",
                "id": req.get("id"),
                "result": result
            }
            print(json.dumps(response), flush=True)
        except Exception as e:
            error_response = {
                "jsonrpc": "2.0",
                "id": req.get("id") if 'req' in locals() else None,
                "error": {"code": -32603, "message": str(e)}
            }
            print(json.dumps(error_response), flush=True)
if __name__ == "__main__":
    main()

配置 Cherry Studio mcp.json：

文件路径：C:UsersgongcAppDataRoamingCherryStudiomcp.json

{
  "mcpServers": {
    "hindsight-cherry": {
      "type": "stdio",
      "command": "python",
      "args": [
        "C:\Users\gongc\AppData\Local\Programs\Python\Python311\Scripts\hindsight-mcp-stdio.py"
      ],
      "env": {
        "HINDSIGHT_API_BASE_URL": "http://localhost:8888",
        "HINDSIGHT_MCP_BANK_ID": "cherry"
      }
    }
  }
}

关键参数：

• HINDSIGHT_API_BASE_URL：Hindsight API 地址
• HINDSIGHT_MCP_BANK_ID：记忆库 ID（与 Hermes 的 bank_id 不同，这里是 cherry）
• command：Python 解释器路径
• args：wrapper 脚本完整路径

8.2 方案二：使用 npm hindsight-mcp 包（备选）

如果 prefer npm 方式：

npm install -g hindsight-mcp

配置：

{
  "mcpServers": {
    "hindsight": {
      "command": "npx",
      "args": ["-y", "hindsight-mcp"],
      "env": {
        "HINDSIGHT_API_BASE_URL": "http://localhost:8888",
        "HINDSIGHT_MCP_BANK_ID": "cherry"
      }
    }
  }
}

注意：npm 包的 hindsight-mcp 只有 11 个工具，而本地 Hindsight API 有 32 个工具。stdio wrapper 方案可直接访问全部 32 个工具，且无需安装 npm 包。

两种方案工具数量对比：

stdio wrapper 优势：

• ✅ 访问全部 32 个工具（npm 包只有 11 个）
• ✅ 无需安装 npm 包，直接用 Python 脚本
• ✅ 与 Hindsight API 版本完全同步
• ✅ 支持心智模型、指令、标签等高级功能
  ![[Pasted image 20260629220757.png]]

8.3 验证 MCP 工具

重启 Cherry Studio 后，应看到以下工具：

• retain — 存储记忆
• syncRetain — 同步存储
• recall — 搜索记忆
• reflect — 合成推理
• getBankStats — 获取统计信息

测试 retain：

{
  "items": [
    {
      "content": "测试 Cherry Studio 到 Hindsight 的记忆存储",
      "context": "MCP 配置测试",
      "tags": ["test", "cherry-studio"]
    }
  ]
}

配置成功后应看到 32 个工具：

九、开机自启动配置

9.1 创建 VBS 启动脚本

' start-hindsight.vbs
' 后台启动 hindsight-api，无 CMD 窗口

Set WshShell = CreateObject("WScript.Shell")
WshShell.Run "cmd /c start-hindsight.bat", 0, False
Set WshShell = Nothing

9.2 添加到启动文件夹

1. 按 Win + R，输入 shell:startup
2. 创建快捷方式，指向 start-hindsight.vbs
3. 重启电脑验证

十、验证清单

10.1 服务状态检查

# 1. hindsight-api 健康检查
curl http://localhost:8888/health

# 2. Control Plane 访问
# 浏览器打开 http://localhost:9998

# 3. MCP 工具列表
curl http://localhost:8888/mcp/default/tools

10.2 Mental Model 状态检查

# 查看所有 mental models
curl http://localhost:8888/banks/hermes/mental-models

# 检查具体内容长度
curl http://localhost:8888/banks/hermes/mental-models/tech-stack

正常状态：

• user-profile：~500 字符
• hindsight-setup：~800 字符
• tech-stack：~4000+ 字符
• ops-playbook：~5000+ 字符

十一、故障排查速查表

核心教训汇总：set = 临时（当前窗口），setx = 永久（写入注册表）。所有环境变量配置统一使用 setx，设置后必须重新打开终端。之前多次踩坑都是因为用了 set 导致重启后失效。

十二、Windows 环境变量终极指南（防坑必备）

setvssetx对比

踩坑实录

错误做法（踩坑）：

set HINDSIGHT_API_LLM_MODEL=deepseek-v4-flash
REM 关闭 CMD 窗口后，变量全部丢失！
REM 新开窗口启动 hindsight-api → 401/400 错误

正确做法（永久生效）：

setx HINDSIGHT_API_LLM_MODEL "deepseek-v4-flash"
REM 关闭当前 CMD，重新打开新窗口
REM 变量永久保存，重启电脑仍然有效

常用 setx 命令模板

REM ===== 一次性设置所有 Hindsight 变量 =====
setx HINDSIGHT_API_LLM_PROVIDER "deepseek"
setx DEEPSEEK_API_KEY "sk-xxx"
setx HINDSIGHT_API_LLM_MODEL "deepseek-v4-flash"

setx HINDSIGHT_API_EMBEDDINGS_PROVIDER "openai"
setx HINDSIGHT_API_EMBEDDINGS_OPENAI_API_KEY "sk-xxx"
setx HINDSIGHT_API_EMBEDDINGS_OPENAI_BASE_URL "https://api.siliconflow.cn/v1"
setx HINDSIGHT_API_EMBEDDINGS_OPENAI_MODEL "Qwen/Qwen3-Embedding-0.6B"

setx HINDSIGHT_API_RERANKER_PROVIDER "siliconflow"
setx HINDSIGHT_API_RERANKER_SILICONFLOW_API_KEY "sk-xxx"
setx HINDSIGHT_API_RERANKER_MODEL "BAAI/bge-reranker-v2-m3"

REM 设置后必须重新打开 CMD 窗口

验证环境变量

REM 查看单个变量
echo %HINDSIGHT_API_LLM_MODEL%

REM 查看所有 Hindsight 变量
set HINDSIGHT

REM 验证是否生效
curl http://localhost:8888/health

更新日志

经验教训： 不要轻信错误代码表面含义——Hindsight 中错误代码 20015 报告"参数无效"，但实际根因是 embedding 失败导致的模型兼容性问题。遇到 embedding 失败时先测试同一平台其他模型；更换 embedding 模型时需确保维度兼容（1024 维），否则需要迁移数据库。另外，所有环境变量配置必须使用 setx 而非 set，之前多次踩坑都是因为用了 set 导致重启后变量丢失，出现 401/400 错误。