您的位置：首页 > > 教程攻略 > ai教程 >Hermes Desktop安装Hindsight 完整指南(含踩坑)

Hermes Desktop安装Hindsight 完整指南(含踩坑)

来源:互联网 更新时间:2026-07-26 07:21

一、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               ← 客户端集成

二、前置条件

组件	版本要求	说明
Windows	10/11	本文基于 Windows 环境
Node.js	≥ v18.x	Hindsight 运行依赖
npm	≥ v9.x	通常随 Node.js 安装
Python	3.11+	Hermes Desktop 自带
PostgreSQL	可选	Hindsight 默认使用 SQLite，生产环境建议 PostgreSQL

三、安装 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，无需手动编辑配置文件，这对新手友好很多。

操作步骤：

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

参数	当前值	说明
Mode	Local External	连接已存在的 Hindsight 实例
API key	（空）	Hindsight API 认证密钥
API URL	http://0.0.0.0:8888	Hindsight API 服务地址
Bank ID	hermes	记忆库名称/命名空间
Recall budget	mid	召回预算（low/mid/high）

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

点击右下角「Sa ve」按钮保存配置
重启 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 后都需要验证：

检查工具列表
：在对话界面中应该能看到以下三个工具
- hindsight_retain — 存储信息到长期记忆
- hindsight_recall — 语义搜索历史记忆
- hindsight_reflect — 跨记忆合成推理
测试存储功能
：发送一条消息，检查是否能正常存储到 Hindsight
验证 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 错误

（参数无效）。

排查过程：

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

解决：

方案 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 成功。

排查过程：

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

解决：

修复 embedding 模型（更换为 Qwen/Qwen3-Embedding-0.6B）
重启 hindsight-api 服务
重新触发 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 配置示例

模型名称	source_query	max_tokens	mode	tags
user-profile	用户画像	2048	delta	[user]
hindsight-setup	Hindsight 配置	2048	delta	[config]
tech-stack	技术栈与工具配置	2048	delta	[config, tech-stack]
ops-playbook	操作经验与踩坑记录	2048	delta	[ops, troubleshooting]

八、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 包。

两种方案工具数量对比：

方案	工具数量	来源	备注
npm hindsight-mcp	11 个	npm 包	官方封装，但工具不全
stdio wrapper	32 个	本地 Hindsight API	推荐，功能完整

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 个工具：

分类	工具	说明
核心	retain	存储记忆
	sync_retain	同步存储
	recall	搜索记忆
	reflect	合成推理
记忆库管理	list_banks	列出记忆库
	create_bank	创建记忆库
	get_bank	获取记忆库信息
	get_bank_stats	获取统计信息
	update_bank	更新记忆库
	delete_bank	删除记忆库
	clear_memories	清空记忆
心智模型	list_mental_models	列出心智模型
	get_mental_model	获取心智模型
	create_mental_model	创建心智模型
	update_mental_model	更新心智模型
	delete_mental_model	删除心智模型
	refresh_mental_model	刷新心智模型
	clear_mental_model	清空心智模型
指令	list_directives	列出指令
	create_directive	创建指令
	delete_directive	删除指令
记忆	list_memories	列出记忆
	get_memory	获取记忆
	update_memory	更新记忆
	invalidate_memory	作废记忆
文档	list_documents	列出文档
	get_document	获取文档
	delete_document	删除文档
操作	list_operations	列出操作
	get_operation	获取操作
	cancel_operation	取消操作
标签	list_tags	列出标签

九、开机自启动配置

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 添加到启动文件夹

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

十、验证清单

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+ 字符

十一、故障排查速查表

问题	排查方向	解决
Mental Model content 为空	检查 embedding 模型是否正常工作	换 Qwen/Qwen3-Embedding-0.6B，用 setx 永久设置
422 错误（MCP 工具）	检查 MCP 包名是否正确	用 hindsight-mcp 而非 @hindsight/mcp-server
401/400 错误（SiliconFlow）	检查环境变量是否正确传递	用 setx 永久设置，或 bat 脚本启动
no attribute 'models'	attrs 模块未安装	pip install attrs + setx PATH 永久生效
环境变量不生效	是否用 setx 而非 set	setx 写入注册表永久保存，set 仅当前窗口生效
端口冲突	8888 或 9998 被占用	使用 --port 指定其他端口

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

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

setvssetx对比

命令	作用范围	生效时间	适用场景
set	当前 CMD 窗口	立即	临时测试
setx	系统/用户级别	需重新打开终端	生产环境、永久配置

踩坑实录

错误做法（踩坑）：

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

更新日志

日期	内容
2026-06-28	首次安装 hindsight-api，配置 DeepSeek + SiliconFlow
2026-06-28	发现 Mental Model 刷新失败，开始排查
2026-06-29	确认 embedding 模型兼容性问题，更换为 Qwen/Qwen3-Embedding-0.6B
2026-06-29	所有 Mental Model 刷新成功，tech-stack 4775 字符，ops-playbook 5856 字符
2026-06-29	整理本文档

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

Hermes Desktop安装Hindsight 完整指南(含踩坑)

一、Hindsight 是什么

Hindsight

长期记忆系统

核心能力其实就三招：

hindsight_retain

hindsight_recall

hindsight_reflect

架构上分三层：

二、前置条件

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

3.1 安装 Hindsight 包

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

必须重新打开终端

3.3 启动 hindsight-api

验证启动成功：

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

http://localhost:9998

五、Hermes Desktop 集成配置

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

操作步骤：

验证配置：

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

5.3 验证 Hermes 集成

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

检查工具列表

测试存储功能

验证 Control Plane

六、踩坑记录（重点！）

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

现象：

422 错误

根因：

解决：

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

现象：

20015 错误

排查过程：

模型兼容性问题

解决：

关键参数：

修复验证：

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

现象：

根因分析：

同步路径

异步 Worker 路径

解决：

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

现象：

解决：

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

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

现象：

解决：

永久生效方案（Windows）：

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

现象：

排查过程：

解决：

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

清空并刷新 Mental Model：

注意：

重新打开终端

七、Mental Model 配置最佳实践

7.1 推荐配置参数

关键发现：

delta 模式 + tags 筛选

7.2 四个 Mental Model 配置示例

八、Cherry Studio MCP 配置

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

适用场景

创建 wrapper 脚本：

配置 Cherry Studio mcp.json：

关键参数：

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

8.3 验证 MCP 工具

测试 retain：

九、开机自启动配置

9.1 创建 VBS 启动脚本