leopold-driver 0.1.0 → 0.1.2

package/assets/extensions/ovmem/install.sh

@@ -0,0 +1,330 @@
+#!/usr/bin/env bash
+# ovmem installer / reconfigure — pick a provider + models, set everything up, and
+# switch safely between providers (incl. re-embedding the memory store when the
+# embedding model changes).
+#
+# Providers:
+#   openai   - one API key (needs embedding + model.request scopes).
+#   bedrock  - AWS Bedrock via LiteLLM; auth = a Bedrock API key (bearer) + region.
+#
+# Re-running detects the current install: it offers to reuse the existing credential,
+# defaults each prompt to the current choice, and — if you change the embedding model —
+# rebuilds the vector index for the new dimension (your memory CONTENT is preserved;
+# only the index is re-embedded). The old index is backed up and restored if the rebuild
+# fails. Server restarts are lock-aware (one OpenViking process per data dir).
+#
+# Interactive prompts read /dev/tty (works under `curl … | bash`). Headless: set
+# OVMEM_PROVIDER, OVMEM_CHAT_MODEL, OVMEM_EMBED_MODEL + OPENAI_API_KEY (openai) or
+# AWS_BEARER_TOKEN_BEDROCK + AWS_REGION (bedrock).
+set -euo pipefail
+
+HERE="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+PAYLOAD="$HERE/payload"; MODELS="$HERE/models.json"
+CLAUDE="${CLAUDE_HOME:-$HOME/.claude}"; OVMEM_DIR="$CLAUDE/ovmem"; SETTINGS="$CLAUDE/settings.json"
+OV_DIR="$HOME/.openviking"; OV_CONF="$OV_DIR/ov.conf"; WORKSPACE="$OV_DIR/data"; VDB="$WORKSPACE/vectordb"
+BIN="$HOME/.local/bin"; HEALTH="http://127.0.0.1:1933/health"; API="http://127.0.0.1:1933/api/v1"
+OPENVIKING_PIN="openviking==0.3.21"
+
+say()  { printf "\033[36m->\033[0m %s\n" "$*"; }
+ok()   { printf "   \033[32mok\033[0m   %s\n" "$*"; }
+warn() { printf "   \033[33mwarn\033[0m %s\n" "$*"; }
+die()  { printf "\033[31mx\033[0m %s\n" "$*" >&2; exit 1; }
+
+TTY=""; if exec 3<>/dev/tty 2>/dev/null; then TTY=3; fi
+ask() { local p="$1" d="${2:-}" a=""
+  if [ -n "$TTY" ]; then
+    if [ -n "$d" ]; then printf "%s [%s]: " "$p" "$d" >&"$TTY"; else printf "%s: " "$p" >&"$TTY"; fi
+    IFS= read -r a <&"$TTY" || a=""; [ -z "$a" ] && a="$d"
+  else a="$d"; fi
+  printf "%s" "$a"; }
+ask_secret() { local p="$1" a=""
+  if [ -n "$TTY" ]; then printf "%s: " "$p" >&"$TTY"; IFS= read -rs a <&"$TTY" || a=""; printf "\n" >&"$TTY"; fi
+  printf "%s" "$a"; }
+confirm() { case "$(ask "$1 [Y/n]" "Y")" in [nN]*) return 1;; *) return 0;; esac; }
+j() { jq -r "$1" "$MODELS"; }
+
+# Run a command with a live "<label>… Ns" spinner so a long, silent step never looks
+# frozen — even when it's really a background download/reindex. stdout+stderr are captured
+# to SPIN_OUT so callers can use the output (or print it on failure). Headless: one line.
+SPIN_OUT=""
+run_spin() {
+  local label="$1"; shift
+  local tmp; tmp="$(mktemp 2>/dev/null || echo "/tmp/ovm_spin.$$")"
+  ( "$@" >"$tmp" 2>&1 ) & local pid=$!
+  if [ -n "$TTY" ]; then
+    local i=0 t0=$SECONDS f='|/-\'
+    while kill -0 "$pid" 2>/dev/null; do
+      printf "\r   \033[2m%s %s… %ds\033[0m" "${f:i%4:1}" "$label" "$((SECONDS-t0))" >&"$TTY"
+      i=$((i+1)); sleep 0.2
+    done
+    printf "\r\033[K" >&"$TTY"
+  else
+    printf "   ... %s (running)\n" "$label"
+  fi
+  local rc=0; wait "$pid" || rc=$?
+  SPIN_OUT="$(cat "$tmp" 2>/dev/null || true)"; rm -f "$tmp"
+  return "$rc"
+}
+
+# ---- platform + server lifecycle (lock-aware) ------------------------------
+case "$(uname -s 2>/dev/null || echo unknown)" in
+  Linux|Darwin) : ;;
+  MINGW*|MSYS*|CYGWIN*|Windows*) die "Native Windows is not supported. Run inside WSL." ;;
+  *) warn "unrecognized OS '$(uname -s 2>/dev/null)'; only Linux/macOS are tested." ;;
+esac
+port_pid() { if command -v lsof >/dev/null 2>&1; then lsof -ti tcp:1933 2>/dev/null | head -1
+  elif command -v ss >/dev/null 2>&1; then ss -tlnp 2>/dev/null | grep ':1933' | sed -n 's/.*pid=\([0-9]*\).*/\1/p' | head -1; fi; }
+server_pids() { pgrep -f "bin/openviking-server" 2>/dev/null || true; }
+# Stop EVERY OpenViking process and wait until the data-dir lock is free. Running two
+# instances on one data dir is forbidden (DataDirectoryLocked); a kill + instant restart
+# races the lock, so we wait for the process to actually die.
+stop_server() {
+  local p _; p="$(server_pids)"; [ -n "$p" ] && kill $p 2>/dev/null || true
+  for _ in $(seq 1 40); do [ -z "$(server_pids)" ] && [ -z "$(port_pid || true)" ] && break; sleep 0.4; done
+  p="$(server_pids)"; [ -n "$p" ] && kill -9 $p 2>/dev/null || true
+  for _ in $(seq 1 10); do [ -z "$(server_pids)" ] && break; sleep 0.3; done
+  rm -f /tmp/openviking.pid "$WORKSPACE/.openviking.pid" 2>/dev/null || true
+}
+start_server() {
+  "$BIN/openviking-start"
+  run_spin "waiting for OpenViking to be healthy" \
+    curl -s --retry 40 --retry-delay 1 --retry-connrefused -m 80 "$HEALTH" \
+    || die "OpenViking did not become healthy; see /tmp/openviking.log"
+}
+
+# ---- detect the current install --------------------------------------------
+CUR_PROVIDER=""; CUR_CHAT_MODEL=""; CUR_EMBED_MODEL=""; CUR_DIM=""; CUR_ROOTKEY=""
+CUR_OPENAI_KEY=""; CUR_AWS_TOKEN=""; CUR_AWS_REGION=""; CUR_CHAT_ID=""; CUR_EMBED_ID=""
+read_current() {
+  [ -f "$OV_CONF" ] && command -v jq >/dev/null 2>&1 || return 0
+  CUR_CHAT_MODEL="$(jq -r '.vlm.model // empty' "$OV_CONF" 2>/dev/null)"
+  CUR_EMBED_MODEL="$(jq -r '.embedding.dense.model // empty' "$OV_CONF" 2>/dev/null)"
+  CUR_DIM="$(jq -r '.embedding.dense.dimension // empty' "$OV_CONF" 2>/dev/null)"
+  CUR_ROOTKEY="$(jq -r '.server.root_api_key // empty' "$OV_CONF" 2>/dev/null)"
+  case "$CUR_CHAT_MODEL" in bedrock/*) CUR_PROVIDER=bedrock ;; ?*) CUR_PROVIDER=openai ;; esac
+  [ "$CUR_PROVIDER" = openai ] && CUR_OPENAI_KEY="$(jq -r '.vlm.api_key // empty' "$OV_CONF" 2>/dev/null)"
+  CUR_CHAT_ID="$(j ".chat[]|select(.model==\"$CUR_CHAT_MODEL\").id" 2>/dev/null | head -1)"
+  CUR_EMBED_ID="$(j ".embed[]|select(.model==\"$CUR_EMBED_MODEL\").id" 2>/dev/null | head -1)"
+  if [ -f "$BIN/openviking-start" ]; then
+    CUR_AWS_TOKEN="$( (eval "$(grep '^export AWS_BEARER_TOKEN_BEDROCK=' "$BIN/openviking-start" 2>/dev/null)"; printf '%s' "${AWS_BEARER_TOKEN_BEDROCK:-}") )"
+    CUR_AWS_REGION="$( (eval "$(grep '^export AWS_REGION=' "$BIN/openviking-start" 2>/dev/null)"; printf '%s' "${AWS_REGION:-}") )"
+  fi
+}
+read_current
+
+# ---- prereqs ---------------------------------------------------------------
+say "checking prerequisites"
+command -v curl    >/dev/null 2>&1 || die "curl is required"
+command -v jq      >/dev/null 2>&1 || die "jq is required (https://jqlang.github.io/jq/)"
+command -v python3 >/dev/null 2>&1 || die "python3 is required"
+[ -f "$MODELS" ]   || die "models.json not found next to the installer"
+if ! command -v uv >/dev/null 2>&1; then
+  warn "uv not found - installing it"; curl -LsSf https://astral.sh/uv/install.sh | sh || die "uv install failed"; export PATH="$HOME/.local/bin:$PATH"
+fi
+ok "curl, jq, python3, uv present"
+[ -n "$CUR_PROVIDER" ] && say "current ovmem: provider=$CUR_PROVIDER  chat=${CUR_CHAT_ID:-$CUR_CHAT_MODEL}  embed=${CUR_EMBED_ID:-$CUR_EMBED_MODEL} (${CUR_DIM}d)"
+
+# ---- pick provider + models (default to current) ---------------------------
+PROVIDER="${OVMEM_PROVIDER:-}"
+if [ -z "$PROVIDER" ]; then
+  if [ -n "$TTY" ]; then
+    pdef=1; [ "$CUR_PROVIDER" = bedrock ] && pdef=2
+    om=""; [ "$CUR_PROVIDER" = openai ] && om=" (current)"; bm=""; [ "$CUR_PROVIDER" = bedrock ] && bm=" (current)"
+    printf "\nProvider:\n  1) openai%s\n  2) bedrock%s\n" "$om" "$bm" >&"$TTY"
+    case "$(ask "select" "$pdef")" in 2|bedrock) PROVIDER=bedrock ;; *) PROVIDER=openai ;; esac
+  else die "headless: set OVMEM_PROVIDER=openai|bedrock"; fi
+fi
+[ "$PROVIDER" = openai ] || [ "$PROVIDER" = bedrock ] || die "unknown provider: $PROVIDER"
+
+pick_model() {  # $1 kind  $2 default_id -> echoes chosen id
+  local kind="$1" defid="${2:-}" preset="" i n choice line defnum=1 id mark
+  local ids=()
+  case "$kind" in chat) preset="${OVMEM_CHAT_MODEL:-}";; embed) preset="${OVMEM_EMBED_MODEL:-}";; esac
+  while IFS= read -r line; do [ -n "$line" ] && ids+=("$line"); done < <(j ".${kind}[] | select(.provider==\"$PROVIDER\") | .id")
+  [ "${#ids[@]}" -gt 0 ] || die "no $kind models for provider $PROVIDER in models.json"
+  if [ -n "$preset" ]; then printf "%s" "$preset"; return; fi
+  if [ -z "$TTY" ]; then die "headless: set OVMEM_$(printf '%s' "$kind" | tr '[:lower:]' '[:upper:]')_MODEL (one of: ${ids[*]})"; fi
+  i=1; for id in "${ids[@]}"; do [ "$id" = "$defid" ] && defnum=$i; i=$((i+1)); done
+  printf "\n%s model:\n" "$kind" >&"$TTY"; i=1
+  for id in "${ids[@]}"; do
+    mark=""; [ "$id" = "$defid" ] && mark=" (current)"
+    if [ "$kind" = chat ]; then
+      printf "  %d) %-22s \$%s in / \$%s out per 1M%s\n" "$i" "$id" "$(j ".chat[]|select(.id==\"$id\").in")" "$(j ".chat[]|select(.id==\"$id\").out")" "$mark" >&"$TTY"
+    else
+      printf "  %d) %-26s \$%s per 1M · %sd%s\n" "$i" "$id" "$(j ".embed[]|select(.id==\"$id\").price")" "$(j ".embed[]|select(.id==\"$id\").dim")" "$mark" >&"$TTY"
+    fi
+    i=$((i+1))
+  done
+  n="${#ids[@]}"; choice="$(ask "select" "$defnum")"
+  case "$choice" in (*[!0-9]*|"") choice=$defnum ;; esac
+  [ "$choice" -ge 1 ] && [ "$choice" -le "$n" ] || choice=$defnum
+  printf "%s" "${ids[$((choice-1))]}"
+}
+
+[ "$PROVIDER" = "$CUR_PROVIDER" ] && DEF_CHAT="$CUR_CHAT_ID" && DEF_EMBED="$CUR_EMBED_ID" || { DEF_CHAT=""; DEF_EMBED=""; }
+CHAT_ID="$(pick_model chat "$DEF_CHAT")"
+EMBED_ID="$(pick_model embed "$DEF_EMBED")"
+CHAT_MODEL="$(j ".chat[]|select(.id==\"$CHAT_ID\").model")"
+EMBED_MODEL="$(j ".embed[]|select(.id==\"$EMBED_ID\").model")"
+EMBED_DIM="$(j ".embed[]|select(.id==\"$EMBED_ID\").dim")"
+ok "provider=$PROVIDER  chat=$CHAT_ID  embed=$EMBED_ID (${EMBED_DIM}d)"
+
+# ---- decide if the memory index must be rebuilt ----------------------------
+REINDEX=0
+if [ -d "$VDB" ] && [ -n "$CUR_EMBED_MODEL" ] && { [ "$EMBED_MODEL" != "$CUR_EMBED_MODEL" ] || [ "$EMBED_DIM" != "$CUR_DIM" ]; }; then
+  REINDEX=1
+  warn "embedding is changing: $CUR_EMBED_MODEL (${CUR_DIM}d) -> $EMBED_MODEL (${EMBED_DIM}d)."
+  warn "your memories stay; the vector index is rebuilt (re-embedded in the new model's space)."
+  [ -n "$TTY" ] && { confirm "proceed with the switch + rebuild?" || die "aborted; nothing changed."; }
+fi
+
+# ---- OpenViking (+ boto3 for bedrock) --------------------------------------
+# First install downloads ~140 packages (OpenViking + LiteLLM + deps); warn so the long,
+# quiet uv resolve/download step doesn't look frozen. Re-runs are near-instant.
+ov_hint() { printf "   \033[2m(downloading OpenViking + ~140 packages — up to a few minutes on first install)\033[0m\n"; }
+uv_fail() { [ -n "$SPIN_OUT" ] && printf '%s\n' "$SPIN_OUT" | tail -5 | sed 's/^/     /'; die "$1"; }
+if [ "$PROVIDER" = bedrock ]; then
+  say "ensuring OpenViking + boto3 (Bedrock)"
+  command -v openviking-server >/dev/null 2>&1 || ov_hint
+  run_spin "downloading OpenViking + boto3" uv tool install --with boto3 "$OPENVIKING_PIN" \
+    || uv_fail "uv tool install (with boto3) failed"
+elif ! command -v openviking-server >/dev/null 2>&1; then
+  say "installing OpenViking"; ov_hint
+  run_spin "downloading OpenViking + deps" uv tool install "$OPENVIKING_PIN" \
+    || uv_fail "uv tool install failed"
+fi
+export PATH="$BIN:$PATH"
+command -v openviking-server >/dev/null 2>&1 || die "openviking-server not on PATH (add $BIN)"
+ok "OpenViking ready"
+
+# ---- auth (reuse existing credential when possible) ------------------------
+OPENAI_KEY=""; AWS_TOKEN=""; AWS_REGION_V=""
+validate_openai() { local cc ec
+  cc="$(curl -s -o /tmp/ovm_c.json -w '%{http_code}' -m 30 https://api.openai.com/v1/chat/completions \
+    -H "Authorization: Bearer $1" -H "Content-Type: application/json" \
+    -d "{\"model\":\"$CHAT_MODEL\",\"max_tokens\":5,\"messages\":[{\"role\":\"user\",\"content\":\"ok\"}]}" 2>/dev/null || echo 000)"
+  if [ "$cc" != 200 ]; then grep -q "model.request" /tmp/ovm_c.json 2>/dev/null && warn "key missing the model.request (chat) scope" || warn "chat check failed (HTTP $cc)"; return 1; fi
+  ec="$(curl -s -o /tmp/ovm_e.json -w '%{http_code}' -m 30 https://api.openai.com/v1/embeddings \
+    -H "Authorization: Bearer $1" -H "Content-Type: application/json" -d "{\"model\":\"$EMBED_MODEL\",\"input\":\"ok\"}" 2>/dev/null || echo 000)"
+  [ "$ec" = 200 ] || { warn "embeddings check failed (HTTP $ec)"; return 1; }; return 0; }
+
+if [ "$PROVIDER" = openai ]; then
+  if [ -n "$CUR_OPENAI_KEY" ] && [ "$CUR_OPENAI_KEY" != bedrock ] && validate_openai "$CUR_OPENAI_KEY" && { [ -z "$TTY" ] || confirm "reuse the existing OpenAI key?"; }; then
+    OPENAI_KEY="$CUR_OPENAI_KEY"; ok "reusing the existing OpenAI key (validated)"
+  elif [ -z "$TTY" ]; then
+    OPENAI_KEY="${OPENAI_API_KEY:-}"; [ -n "$OPENAI_KEY" ] || die "headless: set OPENAI_API_KEY"
+    validate_openai "$OPENAI_KEY" || die "OPENAI_API_KEY failed validation"; ok "key validated"
+  else
+    say "OpenAI key (needs embedding + model.request scopes; hidden)"
+    for _t in 1 2 3; do OPENAI_KEY="$(ask_secret "   paste key")"
+      [ -n "$OPENAI_KEY" ] && validate_openai "$OPENAI_KEY" && { ok "key validated"; break; } || OPENAI_KEY=""
+      [ "$_t" = 3 ] && die "key validation failed 3x."; done
+  fi
+  rm -f /tmp/ovm_c.json /tmp/ovm_e.json
+else
+  AWS_REGION_V="${AWS_REGION:-${CUR_AWS_REGION:-}}"; [ -n "$AWS_REGION_V" ] || AWS_REGION_V="$(ask "AWS region" "us-east-1")"
+  if [ -n "$CUR_AWS_TOKEN" ] && { [ -z "$TTY" ] || confirm "reuse the existing Bedrock API key?"; }; then
+    AWS_TOKEN="$CUR_AWS_TOKEN"; ok "reusing the existing Bedrock API key"
+  elif [ -z "$TTY" ]; then
+    AWS_TOKEN="${AWS_BEARER_TOKEN_BEDROCK:-}"; [ -n "$AWS_TOKEN" ] || die "headless: set AWS_BEARER_TOKEN_BEDROCK"
+  else
+    AWS_TOKEN="$(ask_secret "   Bedrock API key (bearer token)")"; [ -n "$AWS_TOKEN" ] || die "no Bedrock API key given"
+  fi
+  ok "Bedrock region=$AWS_REGION_V (verified by the round-trip below)"
+fi
+
+# ---- ov.conf (preserve the root key on reconfigure) ------------------------
+say "writing $OV_CONF"
+mkdir -p "$OV_DIR" "$WORKSPACE"
+[ -f "$OV_CONF" ] && cp "$OV_CONF" "$OV_CONF.ovmem.bak"
+ROOTKEY="${CUR_ROOTKEY:-$(openssl rand -hex 16 2>/dev/null || echo ov-local-dev-key)}"
+if [ "$PROVIDER" = openai ]; then
+  jq -n --arg key "$OPENAI_KEY" --arg ws "$WORKSPACE" --arg rk "$ROOTKEY" --arg cm "$CHAT_MODEL" --arg em "$EMBED_MODEL" --argjson dim "$EMBED_DIM" '{
+    storage:{workspace:$ws}, server:{host:"127.0.0.1",port:1933,root_api_key:$rk},
+    embedding:{dense:{provider:"openai",model:$em,api_key:$key,api_base:"https://api.openai.com/v1",dimension:$dim}},
+    vlm:{provider:"openai",model:$cm,api_key:$key,api_base:"https://api.openai.com/v1",temperature:0.0,max_tokens:16384,max_retries:2},
+    output_language_override:"en"}' > "$OV_CONF"
+else
+  jq -n --arg ws "$WORKSPACE" --arg rk "$ROOTKEY" --arg cm "$CHAT_MODEL" --arg em "$EMBED_MODEL" --argjson dim "$EMBED_DIM" '{
+    storage:{workspace:$ws}, server:{host:"127.0.0.1",port:1933,root_api_key:$rk},
+    embedding:{dense:{provider:"litellm",model:$em,api_key:"bedrock",dimension:$dim}},
+    vlm:{provider:"litellm",model:$cm,api_key:"bedrock",temperature:0.0,max_tokens:8192,max_retries:2},
+    output_language_override:"en"}' > "$OV_CONF"
+fi
+chmod 600 "$OV_CONF"; ok "ov.conf written (chmod 600)"
+
+# ---- server bootstrap wrapper (+ bedrock env) ------------------------------
+mkdir -p "$BIN"
+{ echo '#!/usr/bin/env bash'; echo '# Start OpenViking in the background if not already healthy.'
+  if [ "$PROVIDER" = bedrock ]; then printf 'export AWS_BEARER_TOKEN_BEDROCK=%q\n' "$AWS_TOKEN"; printf 'export AWS_REGION=%q\n' "$AWS_REGION_V"; printf 'export AWS_DEFAULT_REGION=%q\n' "$AWS_REGION_V"; fi
+  echo 'if curl -sf http://127.0.0.1:1933/health > /dev/null 2>&1; then exit 0; fi'
+  printf 'nohup "%s/openviking-server" --host 127.0.0.1 --port 1933 > /tmp/openviking.log 2>&1 &\n' "$BIN"
+  echo 'echo $! > /tmp/openviking.pid'; } > "$BIN/openviking-start"
+chmod 700 "$BIN/openviking-start"
+
+# ---- apply: stop (lock-safe) -> (rebuild index if needed) -> start ----------
+H=(-H "x-api-key: $ROOTKEY" -H "X-OpenViking-Account: default" -H "X-OpenViking-User: ${USER:-default}" -H "X-OpenViking-Agent: claude-code" -H "Content-Type: application/json")
+say "restarting OpenViking with the new config"
+stop_server
+if [ "$REINDEX" = 1 ] && [ -d "$VDB" ]; then
+  rm -rf "$VDB.ovmem.bak"; cp -r "$VDB" "$VDB.ovmem.bak"; rm -rf "$VDB"
+  warn "index backed up to $VDB.ovmem.bak and dropped (memory content untouched)"
+fi
+start_server
+ok "server healthy on 127.0.0.1:1933"
+
+if [ "$REINDEX" = 1 ]; then
+  say "re-embedding your memories with $EMBED_ID (content preserved)"
+  run_spin "re-embedding memories" \
+    curl -s -m 600 -X POST "${H[@]}" -d '{"uri":"viking://","wait":true}' "$API/content/reindex" || true
+  R="$SPIN_OUT"; [ -n "$R" ] || R='{}'
+  if echo "$R" | jq -e '(.result.status=="completed") and ((.result.failed_records // 0)==0)' >/dev/null 2>&1; then
+    ok "reindex complete ($(echo "$R" | jq -r '.result.rebuilt_records // 0') records re-embedded)"
+    rm -rf "$VDB.ovmem.bak"
+  else
+    warn "reindex did not complete cleanly — restoring the previous index"
+    stop_server; rm -rf "$VDB"; [ -d "$VDB.ovmem.bak" ] && mv "$VDB.ovmem.bak" "$VDB"
+    cp "$OV_CONF.ovmem.bak" "$OV_CONF" 2>/dev/null || true; start_server
+    die "the embedding switch failed; your previous setup ($CUR_PROVIDER/$CUR_EMBED_ID) was restored. See /tmp/openviking.log"
+  fi
+fi
+
+# ---- vendor scripts + wire hooks (idempotent) ------------------------------
+say "installing ovmem engine + hooks"
+mkdir -p "$OVMEM_DIR/state"
+cp "$PAYLOAD/ovmem.py" "$OVMEM_DIR/ovmem.py"; cp "$PAYLOAD/ovmem-cleanup.py" "$OVMEM_DIR/ovmem-cleanup.py"
+cp "$PAYLOAD/RUNTIME.md" "$OVMEM_DIR/README.md" 2>/dev/null || true
+[ -f "$SETTINGS" ] || echo '{}' > "$SETTINGS"; cp "$SETTINGS" "$SETTINGS.ovmem.bak"
+SS="python3 $OVMEM_DIR/ovmem.py --event session-start"; UP="python3 $OVMEM_DIR/ovmem.py --event user-prompt"
+PC="python3 $OVMEM_DIR/ovmem.py --event pre-compact"; SE="python3 $OVMEM_DIR/ovmem.py --event session-end"
+tmp="$(mktemp)"
+jq --arg ss "$SS" --arg up "$UP" --arg pc "$PC" --arg se "$SE" '
+  .hooks //= {} | .hooks.SessionStart //= [] | .hooks.UserPromptSubmit //= [] | .hooks.PreCompact //= [] | .hooks.SessionEnd //= []
+  | (if any(.hooks.SessionStart[]?.hooks[]?;   .command==$ss) then . else .hooks.SessionStart    += [{hooks:[{type:"command",command:$ss,timeout:12}]}] end)
+  | (if any(.hooks.UserPromptSubmit[]?.hooks[]?;.command==$up) then . else .hooks.UserPromptSubmit += [{hooks:[{type:"command",command:$up,timeout:12}]}] end)
+  | (if any(.hooks.PreCompact[]?.hooks[]?;     .command==$pc) then . else .hooks.PreCompact      += [{hooks:[{type:"command",command:$pc,timeout:25}]}] end)
+  | (if any(.hooks.SessionEnd[]?.hooks[]?;     .command==$se) then . else .hooks.SessionEnd      += [{hooks:[{type:"command",command:$se,timeout:25}]}] end)
+' "$SETTINGS" > "$tmp" && mv "$tmp" "$SETTINGS"
+ok "engine + 4 hooks installed"
+
+# ---- round-trip verify ------------------------------------------------------
+say "verifying end-to-end (commit -> extract)"
+SID="ovmem-install-check"
+curl -s -m 10 -X POST "${H[@]}" -d "{\"session_id\":\"$SID\"}" "$API/sessions" >/dev/null 2>&1 || true
+curl -s -m 12 -X POST "${H[@]}" -d '{"messages":[{"role":"user","content":"Install check: I prefer concise answers."},{"role":"assistant","content":"Noted."}]}' "$API/sessions/$SID/messages/batch" >/dev/null 2>&1 || true
+run_spin "extracting memories (this can take up to ~2 min)" \
+  curl -s -m 150 -X POST "${H[@]}" "$API/sessions/$SID/extract" || true
+EXTRACT="$SPIN_OUT"; [ -n "$EXTRACT" ] || EXTRACT='{}'
+curl -s -m 8 -X DELETE "${H[@]}" "$API/sessions/$SID" >/dev/null 2>&1 || true
+if echo "$EXTRACT" | jq -e '.status=="ok"' >/dev/null 2>&1; then
+  ok "extraction works (memories: $(echo "$EXTRACT" | jq '.result|if type=="array" then length else . end' 2>/dev/null))"
+else
+  warn "extraction did not confirm. Last server errors:"
+  grep -iE "error|denied|expired|invalid|bedrock|token|scope|mismatch" /tmp/openviking.log 2>/dev/null | tail -3 | sed 's/^/     /' || true
+  [ "$PROVIDER" = bedrock ] && warn "Bedrock: check the API key, the region, and that the model is enabled in AWS Bedrock model access."
+fi
+
+[ -n "$TTY" ] && exec 3>&- || true
+echo
+ok "ovmem ready ($PROVIDER · $CHAT_ID · $EMBED_ID). Active on your NEXT Claude Code session."
+echo "   off: OVMEM_DISABLE=1   ·   debug: OVMEM_DEBUG=1 (~/.claude/ovmem/ovmem.log)   ·   prune: python3 $OVMEM_DIR/ovmem-cleanup.py"

package/assets/extensions/ovmem/manage.sh

@@ -0,0 +1,87 @@
+#!/usr/bin/env bash
+# ovmem extension - autonomous RAG long-term memory (OpenViking + 4 Claude Code hooks).
+#
+# All subcommands are real: detect / status / doctor probe a live install;
+# install / update run the full installer (also the reconfigure / provider-switch path,
+# with credential reuse + a safe index rebuild); remove unwires the hooks and deletes the
+# engine, leaving your OpenViking server + memory data intact. See README.md in this folder.
+set -euo pipefail
+
+HERE="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+CLAUDE="${CLAUDE_HOME:-$HOME/.claude}"
+OVMEM_DIR="$CLAUDE/ovmem"
+SETTINGS="$CLAUDE/settings.json"
+OV_HEALTH="http://127.0.0.1:1933/health"
+
+server_up() { curl -s -m 2 "$OV_HEALTH" 2>/dev/null | grep -q '"healthy":true'; }
+
+case "${1:-}" in
+  detect)
+    [ -f "$OVMEM_DIR/ovmem.py" ]
+    ;;
+
+  status)
+    if [ -f "$OVMEM_DIR/ovmem.py" ]; then
+      if server_up; then echo "server up"; else echo "server down"; fi
+    else
+      echo "not installed"
+    fi
+    ;;
+
+  install|update)
+    # install.sh is also the reconfigure/switch path: it detects the current setup,
+    # offers to reuse the credential, and rebuilds the index when the embedding changes.
+    bash "$HERE/install.sh"
+    ;;
+
+  remove)
+    if [ -f "$SETTINGS" ] && command -v jq >/dev/null 2>&1; then
+      cp "$SETTINGS" "$SETTINGS.ovmem.bak"
+      tmp="$(mktemp)"
+      jq '
+        if .hooks then
+          .hooks |= ( to_entries
+            | map(.value |= ( map( .hooks |= map(select((.command // "") | test("ovmem.py --event") | not)) )
+                              | map(select((.hooks | length) > 0)) ))
+            | from_entries )
+        else . end
+      ' "$SETTINGS" > "$tmp" && mv "$tmp" "$SETTINGS"
+      echo "unwired ovmem hooks (backup at $SETTINGS.ovmem.bak)"
+    fi
+    rm -rf "$OVMEM_DIR"
+    echo "removed $OVMEM_DIR"
+    echo "left untouched: the OpenViking server + ~/.openviking (your memory data)."
+    echo "to purge those too: uv tool uninstall openviking ; rm -rf ~/.openviking"
+    ;;
+
+  doctor)
+    echo "engine:   $([ -f "$OVMEM_DIR/ovmem.py" ] && echo "$OVMEM_DIR/ovmem.py" || echo missing)"
+    echo "cleanup:  $([ -f "$OVMEM_DIR/ovmem-cleanup.py" ] && echo present || echo missing)"
+    echo "server:   $(server_up && echo "up (127.0.0.1:1933)" || echo "down")"
+    if [ -f "$SETTINGS" ]; then
+      local_hooks="$(grep -c 'ovmem.py --event' "$SETTINGS" 2>/dev/null || echo 0)"
+      echo "hooks:    $local_hooks/4 wired in settings.json"
+    else
+      echo "hooks:    settings.json not found"
+    fi
+    if [ -f "$HOME/.openviking/ov.conf" ] && command -v jq >/dev/null 2>&1; then
+      prov="$(jq -r '.vlm.provider // "?"' "$HOME/.openviking/ov.conf" 2>/dev/null)"
+      chat="$(jq -r '.vlm.model // "?"' "$HOME/.openviking/ov.conf" 2>/dev/null)"
+      emb="$(jq -r '.embedding.dense.model // "?"' "$HOME/.openviking/ov.conf" 2>/dev/null)"
+      lang="$(jq -r '.output_language_override // "auto"' "$HOME/.openviking/ov.conf" 2>/dev/null)"
+      echo "provider: $prov"
+      echo "chat:     $chat"
+      echo "embed:    $emb"
+      echo "ov.conf:  present (lang=$lang)"
+    elif [ -f "$HOME/.openviking/ov.conf" ]; then
+      echo "ov.conf:  present"
+    else
+      echo "ov.conf:  missing"
+    fi
+    ;;
+
+  *)
+    echo "usage: manage.sh {detect|status|install|update|remove|doctor}" >&2
+    exit 2
+    ;;
+esac

package/assets/extensions/ovmem/models.json

@@ -0,0 +1,24 @@
+{
+  "_meta": {
+    "prices": "USD per 1M tokens (input/output for chat; flat for embedding). Approximate, for guidance only.",
+    "source": "LiteLLM model_prices_and_context_window map",
+    "as_of": "2026-06",
+    "note": "ovmem only runs extraction at PreCompact/SessionEnd, so real cost is cents. Verify prices on the provider's pricing page."
+  },
+  "chat": [
+    { "id": "gpt-4o-mini",       "provider": "openai",  "model": "gpt-4o-mini",                                          "in": 0.15, "out": 0.60,  "ctx": "128k", "tag": "cheap default" },
+    { "id": "gpt-4.1-mini",      "provider": "openai",  "model": "gpt-4.1-mini",                                         "in": 0.40, "out": 1.60,  "ctx": "1M" },
+    { "id": "gpt-4o",            "provider": "openai",  "model": "gpt-4o",                                               "in": 2.50, "out": 10.00, "ctx": "128k" },
+    { "id": "nova-lite",         "provider": "bedrock", "model": "bedrock/us.amazon.nova-lite-v1:0",                     "in": 0.06, "out": 0.24,  "ctx": "300k", "tag": "cheapest" },
+    { "id": "claude-3-5-haiku",  "provider": "bedrock", "model": "bedrock/us.anthropic.claude-3-5-haiku-20241022-v1:0", "in": 0.80, "out": 4.00,  "ctx": "200k" },
+    { "id": "claude-3-5-sonnet", "provider": "bedrock", "model": "bedrock/us.anthropic.claude-3-5-sonnet-20241022-v2:0","in": 3.00, "out": 15.00, "ctx": "200k" },
+    { "id": "claude-sonnet-4-5", "provider": "bedrock", "model": "bedrock/us.anthropic.claude-sonnet-4-5-20250929-v1:0","in": 3.30, "out": 16.50, "ctx": "200k" }
+  ],
+  "embed": [
+    { "id": "text-embedding-3-small", "provider": "openai",  "model": "text-embedding-3-small",              "price": 0.02, "dim": 1536, "tag": "default" },
+    { "id": "text-embedding-3-large", "provider": "openai",  "model": "text-embedding-3-large",              "price": 0.13, "dim": 3072 },
+    { "id": "titan-embed-v2",         "provider": "bedrock", "model": "bedrock/amazon.titan-embed-text-v2:0","price": 0.02, "dim": 1024 },
+    { "id": "cohere-embed-v3",        "provider": "bedrock", "model": "bedrock/cohere.embed-multilingual-v3","price": 0.10, "dim": 1024 },
+    { "id": "titan-embed-v1",         "provider": "bedrock", "model": "bedrock/amazon.titan-embed-text-v1",  "price": 0.10, "dim": 1536 }
+  ]
+}

package/assets/extensions/ovmem/payload/RUNTIME.md

@@ -0,0 +1,121 @@
+# ovmem - autonomous RAG memory for Claude Code
+
+Wires **OpenViking** (hierarchical context DB at `127.0.0.1:1933`) to Claude Code via
+**4 native hooks**, so any session stays optimized without destructive `/compact` or
+`/clear`. All reflection/distillation happens **server-side** (OpenViking calls the LLM),
+so the hooks never spend an LLM call of their own.
+
+## Flow
+
+| Hook | What it does | OpenViking endpoint |
+|---|---|---|
+| **SessionStart** | start the server if down + rehydrate (session summary + long-term memory) | `GET /sessions/{id}/context`, `POST /search/find` |
+| **UserPromptSubmit** | recall: inject memory relevant to the prompt (token-budgeted) | `POST /search/find` |
+| **PreCompact** | flush: send the transcript delta to the OV session and commit **before** compaction destroys it | `messages/batch` + `commit` |
+| **SessionEnd** | flush + commit on session end, then maybe run the weekly cleanup | `messages/batch` + `commit` |
+
+`commit` archives the session and kicks off **long-term memory extraction**
+(preferences / entities / events / agent) asynchronously, using the VLM configured
+in OpenViking (`gpt-4o-mini`).
+
+Read-hook output is **plain text** (not JSON) so it concatenates cleanly with other hooks
+on the same event (e.g. `skill-activator.sh`). The hooks **never** exit non-zero - they
+fail silently (fail-open) and never block the session.
+
+## Files
+
+- `ovmem.py` - single engine, dispatched by `--event {session-start|user-prompt|pre-compact|session-end}`. Pure stdlib, no deps.
+- `ovmem-cleanup.py` - hotness-based lifecycle prune (see below).
+- `state/<session_id>.json` - transcript offset already committed (avoids re-sending).
+- `state/access.json` - local access signal (frequency + recency) feeding the cleanup.
+- `ovmem.log` - debug log (only with `OVMEM_DEBUG=1`).
+
+Registered in `~/.claude/settings.json` under `hooks`.
+
+## Controls (env vars)
+
+```
+OVMEM_DISABLE=1        turn everything off (immediate no-op)
+OVMEM_DEBUG=1          log to ~/.claude/ovmem/ovmem.log
+OVMEM_RECALL_LIMIT=5   max memories injected (default 5)
+OVMEM_RECALL_SCORE=0.28 minimum score to inject (default 0.28)
+OVMEM_CHAR_BUDGET=2200 char cap on the injected block (default 2200)
+OVMEM_TIMEOUT=4        timeout (s) for critical-path calls
+OVMEM_ACCOUNT=default  OVMEM_USER=$USER  OVMEM_AGENT=claude-code
+```
+
+## Accumulation / lifecycle (dedup, reconsolidation, pruning)
+
+The biggest risk for long-term memory is accumulation: duplicates, stale notes, and cold
+episodes polluting retrieval. Division of responsibility:
+
+| Problem | Mechanism | Where |
+|---|---|---|
+| **Duplication** | `MemoryDeduplicator` (LLM) - updates the existing note instead of creating another | **native OpenViking**, on commit |
+| **Obsolescence / contradiction** | `contradicts` / `evolved_from` / `supersedes` relations during extraction | **native OpenViking**, on commit |
+| **Cold-memory accumulation** | `ovmem-cleanup.py` - hotness pruning | **ovmem** (the engine has `MemoryArchiver` but never triggers it) |
+
+Verified empirically: committing the same preference across N sessions yields **1** leaf
+(updated), not N duplicates. Dedup and reconsolidation already work - do not rebuild them.
+
+**Hotness pruning** (`ovmem-cleanup.py`), faithful to the native `MemoryArchiver`:
+
+```
+hotness = sigmoid(log1p(freq)) * exp(-ln2/half_life * age_days)
+freq    = max(OpenViking active_count, local recall count)
+age     = from the more recent of updated_at and last local recall
+archive L2 leaves with hotness < threshold AND age >= min_age  ->  {parent}/_archive/
+```
+
+- The frequency signal comes from **recall**: every memory the hook injects is recorded in
+  `state/access.json` (`record_access`). We do not rely on OpenViking's `active_count` -
+  it does not increment reliably via the REST `used` endpoint in this version.
+- Runs **dry-run by default**; `--apply` moves to `_archive/` (reversible, nothing deleted).
+- Auto-trigger: the **SessionEnd** hook calls `ovmem-cleanup.py --apply` at most **once a
+  week** (gated by `state/last_cleanup`), detached. No cron.
+- Protected (never archived): `identity.md`, `soul.md` (agent core identity).
+
+```bash
+python3 ~/.claude/ovmem/ovmem-cleanup.py            # dry-run: list cold candidates
+python3 ~/.claude/ovmem/ovmem-cleanup.py --apply    # archive them
+```
+
+Tunables: `OVMEM_HOTNESS_THRESHOLD=0.1` `OVMEM_HALF_LIFE_DAYS=7` `OVMEM_MIN_AGE_DAYS=7`
+`OVMEM_CLEANUP_PROTECT="identity.md,soul.md"`.
+
+## Verify
+
+```bash
+# server alive?
+curl -s http://127.0.0.1:1933/health
+
+# manual recall
+echo '{"prompt":"what is my preferred stack?","cwd":"'"$PWD"'"}' \
+  | python3 ~/.claude/ovmem/ovmem.py --event user-prompt
+
+# inspect long-term memory
+curl -s -H "x-api-key: ov-local-dev-key" -H "X-OpenViking-User: $USER" \
+  "http://127.0.0.1:1933/api/v1/fs/tree?uri=viking://user/$USER/memories&level_limit=4"
+```
+
+## OpenViking config dependencies
+
+`~/.openviking/ov.conf` (backup in `ov.conf.bak`):
+- `embedding.dense` -> OpenAI `text-embedding-3-small` (recall / semantic search).
+- `vlm` -> OpenAI `gpt-4o-mini`, **`max_tokens: 16384`** (the model's cap; without it
+  OpenViking requests 32768 and OpenAI rejects with 400).
+- `output_language_override: "en"` -> forces memory extraction and summaries/overviews to
+  English regardless of conversation language.
+- The API key needs the **`model.request`** scope (chat), not just embedding - otherwise
+  extraction fails with 401 and long-term memory never populates.
+
+> Local alternative (no OpenAI): point `vlm.api_base` at an Ollama instance running a model
+> that does real **tool-calling** (qwen2.5:7b+). `nemotron-3-nano:4b` does not follow
+> OpenViking's "operations" protocol.
+
+## Server persistence
+
+- The **SessionStart** hook calls `~/.local/bin/openviking-start` (idempotent) if the
+  server is down - auto-bootstrap.
+- For full uptime independent of Claude Code, add `~/.local/bin/openviking-start` to
+  `~/.bashrc`.