Hindsight 快速配置

简介

Hindsight 相当于是hermes登AI Agent的第二层记忆（外挂版本）。

官方仓库：https://github.com/vectorize-io/hindsight.git

中文优化版仓库（未测试）：https://github.com/vulnnull/hindsight-cn.git

安装文档：https://hindsight.vectorize.io/developer/installation

架构概览

hermes agent ──HTTP──→ hindsight-api (:8888)

                          │

                          ├── PostgreSQL (pg0 embedded)

                          ├── LLM (fact extraction + consolidation)

                          └── Embedding (BGE-small-en-v1.5, local)

数据目录

PS：数据目录必须是1000普通用户权限，可以使用命令设置目录权限sudo chown -R 1000:1000 /dir 设置目录权限
之后数据即可正常持久化到目录，如果不想每次重建目录都下载模型，可以挂载HF的缓存路径。

非1000普通用户权限目录报错：

❌ The embedded database directory /home/hindsight/.pg0 is not writable by this container (UID 1000).

   A host directory was bind-mounted but is not owned by the container user (UID 1000).
   Hindsight runs rootless and cannot fix this for you. Choose one:

   • Recommended — use a Docker named volume (auto-owned by the container):
       -v hindsight-data:/home/hindsight/.pg0

   • Or keep the host path and run as your host user, chowning it to match:
       sudo chown -R $(id -u):$(id -g) <host-directory>
       docker run --user $(id -u):$(id -g) -e HOME=/home/hindsight ...

   See https://github.com/vectorize-io/hindsight/issues/1483

Docker Compose 部署

name: hindsight
services:
    hindsight:
        container_name: hindsight
        user: 1000:1000
        ports:
            - 8888:8888
            - 9999:9999
        environment:
            - HINDSIGHT_API_LLM_PROVIDER=openrouter                                      # openrouter deepseek
            - HINDSIGHT_API_LLM_API_KEY=sk-xxxxxxxxxx
            - HINDSIGHT_API_LLM_MODEL=tencent/hy3:free                                   # deepseek-v4-flash  
            - HF_ENDPOINT=https://hf-mirror.com
            - HINDSIGHT_API_EMBEDDINGS_LOCAL_MODEL=shibing624/text2vec-base-chinese
        volumes:
            - ./hindsight-data:/home/hindsight/.pg0
        image: ghcr.nju.edu.cn/vectorize-io/hindsight:latest

端口说明

端口	用途
8888	API 端口，Hermes 通过此端口通信
9999	Web UI（Control Plane），记忆管理界面,可以图形化地查看和管理记忆库。

环境变量说明

变量	必填	说明
`HINDSIGHT_API_LLM_PROVIDER`	是	LLM 提供商（见下方支持列表）
`HINDSIGHT_API_LLM_API_KEY`	是	LLM API 密钥
`HINDSIGHT_API_LLM_MODEL`	是	模型名称
`HINDSIGHT_API_EMBEDDINGS_LOCAL_MODEL`	否	本地 Embedding 模型，默认 BAAI/bge-small-en-v1.5（纯英文），中文用户改为 shibing624/text2vec-base-chinese
`HF_ENDPOINT`	否	HuggingFace 镜像源，国内用户填 https://hf-mirror.com 加速模型下载

支持的 LLM Provider

Provider	HINDSIGHT_API_LLM_PROVIDER	推荐模型	说明
DeepSeek	`deepseek`	deepseek-v4-flash / deepseek-chat	chat会路由到flash，国内直连，性价比高，推荐
MiniMax	`minimax`	按需选择	国内原生支持
OpenAI	`openai`	gpt-4o-mini	需要能访问 OpenAI API
Groq	`groq`	gpt-oss-20b	免费额度，速度快
OpenRouter	`openrouter`	按需选择	聚合多家模型的中转平台
Anthropic	`anthropic`	claude-haiku	价格较高，非必要不推荐
Google Gemini	`gemini`	gemini-2.0-flash	需要 Google API Key
Ollama	`ollama`	本地模型	纯本地，不花钱，但需要显卡
LM Studio	`lmstudio`	本地模型	同 Ollama，GUI 方式管理本地模型

通过 OpenAI 兼容模式接入其他国内模型：

配置方式（以通义千问为例）：

-e HINDSIGHT_API_LLM_PROVIDER=openai \
-e HINDSIGHT_API_LLM_API_KEY=你的API密钥 \
-e HINDSIGHT_API_LLM_MODEL=qwen-turbo \
-e HINDSIGHT_API_LLM_BASE_URL=https://dashscope.aliyuncs.com/compatible-mode/v1

要求：模型必须支持结构化输出（structured output / function calling）。选便宜快速的就行，这个模型只做记忆提取，不影响 Hermes 对话质量。

也可以参考官方文档：https://hindsight.vectorize.io/developer/models

验证服务是否正常

# 健康检查
curl http://127.0.0.1:8888/health

# 确认输出
{"status":"healthy","database":"connected"}

创建一个记忆库：

1
2
3

curl -X POST http://localhost:8888/v1/banks \
  -H "Content-Type: application/json" \
  -d '{"name": "test", "bankType": "HYBRID"}'

存入一条记忆：

1
2
3

curl -X POST http://localhost:8888/v1/banks/test/retain \
  -H "Content-Type: application/json" \
  -d '{"content": "用户偏好使用 Python 技术栈", "context": "技术偏好"}'

搜索记忆：

1
2
3

curl -X POST http://localhost:8888/v1/banks/test/recall \
  -H "Content-Type: application/json" \
  -d '{"query": "用户的技术偏好", "limit": 5}'

能返回刚才存入的内容，说明整个链路通了：Hindsight API 到 PostgreSQL 到 pgvector，全部正常。

删除记忆库：

1 2	curl -X DELETE "http://localhost:8888/v1/default/banks/YOUR_BANK_ID" \ -H "Authorization: Bearer YOUR_HINDSIGHT_API_KEY"

Hermes 接入

在终端执行hermes memory setup，向导里选择 Hindsight 作为 provider，选择 Local External ，输入接口地址：http://你的服务器IP:8888

PS：如果配置了apikey，那么需要输入apiKey的值

完成后执行hermes memory status，日志如下基本上没有问题：

Memory status
────────────────────────────────────────
  Built-in:  always active
  Provider:  hindsight

  Plugin:    installed ✓
  Status:    available ✓

  Installed plugins:
    • byterover  (API key / local)
    • hindsight  (API key / local) ← active
    • holographic  (local)
    • honcho  (API key / local)
    • mem0  (API key / local)
    • openviking  (API key / local)
    • retaindb  (API key / local)
    • supermemory  (requires API key)

（不建议）如果之前使用过hermes内置的记忆系统，先关掉

1
2
3

hermes memory off
# 禁用 Hermes 内置记忆工具（避免冲突） 二选一执行。
hermes tools disable memory

root@e25d428b3e40:/opt/hermes# hermes memory off

  ✓ Memory provider: built-in only
  Saved to config.yaml

root@e25d428b3e40:/opt/hermes# hermes tools disable memory
✓ Disabled: memory
root@e25d428b3e40:/opt/hermes# hermes memory status

Memory status
────────────────────────────────────────
  Built-in:  always active
  Provider:  (none — built-in only)

  Installed plugins:
    • byterover  (API key / local)
    • hindsight  (API key / local)
    • holographic  (local)
    • honcho  (API key / local)
    • mem0  (API key / local)
    • openviking  (API key / local)
    • retaindb  (API key / local)
    • supermemory  (requires API key)

root@e25d428b3e40:/opt/hermes# hermes memory setup

配置文件在~/.hermes/hindsight/config.json

{
  "mode": "local_external",
  "apiKey": "",
  "timeout": 120,
  "idle_timeout": 300,
  "retain_tags": "",
  "observation_scopes": "",
  "retain_source": "",
  "retain_user_prefix": "User",
  "retain_assistant_prefix": "Assistant",
  "banks": {
    "hermes": {
      "bankId": "hermes",
      "budget": "mid",
      "enabled": true
    }
  },
  "api_url": "http://localhost:8888",
  "bank_id": "hermes",
  "bank_id_template": "hermes-{user}",
  "recall_budget": "mid"
}

默认的不是hermes-{user}，而是hermes。这里配置为hermes-{user}，每个用户都有记忆库。

记忆模式	说明
`hybrid`（推荐）	自动注入记忆 + 手动工具并存
`context`	仅自动注入，不暴露工具给模型
`tools`	仅手动工具，模型自行决定何时检索

记忆库

接入hermes后，无需创建名为hermes的记忆库，如果hermes写入记忆失败，可以手动创建。

手动创建可以使用官方的模板导入：https://hindsight.vectorize.io/templates

参考配置

以下是我实际使用的完整 docker-compose.yml，可供参考：

version: '3.8'

services:
  hindsight:
    image: ghcr.nju.edu.cn/vectorize-io/hindsight:0.7.0
    container_name: hindsight
    restart: unless-stopped
    ports:
      - "8888:8888"
      - "9999:9999"
    environment:
      HINDSIGHT_API_LLM_PROVIDER: openai
      HINDSIGHT_API_LLM_API_KEY: 'your-zhipu-api-key'
      HINDSIGHT_API_LLM_BASE_URL: 'https://open.bigmodel.cn/api/coding/paas/v4'
      HINDSIGHT_API_LLM_MODEL: 'glm-5.1'
      HINDSIGHT_API_EMBEDDINGS_PROVIDER: openai
      HINDSIGHT_API_EMBEDDINGS_OPENAI_MODEL: 'BAAI/bge-m3'
      HINDSIGHT_API_EMBEDDINGS_OPENAI_API_KEY: 'your-siliconflow-api-key'
      HINDSIGHT_API_EMBEDDINGS_OPENAI_BASE_URL: 'https://api.siliconflow.cn/v1'
      HINDSIGHT_API_RERANKER_PROVIDER: siliconflow
      HINDSIGHT_API_RERANKER_SILICONFLOW_MODEL: 'BAAI/bge-reranker-v2-m3'
      HINDSIGHT_API_RERANKER_SILICONFLOW_BASE_URL: 'https://api.siliconflow.cn/v1'
      HINDSIGHT_API_RERANKER_SILICONFLOW_API_KEY: 'your-siliconflow-api-key'
      HINDSIGHT_POSTGRES_URL: 'postgresql://hindsight:your-password@192.168.10.9:5432/hindsight'

LLM 用智谱 glm-5.1，Embedding 和 Reranker 都走硅基流动的免费使用，数据库是本机的 PostgreSQL 18。

整套下来，数据完全在自己手里，不用担心隐私，也不用操心云端的用量额度。
Hermes 的记忆能力和之前用云端时一模一样，只是背后的数据流从”上传到别人服务器”变成了”写入自己的数据库”。

常见问题

LLM 端点必须用 HTTPS。

Hindsight 连接 LLM 服务时要求 HTTPS，如果配了 HTTP 的地址会直接连不上。
但如果你用的是自建的 LLM 中转服务，记得配好证书。
Embedding 批量大小要注意。

bge-m3 默认单次最多处理 64 条，而 Hindsight 的默认批量大小是 100。
超出会返回 413 错误。
可以通过环境变量调整：
HINDSIGHT_API_EMBEDDINGS_OPENAI_BATCH_SIZE: 64

切换 Embedding 模型要清库。
不同 Embedding 模型的向量维度不同，比如 bge-m3 是 1024 维，bge-small-en-v1.5 是 384 维。
维度不兼容意味着换了模型之后，之前存的记忆全部失效，需要清空数据库重新来。
所以上线前想好用哪个模型，别来回换。

https://wiki.solozed.com/guides/%E5%B7%A5%E5%85%B7%E4%B8%8E%E6%8A%80%E8%83%BD/pitfalls/hindsight-pitfalls/