feat(cli-bundle): prototype opt-in Hindsight agent-memory step

README.md

@@ -54,7 +54,8 @@ harness/
 │                              # print_manual_install_hint
 └── profiles/
     ├── cli-bundle/            # 01-system → 02-claude → 03-codex → 04-antigravity
-    │                          # → 05-cursor → 05b-opencode → 05c-openviking → 08-obsidian
+    │                          # → 05-cursor → 05b-opencode → 05c-openviking
+    │                          # → 05d-hindsight → 08-obsidian
     │                          # → 06-mcp → 07-dream → 09-plugins
     ├── openclaw/              # 01-system → 02-openclaw
     ├── hermes/                # 01-system → 02-hermes
@@ -159,6 +160,12 @@ Plus:
 - **Obsidian vault** (`08-obsidian.sh`) — shared workspace for every CLI.
 - **Dream mode** (`07-dream.sh`) — cron-driven `claude -p` invocation of
   `anthropic-skills:consolidate-memory` at `03:00`; log auto-rotates at 5 MiB.
+- **Hindsight** (`05d-hindsight.sh`, _prototype, opt-in_) — agent-memory
+  client lib (`@vectorize-io/hindsight-client`) and an optional Dockerized
+  server (API `:8888`, UI `:9999`). Enable with `INSTALL_HINDSIGHT=true`;
+  start the server with `HINDSIGHT_START_SERVER=true` (needs Docker + an LLM
+  key). Tracked alongside OpenViking as an agent-memory backend to evaluate.
+  Upstream: <https://github.com/vectorize-io/hindsight>
 
 Full docs: [profiles/cli-bundle/README.md](profiles/cli-bundle/README.md).
 

profiles/cli-bundle/.env.example

@@ -10,6 +10,7 @@ INSTALL_ANTIGRAVITY=false
 INSTALL_CURSOR=false
 INSTALL_OPENCODE=false
 INSTALL_OPENVIKING=false
+INSTALL_HINDSIGHT=false
 
 # --- Claude Code Auth ---
 # Optional. Leave empty to use OAuth via `claude login`. console.anthropic.com
@@ -29,6 +30,17 @@ OPENAI_API_KEY=
 # No CLI auth needed. Configure your server with `ov config` (interactive).
 # Defaults to http://localhost:1933. https://github.com/volcengine/OpenViking
 
+# --- Hindsight (agent-memory) — PROTOTYPE / opt-in ---
+# Client libs + optional Docker server (API :8888, UI :9999).
+# https://github.com/vectorize-io/hindsight
+HINDSIGHT_NPM_CLIENT=true       # install @vectorize-io/hindsight-client (npm)
+HINDSIGHT_PIP_CLIENT=false      # install hindsight-client (pipx/pip --user)
+# Start the Dockerized server during install (needs Docker + an LLM key below).
+HINDSIGHT_START_SERVER=false
+# LLM provider: openai | anthropic | gemini | groq | ollama | lmstudio | minimax
+HINDSIGHT_LLM_PROVIDER=openai
+HINDSIGHT_LLM_API_KEY=
+
 # --- Context7 (Upstash) ---
 # Optional. Free without key, higher rate limit with key from context7.com
 CONTEXT7_API_KEY=

profiles/cli-bundle/05d-hindsight.sh

@@ -0,0 +1,86 @@
+#!/usr/bin/env bash
+# ============================================================
+# 05d-hindsight.sh — Installs Hindsight agent-memory (client + optional server).
+# Client:  @vectorize-io/hindsight-client (npm) and/or hindsight-client (pip).
+# Server:  Docker image ghcr.io/vectorize-io/hindsight:latest
+#          API on :8888, UI on :9999. Needs an LLM provider + key.
+# Upstream: https://github.com/vectorize-io/hindsight
+# NOTE: prototype — opt-in via INSTALL_HINDSIGHT. Server start is gated again
+#       on HINDSIGHT_START_SERVER and the presence of Docker.
+# ============================================================
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+ENV_FILE="$SCRIPT_DIR/.env"
+
+if [[ ! -f "$ENV_FILE" ]]; then
+  echo "ERROR: $ENV_FILE not found."
+  exit 1
+fi
+
+# shellcheck disable=SC1090
+set -a; source "$ENV_FILE"; set +a
+
+if [[ "${INSTALL_HINDSIGHT:-false}" != "true" ]]; then
+  echo "==> Hindsight install disabled (INSTALL_HINDSIGHT != true). Skipping."
+  exit 0
+fi
+
+export PATH="$HOME/.npm-global/bin:$HOME/.local/bin:$PATH"
+
+# --- Client libraries -----------------------------------------------------
+# Node/TS client (default on; matches the npm-first convention of this bundle).
+if [[ "${HINDSIGHT_NPM_CLIENT:-true}" == "true" ]]; then
+  echo "==> Installing @vectorize-io/hindsight-client (npm)"
+  npm install -g @vectorize-io/hindsight-client
+fi
+
+# Python client (opt-in). Uses pipx when available to avoid PEP 668 breakage.
+if [[ "${HINDSIGHT_PIP_CLIENT:-false}" == "true" ]]; then
+  if command -v pipx >/dev/null 2>&1; then
+    echo "==> Installing hindsight-client (pipx)"
+    pipx install hindsight-client || pipx upgrade hindsight-client || true
+  elif command -v pip3 >/dev/null 2>&1; then
+    echo "==> Installing hindsight-client (pip3 --user)"
+    pip3 install --user -U hindsight-client
+  else
+    echo "WARN: neither pipx nor pip3 found — skipping Python client."
+  fi
+fi
+
+# --- Server (Docker, opt-in) ----------------------------------------------
+if [[ "${HINDSIGHT_START_SERVER:-false}" == "true" ]]; then
+  if ! command -v docker >/dev/null 2>&1; then
+    echo "WARN: HINDSIGHT_START_SERVER=true but Docker is not installed."
+    echo "      Install Docker, then run:"
+    echo "        docker run --rm -d --pull always -p 8888:8888 -p 9999:9999 \\"
+    echo "          -e HINDSIGHT_API_LLM_PROVIDER=${HINDSIGHT_LLM_PROVIDER:-openai} \\"
+    echo "          -e HINDSIGHT_API_LLM_API_KEY=<your-key> \\"
+    echo "          -v \$HOME/.hindsight-docker:/home/hindsight/.pg0 \\"
+    echo "          ghcr.io/vectorize-io/hindsight:latest"
+  elif [[ -z "${HINDSIGHT_LLM_API_KEY:-}" ]]; then
+    echo "WARN: HINDSIGHT_START_SERVER=true but HINDSIGHT_LLM_API_KEY is empty."
+    echo "      Set it (and HINDSIGHT_LLM_PROVIDER) in .env, or start the server manually."
+  else
+    echo "==> Starting Hindsight server (Docker) — API :8888, UI :9999"
+    mkdir -p "$HOME/.hindsight-docker"
+    docker run --rm -d --pull always \
+      --name hindsight \
+      -p 8888:8888 -p 9999:9999 \
+      -e "HINDSIGHT_API_LLM_PROVIDER=${HINDSIGHT_LLM_PROVIDER:-openai}" \
+      -e "HINDSIGHT_API_LLM_API_KEY=${HINDSIGHT_LLM_API_KEY}" \
+      -v "$HOME/.hindsight-docker:/home/hindsight/.pg0" \
+      ghcr.io/vectorize-io/hindsight:latest
+    echo "    Started. API: http://localhost:8888  ·  UI: http://localhost:9999"
+  fi
+else
+  echo "==> Hindsight server start disabled (HINDSIGHT_START_SERVER != true)."
+  echo "    Client installed. To run the server later (needs Docker + LLM key):"
+  echo "      docker run --rm -d --pull always -p 8888:8888 -p 9999:9999 \\"
+  echo "        -e HINDSIGHT_API_LLM_PROVIDER=${HINDSIGHT_LLM_PROVIDER:-openai} \\"
+  echo "        -e HINDSIGHT_API_LLM_API_KEY=<your-key> \\"
+  echo "        -v \$HOME/.hindsight-docker:/home/hindsight/.pg0 \\"
+  echo "        ghcr.io/vectorize-io/hindsight:latest"
+fi
+
+echo "==> Hindsight step complete."

profiles/cli-bundle/README.md

@@ -110,6 +110,37 @@ crontab -l | grep -v claude-dream | crontab -
 rm ~/.claude/dream.sh
 ```
 
+## Hindsight (memória de agentes — protótipo, opt-in)
+
+[Hindsight](https://github.com/vectorize-io/hindsight) é um sistema de memória
+de agentes (mesma categoria do OpenViking), com biblioteca cliente + servidor
+Dockerizado (API `:8888`, UI `:9999`). Passo `05d-hindsight.sh`, **desligado por
+padrão** — adicionado para avaliarmos depois.
+
+```env
+INSTALL_HINDSIGHT=true            # liga o passo
+HINDSIGHT_NPM_CLIENT=true         # instala @vectorize-io/hindsight-client (npm)
+HINDSIGHT_PIP_CLIENT=false        # instala hindsight-client (pipx/pip --user)
+HINDSIGHT_START_SERVER=false      # sobe o servidor via Docker no install
+HINDSIGHT_LLM_PROVIDER=openai     # openai|anthropic|gemini|groq|ollama|lmstudio|minimax
+HINDSIGHT_LLM_API_KEY=            # chave do provider (necessária p/ subir o servidor)
+```
+
+O passo instala o cliente e, se `HINDSIGHT_START_SERVER=true` **e** o Docker
+estiver presente **e** houver `HINDSIGHT_LLM_API_KEY`, sobe o servidor:
+```bash
+docker run --rm -d --pull always -p 8888:8888 -p 9999:9999 \
+  -e HINDSIGHT_API_LLM_PROVIDER=openai \
+  -e HINDSIGHT_API_LLM_API_KEY=<sua-key> \
+  -v $HOME/.hindsight-docker:/home/hindsight/.pg0 \
+  ghcr.io/vectorize-io/hindsight:latest
+```
+Caso contrário, apenas imprime o comando para você subir manualmente depois.
+A API fica em `http://localhost:8888` e a UI em `http://localhost:9999`.
+
+> ⚠️ Protótipo: ainda não integrado ao Claude Code como backend de memória —
+> serve para testes comparativos com o OpenViking.
+
 ## Obsidian vault (workspace compartilhado entre CLIs)
 
 Vault único em `$OBSIDIAN_VAULT_DIR` (default `~/vault`) que todos os CLIs

profiles/cli-bundle/install.sh

@@ -1,8 +1,8 @@
 #!/usr/bin/env bash
 # ============================================================
 # cli-bundle/install.sh
-# Installs Claude Code + Codex + Antigravity + Cursor + OpenCode + OpenViking CLIs.
-# All coexist on one host. Toggle individually in .env.
+# Installs Claude Code + Codex + Antigravity + Cursor + OpenCode + OpenViking CLIs,
+# plus optional Hindsight agent-memory (prototype). Toggle individually in .env.
 # ============================================================
 set -euo pipefail
 
@@ -30,6 +30,7 @@ bash "$SCRIPT_DIR/04-antigravity.sh"
 bash "$SCRIPT_DIR/05-cursor.sh"
 bash "$SCRIPT_DIR/05b-opencode.sh"
 bash "$SCRIPT_DIR/05c-openviking.sh"
+bash "$SCRIPT_DIR/05d-hindsight.sh"
 bash "$SCRIPT_DIR/08-obsidian.sh"   # vault skeleton first; MCP step below registers it
 bash "$SCRIPT_DIR/06-mcp.sh"
 bash "$SCRIPT_DIR/07-dream.sh"