diff --git a/README.md b/README.md index 1dec3af..7bc074a 100644 --- a/README.md +++ b/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: Full docs: [profiles/cli-bundle/README.md](profiles/cli-bundle/README.md). diff --git a/profiles/cli-bundle/.env.example b/profiles/cli-bundle/.env.example index 534bb01..d6eda6e 100644 --- a/profiles/cli-bundle/.env.example +++ b/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= diff --git a/profiles/cli-bundle/05d-hindsight.sh b/profiles/cli-bundle/05d-hindsight.sh new file mode 100755 index 0000000..fbd9f88 --- /dev/null +++ b/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= \\" + 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= \\" + echo " -v \$HOME/.hindsight-docker:/home/hindsight/.pg0 \\" + echo " ghcr.io/vectorize-io/hindsight:latest" +fi + +echo "==> Hindsight step complete." diff --git a/profiles/cli-bundle/README.md b/profiles/cli-bundle/README.md index afb45e5..8105e11 100644 --- a/profiles/cli-bundle/README.md +++ b/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= \ + -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 diff --git a/profiles/cli-bundle/install.sh b/profiles/cli-bundle/install.sh index e7fb74b..0ba71da 100755 --- a/profiles/cli-bundle/install.sh +++ b/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"