@adverant/nexus-memory-skill 1.3.0 → 2.1.0

package/hooks/recall-memory.sh

@@ -1,9 +1,15 @@
 #!/bin/bash
 #
-# Nexus Memory - Enhanced Recall Memory Hook (GraphRAG v2)
+# Nexus Memory - Optimized Recall Memory Hook (GraphRAG v2)
 # Recalls relevant context from Nexus GraphRAG with entity extraction,
 # knowledge graph traversal, and episodic memory support.
 #
+# PERFORMANCE OPTIMIZED:
+# - Query caching with configurable TTL
+# - Fast dependency checks
+# - Connection keep-alive for faster requests
+# - Optimized JSON parsing
+#
 # Usage:
 #   echo '{"query": "..."}' | recall-memory.sh
 #
@@ -16,12 +22,13 @@
 #
 # GraphRAG Enhancement Options:
 #   NEXUS_INCLUDE_EPISODIC   - Include episodic memory context (default: true)
-#   NEXUS_INCLUDE_DOCUMENTS  - Include document context (default: true)
+#   NEXUS_INCLUDE_DOCUMENTS  - Include document context (default: false for speed)
 #   NEXUS_INCLUDE_ENTITIES   - Include entity information (default: true)
 #   NEXUS_INCLUDE_FACTS      - Include extracted facts (default: true)
-#   NEXUS_INCLUDE_FOLLOWUPS  - Include suggested follow-ups (default: true)
-#   NEXUS_GRAPH_DEPTH        - Multi-hop graph traversal depth (default: 2)
-#   NEXUS_MAX_TOKENS         - Token budget for recall (default: 4000)
+#   NEXUS_INCLUDE_FOLLOWUPS  - Include suggested follow-ups (default: false)
+#   NEXUS_GRAPH_DEPTH        - Multi-hop graph traversal depth (default: 1)
+#   NEXUS_MAX_TOKENS         - Token budget for recall (default: 3000)
+#   NEXUS_CACHE_TTL          - Cache TTL in seconds (default: 600)
 #
 # Output:
 #   Rich JSON object with memories, documents, entities, facts, and suggestions
@@ -36,14 +43,19 @@ COMPANY_ID="${NEXUS_COMPANY_ID:-adverant}"
 APP_ID="${NEXUS_APP_ID:-claude-code}"
 VERBOSE="${NEXUS_VERBOSE:-0}"
 
-# GraphRAG Enhancement Configuration
+# GraphRAG Enhancement Configuration (optimized defaults)
 INCLUDE_EPISODIC="${NEXUS_INCLUDE_EPISODIC:-true}"
-INCLUDE_DOCUMENTS="${NEXUS_INCLUDE_DOCUMENTS:-true}"
+INCLUDE_DOCUMENTS="${NEXUS_INCLUDE_DOCUMENTS:-false}"  # Disabled for speed
 INCLUDE_ENTITIES="${NEXUS_INCLUDE_ENTITIES:-true}"
 INCLUDE_FACTS="${NEXUS_INCLUDE_FACTS:-true}"
-INCLUDE_FOLLOWUPS="${NEXUS_INCLUDE_FOLLOWUPS:-true}"
-GRAPH_DEPTH="${NEXUS_GRAPH_DEPTH:-2}"
-MAX_TOKENS="${NEXUS_MAX_TOKENS:-4000}"
+INCLUDE_FOLLOWUPS="${NEXUS_INCLUDE_FOLLOWUPS:-false}"  # Disabled for speed
+GRAPH_DEPTH="${NEXUS_GRAPH_DEPTH:-1}"  # Reduced for speed
+MAX_TOKENS="${NEXUS_MAX_TOKENS:-3000}"
+
+# Cache configuration
+CACHE_DIR="${HOME}/.claude/session-env/recall-cache"
+CACHE_TTL="${NEXUS_CACHE_TTL:-600}"  # 10 minutes
+SKIP_CACHE="${NEXUS_SKIP_CACHE:-0}"
 
 # Logging function
 log() {
@@ -66,29 +78,23 @@ EMPTY_RESPONSE='{
   "suggested_followups": []
 }'
 
+# =========================================================
+# FAST PATH: Early exit checks
+# =========================================================
+
 # Check for API key (REQUIRED)
 if [[ -z "$NEXUS_API_KEY" ]]; then
-  log_error "NEXUS_API_KEY environment variable is required but not set."
-  log_error "Get your API key from: https://dashboard.adverant.ai/dashboard/api-keys"
-  log_error ""
-  log_error "Set it in your shell profile or Claude Code settings:"
-  log_error "  export NEXUS_API_KEY='your-api-key-here'"
+  log_error "NEXUS_API_KEY not set"
   echo "$EMPTY_RESPONSE"
   exit 1
 fi
 
-# Check dependencies
-if ! command -v jq &> /dev/null; then
-  log_error "jq is required but not installed. Install with: brew install jq"
-  echo "$EMPTY_RESPONSE"
-  exit 1
-fi
+# Fast dependency check
+type jq &>/dev/null || { log_error "jq not available"; echo "$EMPTY_RESPONSE"; exit 1; }
+type curl &>/dev/null || { log_error "curl not available"; echo "$EMPTY_RESPONSE"; exit 1; }
 
-if ! command -v curl &> /dev/null; then
-  log_error "curl is required but not installed."
-  echo "$EMPTY_RESPONSE"
-  exit 1
-fi
+# Ensure cache directory exists
+mkdir -p "$CACHE_DIR" 2>/dev/null
 
 # Read input from stdin
 INPUT=$(cat)
@@ -101,18 +107,24 @@ fi
 
 log "Received input: ${INPUT:0:100}..."
 
-# Extract query from input
-QUERY=$(echo "$INPUT" | jq -r '.query // .prompt // .tool_input.command // "recent context"' 2>/dev/null)
+# =========================================================
+# INPUT PARSING
+# =========================================================
 
-# Get limit if provided
-LIMIT=$(echo "$INPUT" | jq -r '.limit // 10' 2>/dev/null)
+# Extract query and limit with single jq call
+read -r QUERY LIMIT < <(echo "$INPUT" | jq -r '[
+  (.query // .prompt // .tool_input.command // "recent context"),
+  (.limit // 10)
+] | @tsv' 2>/dev/null || echo "recent context	10")
+
+# Validate limit
 if ! [[ "$LIMIT" =~ ^[0-9]+$ ]]; then
   LIMIT=10
 fi
 
 # Get optional filters from input
 FILTERS=$(echo "$INPUT" | jq -c '.filters // {}' 2>/dev/null)
-if [[ "$FILTERS" == "null" ]]; then
+if [[ "$FILTERS" == "null" ]] || [[ -z "$FILTERS" ]]; then
   FILTERS="{}"
 fi
 
@@ -123,7 +135,6 @@ PROJECT_DIR=$(pwd)
 log "Query: $QUERY"
 log "Limit: $LIMIT"
 log "Project: $PROJECT_NAME"
-log "Filters: $FILTERS"
 
 # Skip if no query
 if [[ -z "$QUERY" ]] || [[ "$QUERY" == "null" ]]; then
@@ -132,7 +143,34 @@ if [[ -z "$QUERY" ]] || [[ "$QUERY" == "null" ]]; then
   exit 0
 fi
 
-# Build the enhanced payload for GraphRAG retrieval
+# =========================================================
+# CACHE CHECK
+# =========================================================
+
+# Generate query hash
+QUERY_KEY="${PROJECT_NAME}:${QUERY:0:150}:$LIMIT"
+QUERY_HASH=$(echo -n "$QUERY_KEY" | md5 2>/dev/null || echo -n "$QUERY_KEY" | md5sum 2>/dev/null | cut -d' ' -f1)
+CACHE_FILE="${CACHE_DIR}/recall-${QUERY_HASH}"
+
+# Check cache
+if [[ "$SKIP_CACHE" != "1" ]] && [[ -f "$CACHE_FILE" ]]; then
+  CACHE_AGE=$(( $(date +%s) - $(stat -f %m "$CACHE_FILE" 2>/dev/null || stat -c %Y "$CACHE_FILE" 2>/dev/null || echo 0) ))
+
+  if [[ "$CACHE_AGE" -lt "$CACHE_TTL" ]]; then
+    log "Cache hit (age: ${CACHE_AGE}s)"
+    cat "$CACHE_FILE"
+    exit 0
+  else
+    log "Cache expired"
+    rm -f "$CACHE_FILE" 2>/dev/null
+  fi
+fi
+
+# =========================================================
+# API REQUEST
+# =========================================================
+
+# Build the optimized payload for GraphRAG retrieval
 PAYLOAD=$(jq -n \
   --arg query "$QUERY" \
   --argjson limit "$LIMIT" \
@@ -159,42 +197,40 @@ PAYLOAD=$(jq -n \
     include_entities: $includeEntities,
     include_facts: $includeFacts,
     include_followups: $includeFollowups,
-    enable_graph_traversal: true,
+    enable_graph_traversal: ($graphDepth > 0),
     graph_depth: $graphDepth,
     max_tokens: $maxTokens,
     hybrid_search: true,
-    rerank: true
+    rerank: true,
+    fast_mode: true
   }')
 
-# Use enhanced retrieval endpoint for full GraphRAG features
-# The Gateway exposes this at /api/retrieve/enhanced (routes through smartRouter)
+# Use enhanced retrieval endpoint
 ENDPOINT="$NEXUS_API_URL/api/retrieve/enhanced"
 log "Recalling from $ENDPOINT"
 
-# Search GraphRAG for relevant memories via enhanced retrieval endpoint
-# Authorization: Bearer token for API authentication
-# Headers: X-Company-ID, X-App-ID, X-User-ID (required for tenant context)
+# Make request with optimized settings
 RESPONSE=$(curl -s -w "\n%{http_code}" -X POST "$ENDPOINT" \
   -H "Content-Type: application/json" \
   -H "Authorization: Bearer $NEXUS_API_KEY" \
   -H "X-Company-ID: $COMPANY_ID" \
   -H "X-App-ID: $APP_ID" \
   -H "X-User-ID: ${USER:-unknown}" \
+  -H "Connection: keep-alive" \
   -d "$PAYLOAD" \
-  --max-time 15 2>&1)
+  --connect-timeout 3 \
+  --max-time 10 2>&1)
 
 # Parse response
 HTTP_CODE=$(echo "$RESPONSE" | tail -n1)
 BODY=$(echo "$RESPONSE" | sed '$d')
 
 log "Response code: $HTTP_CODE"
-log "Response body: ${BODY:0:500}..."
 
-# Check for errors - fallback to basic endpoint if enhanced fails
+# Fallback to basic endpoint if enhanced fails
 if [[ "$HTTP_CODE" != "200" ]]; then
   log "Enhanced retrieval failed (HTTP $HTTP_CODE), trying basic endpoint..."
 
-  # Fallback to basic recall endpoint
   BASIC_PAYLOAD=$(jq -n \
     --arg query "$QUERY" \
     --argjson limit "$LIMIT" \
@@ -209,8 +245,10 @@ if [[ "$HTTP_CODE" != "200" ]]; then
     -H "X-Company-ID: $COMPANY_ID" \
     -H "X-App-ID: $APP_ID" \
     -H "X-User-ID: ${USER:-unknown}" \
+    -H "Connection: keep-alive" \
     -d "$BASIC_PAYLOAD" \
-    --max-time 10 2>&1)
+    --connect-timeout 2 \
+    --max-time 8 2>&1)
 
   HTTP_CODE=$(echo "$RESPONSE" | tail -n1)
   BODY=$(echo "$RESPONSE" | sed '$d')
@@ -225,16 +263,19 @@ if [[ "$HTTP_CODE" != "200" ]]; then
 fi
 
 # Validate JSON response
-if ! echo "$BODY" | jq . &>/dev/null; then
+if ! echo "$BODY" | jq -e . &>/dev/null; then
   log_error "Invalid JSON response"
   echo "$EMPTY_RESPONSE"
   exit 0
 fi
 
-# Normalize response to expected structure
-# Handle both direct response and Gateway-wrapped response (.data.results)
+# =========================================================
+# RESPONSE NORMALIZATION
+# =========================================================
+
+# Normalize response to expected structure - single jq pass
 NORMALIZED=$(echo "$BODY" | jq '
-  # Extract the actual result object (handle Gateway wrapper)
+  # Handle Gateway wrapper
   (if .data.results then .data.results else . end) as $result |
   {
     memories: ($result.unified_memories // $result.memories // []),
@@ -244,13 +285,25 @@ NORMALIZED=$(echo "$BODY" | jq '
     episodic_context: ($result.episodic_context // []),
     suggested_followups: ($result.suggested_followups // []),
     query_understanding: ($result.query_understanding // null),
-    confidence_score: ($result.confidence_score // null)
+    confidence_score: ($result.confidence_score // null),
+    context: {
+      project: ($result.context.project // "unknown"),
+      query: ($result.query // "")
+    }
   }
 ')
 
-# Output the normalized response
+# Cache the result
+if [[ "$SKIP_CACHE" != "1" ]]; then
+  echo "$NORMALIZED" > "$CACHE_FILE" 2>/dev/null
+  log "Cached result for ${CACHE_TTL}s"
+
+  # Cleanup old cache files (async)
+  (find "$CACHE_DIR" -type f -name "recall-*" -mmin +$((CACHE_TTL / 60 + 1)) -delete 2>/dev/null &)
+fi
+
+# Output verbose info if enabled
 if [[ "$VERBOSE" == "1" ]]; then
-  # In verbose mode, include additional metadata
   MEMORY_COUNT=$(echo "$NORMALIZED" | jq '.memories | length')
   ENTITY_COUNT=$(echo "$NORMALIZED" | jq '.entities | length')
   FACT_COUNT=$(echo "$NORMALIZED" | jq '.facts | length')
@@ -258,4 +311,4 @@ if [[ "$VERBOSE" == "1" ]]; then
   log "Retrieved: $MEMORY_COUNT memories, $ENTITY_COUNT entities, $FACT_COUNT facts"
 fi
 
-echo "$NORMALIZED"
+echo "$NORMALIZED"

package/hooks/store-memory.sh

@@ -27,6 +27,7 @@
 #   pattern    - Reusable code patterns
 #   preference - User/project preferences
 #   context    - Project-specific context
+#   bead       - Git-backed issue/task tracking (synced via bead-sync.sh)
 #
 
 set -o pipefail
@@ -84,6 +85,85 @@ detect_domain() {
   fi
 }
 
+# Classify content to determine if it should be stored
+# Returns: bead | decision | learning | error_fix | code_change | routine | noise
+classify_content() {
+  local content="$1"
+  local event_type="$2"
+  local content_lower=$(echo "$content" | tr '[:upper:]' '[:lower:]')
+
+  # Bead operations (HIGH priority - always store + trigger sync)
+  # Matches: bd create, bd close, bd work, bd dep, bd list, bd ready, bd show, bd init
+  if echo "$content" | grep -qE '\bbd (create|close|work|dep|list|ready|show|init|update|add|remove|link|unlink|graph|molecule)\b'; then
+    echo "bead"
+    return 0
+  fi
+
+  # Also detect bead-related event type
+  if [[ "$event_type" == "bead" ]]; then
+    echo "bead"
+    return 0
+  fi
+
+  # High-value patterns - ALWAYS store
+  # Decisions: chose X over Y, decided to, instead of, went with
+  if echo "$content_lower" | grep -qE '(decided to|chose|instead of|went with|opted for|prefer|selected|picked)'; then
+    echo "decision"
+    return 0
+  fi
+
+  # Learnings: learned, realized, discovered, found out, turns out
+  if echo "$content_lower" | grep -qE '(learned|realized|discovered|found out|turns out|figured out|now i know|aha|insight)'; then
+    echo "learning"
+    return 0
+  fi
+
+  # Error fixes: fixed, resolved, solved, bug, error, issue
+  if echo "$content_lower" | grep -qE '(fixed|resolved|solved|the (bug|error|issue)|fix for|solution)'; then
+    echo "error_fix"
+    return 0
+  fi
+
+  # Event type overrides for explicit categorization
+  if [[ "$event_type" == "decision" ]] || [[ "$event_type" == "preference" ]]; then
+    echo "decision"
+    return 0
+  fi
+
+  if [[ "$event_type" == "learning" ]]; then
+    echo "learning"
+    return 0
+  fi
+
+  if [[ "$event_type" == "fix" ]] || [[ "$event_type" == "pattern" ]]; then
+    echo "error_fix"
+    return 0
+  fi
+
+  # Medium-value: code changes with explanation
+  if echo "$content_lower" | grep -qE '(modified|updated|changed|added|implemented|created|refactored)'; then
+    echo "code_change"
+    return 0
+  fi
+
+  # Low-value: routine commands - SKIP storage
+  # Common shell commands, git status checks, npm installs
+  if echo "$content" | grep -qE '^(ls |cd |pwd|cat |head |tail |grep |find |git status|git diff|git log|npm install|npm run|yarn |pnpm )'; then
+    echo "routine"
+    return 0
+  fi
+
+  # Noise: very short content, single words, numbers only
+  if [[ ${#content} -lt 30 ]]; then
+    echo "noise"
+    return 0
+  fi
+
+  # Default: store as context
+  echo "context"
+  return 0
+}
+
 # Get previous memory ID for causal chaining
 get_previous_memory_id() {
   if [[ -f "$LAST_MEMORY_FILE" ]]; then
@@ -142,7 +222,7 @@ SESSION_ID=$(echo "$INPUT" | jq -r '.session_id // "unknown"' 2>/dev/null)
 EVENT_TYPE=$(echo "$INPUT" | jq -r '.event_type // "conversation"' 2>/dev/null)
 
 # Validate event type
-VALID_TYPES=("fix" "decision" "learning" "pattern" "preference" "context" "conversation")
+VALID_TYPES=("fix" "decision" "learning" "pattern" "preference" "context" "conversation" "bead")
 TYPE_VALID=0
 for type in "${VALID_TYPES[@]}"; do
   if [[ "$EVENT_TYPE" == "$type" ]]; then
@@ -169,6 +249,16 @@ if [[ -z "$CONTENT" ]] || [[ "$CONTENT" == "null" ]]; then
   exit 0
 fi
 
+# Classify content to determine storage value
+CONTENT_CLASS=$(classify_content "$CONTENT" "$EVENT_TYPE")
+log "Content classification: $CONTENT_CLASS"
+
+# Skip low-value content (routine commands, noise)
+if [[ "$CONTENT_CLASS" == "routine" ]] || [[ "$CONTENT_CLASS" == "noise" ]]; then
+  log "Skipping $CONTENT_CLASS content (low value)"
+  exit 0
+fi
+
 # Truncate very long content (max 10000 chars)
 if [[ ${#CONTENT} -gt 10000 ]]; then
   CONTENT="${CONTENT:0:10000}... [truncated]"
@@ -196,6 +286,7 @@ PAYLOAD=$(jq -n \
   --arg content "$CONTENT" \
   --arg session "$SESSION_ID" \
   --arg event "$EVENT_TYPE" \
+  --arg contentClass "$CONTENT_CLASS" \
   --arg project "$PROJECT_NAME" \
   --arg projectDir "$PROJECT_DIR" \
   --arg timestamp "$TIMESTAMP" \
@@ -207,10 +298,11 @@ PAYLOAD=$(jq -n \
   --argjson entityTypes "$ENTITY_TYPES_JSON" \
   '{
     content: $content,
-    tags: ["claude-code", "session:\($session)", "type:\($event)", "project:\($project)", "domain:\($domain)"],
+    tags: ["claude-code", "session:\($session)", "type:\($event)", "class:\($contentClass)", "project:\($project)", "domain:\($domain)"],
     metadata: {
       sessionId: $session,
       eventType: $event,
+      contentClass: $contentClass,
       projectDir: $projectDir,
       projectName: $project,
       timestamp: $timestamp,
@@ -288,4 +380,15 @@ else
   ) &
 fi
 
+# Trigger bead-sync if this was a bead operation
+# This syncs the local beads to GraphRAG in the background
+if [[ "$CONTENT_CLASS" == "bead" ]]; then
+  BEAD_SYNC_HOOK="${HOME}/.claude/hooks/bead-sync.sh"
+  if [[ -x "$BEAD_SYNC_HOOK" ]]; then
+    log "Triggering bead-sync for bead operation"
+    # Run sync-latest in background to not block the hook
+    ("$BEAD_SYNC_HOOK" sync-latest 2>/dev/null) &
+  fi
+fi
+
 exit 0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adverant/nexus-memory-skill",
-  "version": "1.3.0",
+  "version": "2.1.0",
   "description": "Claude Code skill for persistent memory via Nexus GraphRAG - store and recall memories across all sessions and projects",
   "main": "SKILL.md",
   "type": "module",