Hermes Desktop 安装 Hindsight 完整指南（含踩坑记录）

本文记录从 0 到 1 在 Hermes Desktop 中安装、配置 Hindsight 长期记忆系统的完整过程，包含所有踩过的坑和解决方案。基于 Windows 10 + Hermes Desktop + Hindsight v0.8.3 环境。

---

一、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，无需手动编辑配置文件。

操作步骤：

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

参数	当前值	说明
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 红色提示，可留空或填写任意值。

7. 点击右下角「Save」按钮保存配置
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-server vs hindsight-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:\Users\gongc\AppData\Local\hermes\venv\Scripts"
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 配置示例

模型名称	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:\Users\gongc\AppData\Local\Programs\Python\Python311\Scripts\hindsight-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 available 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:\Users\gongc\AppData\Roaming\CherryStudio\mcp.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 添加到启动文件夹

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

---

十一、故障排查速查表

问题	排查方向	解决
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 导致重启后失效。

---

十二、相关资源

• [[concepts/Hindsight记忆系统教程]] — Hindsight 基础教程
• [[concepts/Hermes安装Hindsight]] — 早期版本安装指南
• [[entities/用户画像 龚晨]] — 用户画像配置
• Hindsight GitHub: https://github.com/vectorize-io/hindsight
• Hindsight 文档: https://docs.hindsight.ai

---

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

set vs setx 对比

命令	作用范围	生效时间	适用场景
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 错误。