From e277ddc729bb8a345cb0e30d57d7cf82632263db Mon Sep 17 00:00:00 2001
From: Codex <codex@local>
Date: Mon, 14 Sep 2026 00:39:09 -0700
Subject: [PATCH] feat: add Hindsight 0.9.2 cloud inference stack

---
 servers/hindsight/hindsight/.env.example | 69 ++++++++++++++++++++++++
 servers/hindsight/hindsight/README.md    | 32 +++++++++++
 servers/hindsight/hindsight/compose.yaml | 56 +++++++++++++++++++
 3 files changed, 157 insertions(+)
 create mode 100644 servers/hindsight/hindsight/.env.example
 create mode 100644 servers/hindsight/hindsight/README.md
 create mode 100644 servers/hindsight/hindsight/compose.yaml

diff --git a/servers/hindsight/hindsight/.env.example b/servers/hindsight/hindsight/.env.example
new file mode 100644
index 0000000..805c996
--- /dev/null
+++ b/servers/hindsight/hindsight/.env.example
@@ -0,0 +1,69 @@
+TZ=Asia/Shanghai
+
+# PostgreSQL. The password and the derived database URL stay in Arcane only.
+HINDSIGHT_DB_USER=hindsight_user
+HINDSIGHT_DB_PASSWORD=replace-with-a-random-url-safe-password
+HINDSIGHT_DB_NAME=hindsight_db
+
+# Hindsight API and control-plane UI.
+HINDSIGHT_ENABLE_API=true
+HINDSIGHT_ENABLE_CP=true
+HINDSIGHT_API_HOST=0.0.0.0
+HINDSIGHT_API_PORT=8888
+HINDSIGHT_API_LOG_LEVEL=info
+HINDSIGHT_API_WORKERS=1
+HINDSIGHT_API_VECTOR_EXTENSION=pgvector
+HINDSIGHT_API_TEXT_SEARCH_EXTENSION=native
+HINDSIGHT_API_TEXT_SEARCH_EXTENSION_NATIVE_LANGUAGE=english
+HINDSIGHT_API_ENABLE_AUTO_CONSOLIDATION=true
+HINDSIGHT_API_MCP_ENABLED=true
+
+# ZenMux, using its OpenAI-compatible endpoint. Store the real key in Arcane.
+HINDSIGHT_API_LLM_PROVIDER=openai
+HINDSIGHT_API_LLM_BASE_URL=https://zenmux.ai/api/v1
+HINDSIGHT_API_LLM_API_KEY=replace-with-zenmux-subscription-key
+HINDSIGHT_API_LLM_MODEL=openai/gpt-5.6-luna
+HINDSIGHT_API_LLM_MAX_CONCURRENT=4
+HINDSIGHT_API_LLM_MAX_RETRIES=4
+HINDSIGHT_API_LLM_INITIAL_BACKOFF=2
+HINDSIGHT_API_LLM_MAX_BACKOFF=120
+HINDSIGHT_API_LLM_TIMEOUT=300
+HINDSIGHT_API_LLM_REASONING_EFFORT=low
+HINDSIGHT_API_LLM_PROMPT_CACHE_ENABLED=true
+HINDSIGHT_API_LLM_SEND_BANK_AS_USER=true
+
+# Retain: fast structured extraction.
+HINDSIGHT_API_RETAIN_LLM_PROVIDER=openai
+HINDSIGHT_API_RETAIN_LLM_BASE_URL=https://zenmux.ai/api/v1
+HINDSIGHT_API_RETAIN_LLM_MODEL=openai/gpt-5.6-luna
+HINDSIGHT_API_RETAIN_LLM_MAX_CONCURRENT=2
+HINDSIGHT_API_RETAIN_LLM_TIMEOUT=300
+
+# Consolidation: stronger cross-memory organization, quota-aware concurrency.
+HINDSIGHT_API_CONSOLIDATION_LLM_PROVIDER=openai
+HINDSIGHT_API_CONSOLIDATION_LLM_BASE_URL=https://zenmux.ai/api/v1
+HINDSIGHT_API_CONSOLIDATION_LLM_MODEL=x-ai/grok-4.6
+HINDSIGHT_API_CONSOLIDATION_LLM_MAX_CONCURRENT=1
+HINDSIGHT_API_CONSOLIDATION_LLM_TIMEOUT=600
+HINDSIGHT_API_CONSOLIDATION_LLM_BATCH_SIZE=10
+
+# Reflect: highest-quality synthesis and belief evolution.
+HINDSIGHT_API_REFLECT_LLM_PROVIDER=openai
+HINDSIGHT_API_REFLECT_LLM_BASE_URL=https://zenmux.ai/api/v1
+HINDSIGHT_API_REFLECT_LLM_MODEL=anthropic/claude-sonnet-5
+HINDSIGHT_API_REFLECT_LLM_MAX_CONCURRENT=1
+HINDSIGHT_API_REFLECT_LLM_TIMEOUT=600
+
+# OpenRouter embeddings. BGE-M3 emits 1024-dimensional multilingual vectors.
+HINDSIGHT_API_OPENROUTER_API_KEY=replace-with-openrouter-key
+HINDSIGHT_API_EMBEDDINGS_PROVIDER=openrouter
+HINDSIGHT_API_EMBEDDINGS_OPENROUTER_MODEL=baai/bge-m3
+HINDSIGHT_API_EMBEDDINGS_OPENAI_BATCH_SIZE=32
+HINDSIGHT_API_EMBEDDINGS_MAX_INPUT_TOKENS=8192
+
+# OpenRouter reranker, with a fail-open RRF fallback.
+HINDSIGHT_API_RERANKER_PROVIDER=openrouter
+HINDSIGHT_API_RERANKER_OPENROUTER_MODEL=cohere/rerank-4-fast
+HINDSIGHT_API_RERANKER_OPENROUTER_TIMEOUT=30
+HINDSIGHT_API_RERANKER_MAX_CANDIDATES=100
+HINDSIGHT_API_RERANKER_1_PROVIDER=rrf
diff --git a/servers/hindsight/hindsight/README.md b/servers/hindsight/hindsight/README.md
new file mode 100644
index 0000000..52e4599
--- /dev/null
+++ b/servers/hindsight/hindsight/README.md
@@ -0,0 +1,32 @@
+# Hindsight 独立 VM
+
+本项目部署到 PVE VM `hindsight`（`192.168.50.47`）的 Arcane Environment。
+它是新一代空白实例，不直接挂载或修改 unRaid 上的旧数据库。
+
+## 组件
+
+- Hindsight `0.9.2-slim`；
+- PostgreSQL 18 + pgvector；
+- OpenRouter `baai/bge-m3` embedding；
+- OpenRouter `cohere/rerank-4-fast` reranker，失败时回退到 RRF；
+- ZenMux Luna 用于 Retain；
+- ZenMux Grok 4.6 用于 Consolidation；
+- ZenMux Sonnet 5 用于 Reflect。
+
+运行数据固定在 `/srv/hindsight/postgres`。Compose 和非敏感模板进入 Git，真实
+数据库密码、ZenMux key 和 OpenRouter key 仅保存在该 Arcane Environment 的
+`.env` 中。
+
+## 发布顺序
+
+1. 用 `.env.example` 在 Arcane 中建立 Environment 专属 `.env`；
+2. 对三种 LLM、embedding 和 reranker 运行合成内容探针；
+3. 启动空白实例，验证 `/health`、UI、Retain、Recall、Consolidation 和 Reflect；
+4. 保持 unRaid 旧实例在线，另行制定 bank export/import 迁移与回滚窗口；
+5. 迁移完成前不修改现有 Agent 的 Hindsight URL。
+
+## 升级策略
+
+不长期冻结在历史生产版本，也不直接使用浮动的 `latest`。跟踪 Hindsight release，
+先在空白或影子实例验证数据库迁移、provider 配置和核心工作流，再更新固定版本与
+镜像 digest，由 Arcane 滚动部署。
diff --git a/servers/hindsight/hindsight/compose.yaml b/servers/hindsight/hindsight/compose.yaml
new file mode 100644
index 0000000..e392e49
--- /dev/null
+++ b/servers/hindsight/hindsight/compose.yaml
@@ -0,0 +1,56 @@
+services:
+  postgres:
+    image: pgvector/pgvector:pg18@sha256:2ba9ca5f2e7daa0f0e7723cba1ee9167bab54efd3640516a44ac1a928dd67e7a
+    container_name: hindsight-postgres
+    restart: unless-stopped
+    environment:
+      POSTGRES_USER: ${HINDSIGHT_DB_USER:-hindsight_user}
+      POSTGRES_PASSWORD: ${HINDSIGHT_DB_PASSWORD:?Set HINDSIGHT_DB_PASSWORD in Arcane}
+      POSTGRES_DB: ${HINDSIGHT_DB_NAME:-hindsight_db}
+    volumes:
+      - /srv/hindsight/postgres:/var/lib/postgresql/18/docker
+    healthcheck:
+      test: ["CMD-SHELL", "pg_isready -U ${HINDSIGHT_DB_USER:-hindsight_user} -d ${HINDSIGHT_DB_NAME:-hindsight_db}"]
+      interval: 10s
+      timeout: 5s
+      retries: 10
+      start_period: 20s
+    networks:
+      - hindsight
+    security_opt:
+      - no-new-privileges:true
+    logging: &default-logging
+      driver: json-file
+      options:
+        max-size: 10m
+        max-file: "3"
+
+  hindsight:
+    image: ghcr.io/vectorize-io/hindsight:0.9.2-slim@sha256:2e894dee607d98fa9cbc5ca8d9676ca803618f9570e1a473385050a899a3e1a1
+    container_name: hindsight
+    restart: unless-stopped
+    env_file:
+      - ${HINDSIGHT_ENV_FILE:-.env}
+    environment:
+      HINDSIGHT_API_DATABASE_URL: postgresql://${HINDSIGHT_DB_USER:-hindsight_user}:${HINDSIGHT_DB_PASSWORD:?Set HINDSIGHT_DB_PASSWORD in Arcane}@postgres:5432/${HINDSIGHT_DB_NAME:-hindsight_db}
+    ports:
+      - "192.168.50.47:8888:8888"
+      - "192.168.50.47:9999:9999"
+    depends_on:
+      postgres:
+        condition: service_healthy
+    healthcheck:
+      test: ["CMD", "python", "-c", "import urllib.request; urllib.request.urlopen('http://127.0.0.1:8888/health', timeout=5)"]
+      interval: 15s
+      timeout: 8s
+      retries: 10
+      start_period: 45s
+    networks:
+      - hindsight
+    security_opt:
+      - no-new-privileges:true
+    logging: *default-logging
+
+networks:
+  hindsight:
+    name: hindsight