Enable Hyperspell Auto-Trace

Enable Hyperspell Auto-Trace

This skill configures a Claude Code SessionEnd hook that automatically sends your conversation transcripts to Hyperspell at the end of each session. Hyperspell extracts procedural memories and emotional context from these traces, so your agents can learn from past sessions.

Instructions

Step 1: Verify Prerequisites

Check that jq is installed:

which jq

If not found, display:

jq is required for the auto-trace hook. Install it with:
  brew install jq    (macOS)
  apt install jq     (Linux)

Wait for the user to install it before continuing.

Step 2: Get the API Key

When the user invoked this skill, they may have passed an API key as an argument: '$1'

If that string is blank or not a valid API key (should start with hs- or hs_), check:

1. The current project's .env.local or .env for HYPERSPELL_API_KEY
2. The user's shell profile (~/.zshrc, ~/.bashrc, ~/.zprofile) for an exported HYPERSPELL_API_KEY

If still not found, ask the user:

Please paste your Hyperspell API key. Get one at https://app.hyperspell.com/api-keys

Step 3: Get the User ID

Check the user's shell profile for HYPERSPELL_USER_ID. If not found, ask:

What user ID should traces be associated with? This can be your email or any identifier.

If the user doesn't have a preference, suggest using their system username (output of whoami).

Step 4: Ensure Environment Variables Are Exported

Check the user's primary shell profile (usually ~/.zshrc on macOS). If HYPERSPELL_API_KEY is not exported there, add it:

export HYPERSPELL_API_KEY="<the-api-key>"

Similarly for HYPERSPELL_USER_ID if the user provided a custom one.

Do not duplicate if the export already exists -- update the existing line instead.

Step 5: Create the Trace Script

Create the directory ~/.hyperspell/ if it doesn't exist, then write the following script to ~/.hyperspell/send-trace.sh:

#!/usr/bin/env bash
# Hyperspell Auto-Trace: Sends Claude Code session transcripts to Hyperspell
# for procedural memory and mood extraction.
#
# Invoked by a Claude Code SessionEnd hook. Reads hook JSON from stdin.

set -euo pipefail

INPUT=$(cat)

SESSION_ID=$(echo "$INPUT" | jq -r '.session_id // empty')
TRANSCRIPT_PATH=$(echo "$INPUT" | jq -r '.transcript_path // empty')

if [ -z "$TRANSCRIPT_PATH" ] || [ ! -f "$TRANSCRIPT_PATH" ]; then
  exit 0
fi

if [ -z "$SESSION_ID" ]; then
  exit 0
fi

if [ -z "${HYPERSPELL_API_KEY:-}" ]; then
  exit 0
fi

HYPERSPELL_API_URL="${HYPERSPELL_API_URL:-https://api.hyperspell.com}"
HYPERSPELL_USER_ID="${HYPERSPELL_USER_ID:-$(whoami)}"

HISTORY=$(cat "$TRANSCRIPT_PATH")

PAYLOAD=$(jq -n \
  --arg session_id "$SESSION_ID" \
  --arg history "$HISTORY" \
  '{
    session_id: $session_id,
    history: $history,
    format: "openclaw",
    extract: ["procedure", "mood"]
  }')

curl -s -X POST "${HYPERSPELL_API_URL}/trace/add" \
  -H "Authorization: Bearer ${HYPERSPELL_API_KEY}" \
  -H "X-As-User: ${HYPERSPELL_USER_ID}" \
  -H "Content-Type: application/json" \
  -d "$PAYLOAD" \
  --max-time 30 \
  > /dev/null 2>&1 || true

exit 0