@adverant/nexus-memory-skill 2.3.3 → 2.4.0

package/SKILL.md

@@ -30,6 +30,20 @@ When properly configured, Nexus Memory provides **fully automatic** memory manag
 - Captures: topics discussed, decisions made, problems solved
 - Stored with `event_type: "episode"` for easy retrieval
 
+### Auto-Ingest (File Detection) - NEW in v2.4.0
+- **Automatic file ingestion** when Claude reads files or user mentions file paths
+- Files are processed in the background (non-blocking)
+- Full document storage in PostgreSQL + GraphRAG for semantic search
+- **Triggers**:
+  - When Claude uses the Read tool to access a file
+  - When user mentions file paths in prompts (e.g., `/path/to/file.pdf`)
+- **Excluded directories**: node_modules, .git, __pycache__, dist, build, vendor
+- **Deduplication**: Files only re-ingested if modified since last ingestion
+- **Status notifications**:
+  - Context injection shows "Files queued for ingestion..."
+  - Next prompt shows "✅ file.pdf - now searchable"
+  - Stale documents (>30 days) flagged for re-ingestion
+
 ### Configuration
 
 The automatic features are controlled by `~/.claude/settings.json`:
@@ -42,6 +56,7 @@ The automatic features are controlled by `~/.claude/settings.json`:
         "matcher": "",
         "hooks": [
           {"type": "command", "command": "~/.claude/hooks/auto-recall.sh"},
+          {"type": "command", "command": "~/.claude/hooks/auto-ingest.sh"},
           {"type": "command", "command": "~/.claude/hooks/store-memory.sh"}
         ]
       }
@@ -50,6 +65,7 @@ The automatic features are controlled by `~/.claude/settings.json`:
       {
         "matcher": "",
         "hooks": [
+          {"type": "command", "command": "~/.claude/hooks/auto-ingest.sh"},
           {"type": "command", "command": "~/.claude/hooks/store-memory.sh"},
           {"type": "command", "command": "~/.claude/hooks/episode-summary.sh"}
         ]
@@ -68,6 +84,9 @@ The automatic features are controlled by `~/.claude/settings.json`:
 | `NEXUS_RECALL_LIMIT` | `5` | Number of memories to auto-recall |
 | `NEXUS_EPISODE_THRESHOLD` | `10` | Tool count before episode summary |
 | `NEXUS_VERBOSE` | `0` | Set to `1` for debug output |
+| `NEXUS_AUTO_INGEST` | `1` | Enable automatic file ingestion |
+| `NEXUS_FRESHNESS_DAYS` | `30` | Days before document flagged as stale |
+| `NEXUS_INGEST_POLL_INTERVAL` | `10` | Job status poll interval (seconds) |
 
 ---
 

package/hooks/auto-ingest.sh

@@ -0,0 +1,333 @@
+#!/bin/bash
+#
+# Nexus Memory - Auto Ingest Hook
+# Automatically detects files from Read tool usage or prompt mentions and queues
+# them for background ingestion into GraphRAG.
+#
+# Triggers:
+#   - PostToolUse: When Claude uses the Read tool to access a file
+#   - UserPromptSubmit: When user mentions file paths in their prompt
+#
+# Features:
+#   - Automatic file path detection from tool input and prompts
+#   - Deduplication via mtime-based freshness tracking
+#   - Background ingestion (non-blocking)
+#   - Excluded directory filtering (node_modules, .git, etc.)
+#   - Context injection for immediate user feedback
+#
+# Environment Variables:
+#   NEXUS_API_KEY           - API key for authentication (REQUIRED)
+#   NEXUS_AUTO_INGEST       - Enable/disable auto-ingestion (default: 1)
+#   NEXUS_INGEST_VERBOSE    - Enable debug output (default: 0)
+#   NEXUS_FRESHNESS_DAYS    - Days before re-ingesting a file (default: 30)
+#
+
+set -o pipefail
+
+# Configuration
+NEXUS_API_KEY="${NEXUS_API_KEY:-}"
+AUTO_INGEST="${NEXUS_AUTO_INGEST:-1}"
+VERBOSE="${NEXUS_INGEST_VERBOSE:-${NEXUS_VERBOSE:-0}}"
+FRESHNESS_DAYS="${NEXUS_FRESHNESS_DAYS:-30}"
+
+# State directory
+STATE_DIR="${HOME}/.claude/session-env/auto-ingest"
+INGESTED_FILES="${STATE_DIR}/ingested_files.json"
+PENDING_JOBS="${STATE_DIR}/pending_jobs.json"
+NOTIFIER_PID="${STATE_DIR}/notifier.pid"
+
+# Excluded directories (skip files in these paths)
+EXCLUDED_DIRS=(
+  "node_modules"
+  ".git"
+  "__pycache__"
+  "dist"
+  "build"
+  "vendor"
+  ".venv"
+  "venv"
+  ".next"
+  ".nuxt"
+  "coverage"
+  ".cache"
+  ".npm"
+  ".yarn"
+  "bower_components"
+  "target"
+  "out"
+  ".gradle"
+  ".idea"
+  ".vscode"
+)
+
+# Logging functions
+log() {
+  if [[ "$VERBOSE" == "1" ]]; then
+    echo "[auto-ingest] $1" >&2
+  fi
+}
+
+log_error() {
+  echo "[auto-ingest] ERROR: $1" >&2
+}
+
+# Skip if auto-ingest is disabled
+if [[ "$AUTO_INGEST" != "1" ]]; then
+  log "Auto-ingest disabled (NEXUS_AUTO_INGEST=$AUTO_INGEST)"
+  exit 0
+fi
+
+# Skip if no API key (silently - don't block conversation)
+if [[ -z "$NEXUS_API_KEY" ]]; then
+  log "NEXUS_API_KEY not set, skipping auto-ingest"
+  exit 0
+fi
+
+# Check dependencies silently
+if ! command -v jq &> /dev/null; then
+  log "jq not installed, skipping auto-ingest"
+  exit 0
+fi
+
+# Initialize state directory
+init_state() {
+  mkdir -p "$STATE_DIR"
+  [[ -f "$INGESTED_FILES" ]] || echo "{}" > "$INGESTED_FILES"
+  [[ -f "$PENDING_JOBS" ]] || echo "[]" > "$PENDING_JOBS"
+}
+
+# Check if file is in an excluded directory
+is_excluded() {
+  local file_path="$1"
+
+  for dir in "${EXCLUDED_DIRS[@]}"; do
+    if [[ "$file_path" == *"/$dir/"* ]] || [[ "$file_path" == *"/$dir" ]]; then
+      log "Skipping excluded directory: $dir"
+      return 0
+    fi
+  done
+
+  return 1
+}
+
+# Get file modification time (cross-platform)
+get_mtime() {
+  local file_path="$1"
+  if [[ "$(uname)" == "Darwin" ]]; then
+    stat -f %m "$file_path" 2>/dev/null
+  else
+    stat -c %Y "$file_path" 2>/dev/null
+  fi
+}
+
+# Check if file needs ingestion (not already ingested or modified since)
+needs_ingestion() {
+  local file_path="$1"
+
+  # File must exist
+  if [[ ! -f "$file_path" ]]; then
+    log "File not found: $file_path"
+    return 1
+  fi
+
+  # Check if already pending
+  local is_pending=$(jq -r --arg p "$file_path" '[.[] | select(.path == $p)] | length' "$PENDING_JOBS" 2>/dev/null || echo "0")
+  if [[ "$is_pending" -gt 0 ]]; then
+    log "File already pending: $file_path"
+    return 1
+  fi
+
+  # Get current mtime
+  local current_mtime=$(get_mtime "$file_path")
+  if [[ -z "$current_mtime" ]]; then
+    log "Cannot get mtime for: $file_path"
+    return 1
+  fi
+
+  # Check ingested files index
+  local cached=$(jq -r --arg p "$file_path" '.[$p] // empty' "$INGESTED_FILES" 2>/dev/null)
+
+  if [[ -z "$cached" ]]; then
+    log "File never ingested: $file_path"
+    return 0  # Never ingested, needs ingestion
+  fi
+
+  local cached_mtime=$(echo "$cached" | jq -r '.mtime // 0')
+  local cached_status=$(echo "$cached" | jq -r '.status // "unknown"')
+
+  # Re-ingest if: modified since last ingest, or previous attempt failed
+  if [[ "$current_mtime" != "$cached_mtime" ]]; then
+    log "File modified since last ingest: $file_path (old: $cached_mtime, new: $current_mtime)"
+    return 0
+  fi
+
+  if [[ "$cached_status" == "failed" ]]; then
+    log "Previous ingestion failed, retrying: $file_path"
+    return 0
+  fi
+
+  log "File unchanged and already ingested: $file_path"
+  return 1
+}
+
+# Extract file paths from Read tool input
+extract_read_tool_path() {
+  local input="$1"
+
+  # Check if this is a Read tool PostToolUse event
+  local tool_name=$(echo "$input" | jq -r '.tool_name // empty' 2>/dev/null)
+
+  if [[ "$tool_name" == "Read" ]]; then
+    # Extract file_path from tool_input
+    local file_path=$(echo "$input" | jq -r '.tool_input.file_path // empty' 2>/dev/null)
+    if [[ -n "$file_path" ]] && [[ "$file_path" != "null" ]]; then
+      echo "$file_path"
+    fi
+  fi
+}
+
+# Extract file paths from prompt text using regex
+extract_prompt_paths() {
+  local prompt="$1"
+
+  # Match absolute paths: /foo/bar/file.ext
+  # Match home paths: ~/project/file.ext
+  # Match relative paths: ./foo/bar.ts, ../src/index.js
+  # Require file extension to reduce false positives
+  echo "$prompt" | grep -oE '(~|\.{0,2})?/[A-Za-z0-9_./+-]+\.[A-Za-z0-9]+' 2>/dev/null | while read -r path; do
+    # Expand ~ to home directory
+    if [[ "$path" == ~* ]]; then
+      path="${path/#\~/$HOME}"
+    fi
+
+    # Resolve relative paths
+    if [[ "$path" == ./* ]] || [[ "$path" == ../* ]]; then
+      path=$(cd "$(dirname "$path")" 2>/dev/null && pwd)/$(basename "$path")
+    fi
+
+    # Only output if file exists
+    if [[ -f "$path" ]]; then
+      echo "$path"
+    fi
+  done | sort -u
+}
+
+# Queue file for background ingestion
+queue_for_ingestion() {
+  local file_path="$1"
+  local file_name=$(basename "$file_path")
+
+  log "Queueing for ingestion: $file_path"
+
+  # Call upload-document.sh in background mode
+  local upload_script="${HOME}/.claude/hooks/upload-document.sh"
+
+  if [[ ! -x "$upload_script" ]]; then
+    log_error "upload-document.sh not found or not executable"
+    return 1
+  fi
+
+  # Run in background (fire-and-forget)
+  (
+    "$upload_script" "$file_path" --background 2>/dev/null
+  ) &
+  disown 2>/dev/null || true
+
+  return 0
+}
+
+# Output context injection for user feedback
+emit_context() {
+  local files_queued="$1"
+  local count=$(echo "$files_queued" | wc -l | tr -d ' ')
+
+  if [[ -n "$files_queued" ]] && [[ "$count" -gt 0 ]]; then
+    echo ""
+    echo "<nexus-auto-ingest>"
+    echo "## Files Queued for Memory Ingestion"
+    echo "$files_queued" | while read -r path; do
+      if [[ -n "$path" ]]; then
+        echo "- $(basename "$path") - processing in background..."
+      fi
+    done
+    echo ""
+    echo "Files will be searchable via recall after processing completes."
+    echo "</nexus-auto-ingest>"
+  fi
+}
+
+# Main execution
+main() {
+  init_state
+
+  # Read input from stdin
+  INPUT=$(cat)
+
+  if [[ -z "$INPUT" ]]; then
+    log "No input provided"
+    exit 0
+  fi
+
+  log "Received input: ${INPUT:0:200}..."
+
+  # Collect file paths to process
+  FILES_TO_INGEST=""
+
+  # 1. Check for Read tool usage (PostToolUse)
+  local read_path=$(extract_read_tool_path "$INPUT")
+  if [[ -n "$read_path" ]]; then
+    log "Detected Read tool file: $read_path"
+
+    if ! is_excluded "$read_path" && needs_ingestion "$read_path"; then
+      FILES_TO_INGEST="$read_path"
+    fi
+  fi
+
+  # 2. Check for file paths in prompt (UserPromptSubmit)
+  local prompt=$(echo "$INPUT" | jq -r '.prompt // .content // empty' 2>/dev/null)
+  if [[ -n "$prompt" ]] && [[ "$prompt" != "null" ]]; then
+    log "Scanning prompt for file paths..."
+
+    while IFS= read -r path; do
+      if [[ -n "$path" ]]; then
+        log "Detected prompt file: $path"
+
+        if ! is_excluded "$path" && needs_ingestion "$path"; then
+          if [[ -n "$FILES_TO_INGEST" ]]; then
+            FILES_TO_INGEST="${FILES_TO_INGEST}"$'\n'"${path}"
+          else
+            FILES_TO_INGEST="$path"
+          fi
+        fi
+      fi
+    done < <(extract_prompt_paths "$prompt")
+  fi
+
+  # Remove duplicates
+  if [[ -n "$FILES_TO_INGEST" ]]; then
+    FILES_TO_INGEST=$(echo "$FILES_TO_INGEST" | sort -u)
+  fi
+
+  # Queue files for ingestion
+  QUEUED_FILES=""
+  if [[ -n "$FILES_TO_INGEST" ]]; then
+    while IFS= read -r file_path; do
+      if [[ -n "$file_path" ]]; then
+        if queue_for_ingestion "$file_path"; then
+          if [[ -n "$QUEUED_FILES" ]]; then
+            QUEUED_FILES="${QUEUED_FILES}"$'\n'"${file_path}"
+          else
+            QUEUED_FILES="$file_path"
+          fi
+        fi
+      fi
+    done <<< "$FILES_TO_INGEST"
+  fi
+
+  # Emit context for user feedback
+  emit_context "$QUEUED_FILES"
+
+  exit 0
+}
+
+main

package/hooks/auto-recall.sh

@@ -332,6 +332,67 @@ if [[ "$FOLLOWUP_COUNT" -gt 0 ]] && [[ "$FOLLOWUP_COUNT" != "null" ]] && [[ "$IN
   echo ""
 fi
 
+# === AUTO-INGEST STATUS SECTION ===
+AUTO_INGEST_STATE="${HOME}/.claude/session-env/auto-ingest"
+
+# Show recently completed ingestions (cleared after display)
+if [[ -f "${AUTO_INGEST_STATE}/recent_completions.json" ]]; then
+  COMPLETIONS=$(cat "${AUTO_INGEST_STATE}/recent_completions.json" 2>/dev/null || echo "[]")
+  COMPLETION_COUNT=$(echo "$COMPLETIONS" | jq 'length' 2>/dev/null || echo "0")
+
+  if [[ "$COMPLETION_COUNT" -gt 0 ]] && [[ "$COMPLETION_COUNT" != "0" ]]; then
+    echo "## Recently Ingested Files (Ready for Recall)"
+    echo "$COMPLETIONS" | jq -r '.[] |
+      if .status == "completed" then
+        "- ✅ \(.path | split("/") | .[-1]) - now searchable\(if .entityCount > 0 then " (\(.entityCount) entities)" else "" end)"
+      else
+        "- ❌ \(.path | split("/") | .[-1]) - ingestion failed"
+      end
+    ' 2>/dev/null
+    echo ""
+    # Clear after display
+    echo "[]" > "${AUTO_INGEST_STATE}/recent_completions.json"
+  fi
+fi
+
+# Show pending ingestions
+if [[ -f "${AUTO_INGEST_STATE}/pending_jobs.json" ]]; then
+  PENDING=$(cat "${AUTO_INGEST_STATE}/pending_jobs.json" 2>/dev/null || echo "[]")
+  PENDING_COUNT=$(echo "$PENDING" | jq 'length' 2>/dev/null || echo "0")
+
+  if [[ "$PENDING_COUNT" -gt 0 ]] && [[ "$PENDING_COUNT" != "0" ]]; then
+    echo "## Files Currently Being Processed"
+    echo "$PENDING" | jq -r '.[] | "- ⏳ \(.path | split("/") | .[-1]) - processing..."' 2>/dev/null
+    echo ""
+  fi
+fi
+
+# Document freshness alerts (files ingested > 30 days ago)
+FRESHNESS_DAYS="${NEXUS_FRESHNESS_DAYS:-30}"
+if [[ -f "${AUTO_INGEST_STATE}/ingested_files.json" ]]; then
+  STALE_THRESHOLD=$((FRESHNESS_DAYS * 24 * 60 * 60))  # Convert days to seconds
+  NOW=$(date +%s)
+
+  # Find stale documents (completed but old)
+  STALE_DOCS=$(jq --argjson now "$NOW" --argjson thresh "$STALE_THRESHOLD" '
+    to_entries | map(select(
+      (.value.status == "completed") and
+      (.value.ingestedAt != null) and
+      (($now - (.value.ingestedAt | if type == "string" then (. | split("T")[0] | strptime("%Y-%m-%d") | mktime) else 0 end)) > $thresh)
+    )) | .[0:3]
+  ' "${AUTO_INGEST_STATE}/ingested_files.json" 2>/dev/null || echo "[]")
+
+  STALE_COUNT=$(echo "$STALE_DOCS" | jq 'length' 2>/dev/null || echo "0")
+
+  if [[ "$STALE_COUNT" -gt 0 ]] && [[ "$STALE_COUNT" != "0" ]]; then
+    echo "## Document Freshness Alerts"
+    echo "$STALE_DOCS" | jq -r --argjson days "$FRESHNESS_DAYS" '.[] |
+      "- ⚠️ \(.key | split("/") | .[-1]) - ingested >\($days) days ago, may be outdated"
+    ' 2>/dev/null
+    echo ""
+  fi
+fi
+
 echo "</nexus-memory-context>"
 
 exit 0

package/hooks/ingest-notify.sh

@@ -0,0 +1,316 @@
+#!/bin/bash
+#
+# Nexus Memory - Ingest Notify Daemon
+# Background daemon that polls pending ingestion jobs and updates state files.
+# Started by auto-ingest.sh when files are queued for ingestion.
+#
+# Features:
+#   - Polls job status every 10 seconds
+#   - Updates pending_jobs.json with current status
+#   - Moves completed jobs to recent_completions.json
+#   - Self-terminates when no pending jobs remain
+#   - Prevents duplicate daemon instances
+#
+# Environment Variables:
+#   NEXUS_API_KEY              - API key for authentication (REQUIRED)
+#   NEXUS_API_URL              - API endpoint (default: https://api.adverant.ai)
+#   NEXUS_INGEST_POLL_INTERVAL - Poll interval in seconds (default: 10)
+#   NEXUS_INGEST_VERBOSE       - Enable debug output (default: 0)
+#
+
+set -o pipefail
+
+# Configuration
+NEXUS_API_KEY="${NEXUS_API_KEY:-}"
+NEXUS_API_URL="${NEXUS_API_URL:-https://api.adverant.ai}"
+POLL_INTERVAL="${NEXUS_INGEST_POLL_INTERVAL:-10}"
+VERBOSE="${NEXUS_INGEST_VERBOSE:-${NEXUS_VERBOSE:-0}}"
+
+# State files
+STATE_DIR="${HOME}/.claude/session-env/auto-ingest"
+INGESTED_FILES="${STATE_DIR}/ingested_files.json"
+PENDING_JOBS="${STATE_DIR}/pending_jobs.json"
+RECENT_COMPLETIONS="${STATE_DIR}/recent_completions.json"
+PID_FILE="${STATE_DIR}/notifier.pid"
+
+# Logging functions
+log() {
+  if [[ "$VERBOSE" == "1" ]]; then
+    echo "[ingest-notify] $1" >&2
+  fi
+}
+
+log_error() {
+  echo "[ingest-notify] ERROR: $1" >&2
+}
+
+# Check if another instance is running
+check_existing_instance() {
+  if [[ -f "$PID_FILE" ]]; then
+    local existing_pid=$(cat "$PID_FILE" 2>/dev/null)
+    if [[ -n "$existing_pid" ]] && kill -0 "$existing_pid" 2>/dev/null; then
+      log "Another notifier instance is running (PID: $existing_pid)"
+      exit 0
+    fi
+    # Stale PID file, remove it
+    rm -f "$PID_FILE"
+  fi
+}
+
+# Initialize state files
+init_state() {
+  mkdir -p "$STATE_DIR"
+  [[ -f "$INGESTED_FILES" ]] || echo "{}" > "$INGESTED_FILES"
+  [[ -f "$PENDING_JOBS" ]] || echo "[]" > "$PENDING_JOBS"
+  [[ -f "$RECENT_COMPLETIONS" ]] || echo "[]" > "$RECENT_COMPLETIONS"
+}
+
+# Get file modification time (cross-platform)
+get_mtime() {
+  local file_path="$1"
+  if [[ "$(uname)" == "Darwin" ]]; then
+    stat -f %m "$file_path" 2>/dev/null || echo "0"
+  else
+    stat -c %Y "$file_path" 2>/dev/null || echo "0"
+  fi
+}
+
+# Update ingested files index
+update_ingested_file() {
+  local file_path="$1"
+  local job_id="$2"
+  local status="$3"
+  local entity_count="${4:-0}"
+
+  local mtime=$(get_mtime "$file_path")
+  local now=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
+
+  # Atomic update using temp file
+  jq --arg p "$file_path" \
+     --arg j "$job_id" \
+     --arg s "$status" \
+     --arg m "$mtime" \
+     --arg t "$now" \
+     --argjson e "$entity_count" \
+     '.[$p] = {
+       jobId: $j,
+       status: $s,
+       mtime: ($m | tonumber),
+       ingestedAt: $t,
+       entityCount: $e
+     }' "$INGESTED_FILES" > "${INGESTED_FILES}.tmp" 2>/dev/null \
+    && mv "${INGESTED_FILES}.tmp" "$INGESTED_FILES"
+}
+
+# Add to recent completions
+add_completion() {
+  local file_path="$1"
+  local job_id="$2"
+  local entity_count="${3:-0}"
+  local status="${4:-completed}"
+
+  local now=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
+
+  # Read existing completions
+  local existing=$(cat "$RECENT_COMPLETIONS" 2>/dev/null || echo "[]")
+
+  # Append new completion
+  echo "$existing" | jq --arg p "$file_path" \
+                        --arg j "$job_id" \
+                        --arg t "$now" \
+                        --arg s "$status" \
+                        --argjson e "$entity_count" \
+                        '. + [{
+                          path: $p,
+                          jobId: $j,
+                          completedAt: $t,
+                          status: $s,
+                          entityCount: $e
+                        }]' > "${RECENT_COMPLETIONS}.tmp" 2>/dev/null \
+    && mv "${RECENT_COMPLETIONS}.tmp" "$RECENT_COMPLETIONS"
+}
+
+# Check status of a single job
+check_job_status() {
+  local job_id="$1"
+
+  local response=$(curl -s "$NEXUS_API_URL/fileprocess/api/jobs/$job_id" \
+    -H "Authorization: Bearer $NEXUS_API_KEY" \
+    --max-time 10 2>/dev/null)
+
+  if [[ -z "$response" ]]; then
+    echo '{"status": "unknown", "error": "No response from API"}'
+    return 1
+  fi
+
+  # Extract status from response (handles nested .job.status structure)
+  local status=$(echo "$response" | jq -r '.job.status // .status // "unknown"' 2>/dev/null)
+  local error=$(echo "$response" | jq -r '.job.errorMessage // .error // null' 2>/dev/null)
+  local entity_count=$(echo "$response" | jq -r '.job.metadata.entities // [] | length' 2>/dev/null || echo "0")
+
+  jq -n --arg s "$status" --arg e "$error" --argjson c "$entity_count" \
+    '{status: $s, error: $e, entityCount: $c}'
+}
+
+# Poll all pending jobs
+poll_pending_jobs() {
+  local pending=$(cat "$PENDING_JOBS" 2>/dev/null || echo "[]")
+  local pending_count=$(echo "$pending" | jq 'length' 2>/dev/null || echo "0")
+
+  if [[ "$pending_count" == "0" ]]; then
+    log "No pending jobs"
+    return 0
+  fi
+
+  log "Polling $pending_count pending jobs..."
+
+  # Build new pending list (jobs still in progress)
+  local still_pending="[]"
+
+  # Process each pending job
+  echo "$pending" | jq -c '.[]' 2>/dev/null | while read -r job; do
+    local job_id=$(echo "$job" | jq -r '.jobId')
+    local file_path=$(echo "$job" | jq -r '.path')
+    local file_name=$(basename "$file_path")
+
+    log "Checking job $job_id for $file_name"
+
+    # Get job status
+    local status_json=$(check_job_status "$job_id")
+    local status=$(echo "$status_json" | jq -r '.status')
+    local entity_count=$(echo "$status_json" | jq -r '.entityCount // 0')
+
+    case "$status" in
+      "completed"|"finished"|"success")
+        log "Job completed: $file_name ($entity_count entities)"
+        update_ingested_file "$file_path" "$job_id" "completed" "$entity_count"
+        add_completion "$file_path" "$job_id" "$entity_count" "completed"
+        ;;
+
+      "failed"|"error"|"cancelled")
+        local error=$(echo "$status_json" | jq -r '.error // "Unknown error"')
+        log "Job failed: $file_name - $error"
+        update_ingested_file "$file_path" "$job_id" "failed" "0"
+        add_completion "$file_path" "$job_id" "0" "failed"
+        ;;
+
+      "queued"|"pending"|"processing"|"active"|"triaging"|"routing")
+        log "Job still processing: $file_name ($status)"
+        # Keep in pending list - will be rebuilt after loop
+        ;;
+
+      *)
+        log "Unknown status for $file_name: $status"
+        # Keep in pending list
+        ;;
+    esac
+  done
+
+  # Rebuild pending jobs list (only keep non-completed jobs)
+  local updated_pending=$(cat "$PENDING_JOBS" 2>/dev/null || echo "[]")
+  local new_pending="[]"
+
+  echo "$updated_pending" | jq -c '.[]' 2>/dev/null | while read -r job; do
+    local job_id=$(echo "$job" | jq -r '.jobId')
+    local file_path=$(echo "$job" | jq -r '.path')
+
+    # Check if this job is completed in ingested_files
+    local ingested_status=$(jq -r --arg p "$file_path" '.[$p].status // "pending"' "$INGESTED_FILES" 2>/dev/null)
+
+    if [[ "$ingested_status" != "completed" ]] && [[ "$ingested_status" != "failed" ]]; then
+      # Still pending, keep it
+      new_pending=$(echo "$new_pending" | jq --argjson job "$job" '. + [$job]')
+    fi
+  done
+
+  # Calculate remaining pending jobs
+  local final_pending=$(cat "$PENDING_JOBS" 2>/dev/null || echo "[]")
+  local remaining="[]"
+
+  while IFS= read -r job; do
+    if [[ -n "$job" ]]; then
+      local job_id=$(echo "$job" | jq -r '.jobId')
+      local file_path=$(echo "$job" | jq -r '.path')
+
+      # Check completion status
+      local ingested_status=$(jq -r --arg p "$file_path" '.[$p].status // "pending"' "$INGESTED_FILES" 2>/dev/null)
+
+      if [[ "$ingested_status" != "completed" ]] && [[ "$ingested_status" != "failed" ]]; then
+        remaining=$(echo "$remaining" | jq --argjson j "$job" '. + [$j]')
+      fi
+    fi
+  done < <(echo "$final_pending" | jq -c '.[]' 2>/dev/null)
+
+  echo "$remaining" > "$PENDING_JOBS"
+
+  local remaining_count=$(echo "$remaining" | jq 'length' 2>/dev/null || echo "0")
+  log "Remaining pending jobs: $remaining_count"
+
+  return "$remaining_count"
+}
+
+# Cleanup on exit
+cleanup() {
+  rm -f "$PID_FILE"
+  log "Notifier daemon stopped"
+}
+
+# Main daemon loop
+run_daemon() {
+  log "Starting notifier daemon (PID: $$)"
+  echo $$ > "$PID_FILE"
+
+  trap cleanup EXIT
+
+  local max_iterations=360  # 1 hour max (360 * 10s = 3600s)
+  local iteration=0
+
+  while [[ $iteration -lt $max_iterations ]]; do
+    poll_pending_jobs
+    local remaining=$?
+
+    # Exit if no more pending jobs
+    local pending_count=$(jq 'length' "$PENDING_JOBS" 2>/dev/null || echo "0")
+    if [[ "$pending_count" == "0" ]]; then
+      log "All jobs completed, exiting daemon"
+      break
+    fi
+
+    # Wait before next poll
+    sleep "$POLL_INTERVAL"
+    ((iteration++))
+  done
+
+  log "Daemon loop ended after $iteration iterations"
+}
+
+# Main entry point
+main() {
+  # Skip if no API key
+  if [[ -z "$NEXUS_API_KEY" ]]; then
+    log "NEXUS_API_KEY not set, exiting"
+    exit 0
+  fi
+
+  # Check dependencies
+  if ! command -v jq &> /dev/null; then
+    log_error "jq not installed"
+    exit 1
+  fi
+
+  if ! command -v curl &> /dev/null; then
+    log_error "curl not installed"
+    exit 1
+  fi
+
+  # Check for existing instance
+  check_existing_instance
+
+  # Initialize state
+  init_state
+
+  # Run daemon
+  run_daemon
+}
+
+main

package/hooks/upload-document.sh

@@ -37,6 +37,7 @@
 #   --tags=a,b,c      Add custom tags for recall (comma-separated)
 #   --no-entities     Skip entity extraction to knowledge graph
 #   --prefer-speed    Use faster OCR (may reduce accuracy for scanned docs)
+#   --background      Fire-and-forget mode for auto-ingestion (non-blocking)
 #
 # Environment Variables:
 #   NEXUS_API_KEY     - API key for authentication (REQUIRED)
@@ -158,6 +159,7 @@ BATCH_MODE=0
 CUSTOM_TAGS=""
 EXTRACT_ENTITIES=1
 PREFER_SPEED=0
+BACKGROUND_MODE=0
 
 while [[ $# -gt 0 ]]; do
   case $1 in
@@ -185,6 +187,10 @@ while [[ $# -gt 0 ]]; do
       PREFER_SPEED=1
       shift
       ;;
+    --background)
+      BACKGROUND_MODE=1
+      shift
+      ;;
     --help|-h)
       print_usage
       exit 0
@@ -493,6 +499,77 @@ wait_for_job() {
 # MAIN EXECUTION
 # ============================================================================
 
+# Background mode: Fire-and-forget for auto-ingestion
+if [[ "$BACKGROUND_MODE" == "1" ]]; then
+  # Only process first file in background mode
+  FILE_PATH="${FILES[0]}"
+  FILE_NAME=$(basename "$FILE_PATH")
+
+  log "Background mode: uploading $FILE_NAME"
+
+  # Run upload in background subshell
+  (
+    # Suppress output in background mode
+    UPLOAD_OUTPUT=$(upload_file "$FILE_PATH" 2>&1)
+    UPLOAD_EXIT_CODE=$?
+
+    if [[ $UPLOAD_EXIT_CODE -eq 0 ]]; then
+      # Extract job ID from output
+      JOB_ID=$(echo "$UPLOAD_OUTPUT" | grep -E '^[a-f0-9-]+$' | tail -1)
+      if [[ -z "$JOB_ID" ]]; then
+        JOB_ID=$(echo "$UPLOAD_OUTPUT" | grep "Job ID:" | sed 's/Job ID: //' | tr -d ' ')
+      fi
+
+      if [[ -n "$JOB_ID" ]]; then
+        # Update state files for auto-ingest tracking
+        STATE_DIR="${HOME}/.claude/session-env/auto-ingest"
+        PENDING_FILE="${STATE_DIR}/pending_jobs.json"
+        INGESTED_FILE="${STATE_DIR}/ingested_files.json"
+
+        mkdir -p "$STATE_DIR"
+        [[ -f "$PENDING_FILE" ]] || echo "[]" > "$PENDING_FILE"
+        [[ -f "$INGESTED_FILE" ]] || echo "{}" > "$INGESTED_FILE"
+
+        # Add to pending jobs
+        NOW=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
+        jq --arg j "$JOB_ID" --arg p "$FILE_PATH" --arg t "$NOW" \
+          '. + [{jobId: $j, path: $p, startTime: $t}]' "$PENDING_FILE" > "${PENDING_FILE}.tmp" 2>/dev/null \
+          && mv "${PENDING_FILE}.tmp" "$PENDING_FILE"
+
+        # Mark as processing in ingested files
+        if [[ "$(uname)" == "Darwin" ]]; then
+          MTIME=$(stat -f %m "$FILE_PATH" 2>/dev/null || echo "0")
+        else
+          MTIME=$(stat -c %Y "$FILE_PATH" 2>/dev/null || echo "0")
+        fi
+
+        jq --arg p "$FILE_PATH" --arg j "$JOB_ID" --arg m "$MTIME" --arg t "$NOW" \
+          '.[$p] = {jobId: $j, status: "processing", mtime: ($m | tonumber), ingestedAt: $t}' \
+          "$INGESTED_FILE" > "${INGESTED_FILE}.tmp" 2>/dev/null \
+          && mv "${INGESTED_FILE}.tmp" "$INGESTED_FILE"
+
+        # Start notifier daemon if not running
+        NOTIFIER_SCRIPT="${HOME}/.claude/hooks/ingest-notify.sh"
+        PID_FILE="${STATE_DIR}/notifier.pid"
+
+        if [[ -x "$NOTIFIER_SCRIPT" ]]; then
+          if [[ ! -f "$PID_FILE" ]] || ! kill -0 "$(cat "$PID_FILE" 2>/dev/null)" 2>/dev/null; then
+            "$NOTIFIER_SCRIPT" &
+          fi
+        fi
+
+        log "Background upload queued: $FILE_NAME (job: $JOB_ID)"
+      fi
+    else
+      log "Background upload failed: $FILE_NAME"
+    fi
+  ) &
+  disown 2>/dev/null || true
+
+  # Exit immediately (non-blocking)
+  exit 0
+fi
+
 # Track all job IDs for batch mode
 JOB_IDS=()
 FILE_NAMES=()

package/install.sh

@@ -116,6 +116,29 @@ install_files() {
     chmod +x ~/.claude/hooks/upload-document.sh
   fi
 
+  # Copy auto-ingest hooks (v2.4.0+)
+  if [ -f "$source_dir/hooks/auto-ingest.sh" ]; then
+    cp "$source_dir/hooks/auto-ingest.sh" ~/.claude/hooks/
+    chmod +x ~/.claude/hooks/auto-ingest.sh
+  fi
+
+  if [ -f "$source_dir/hooks/ingest-notify.sh" ]; then
+    cp "$source_dir/hooks/ingest-notify.sh" ~/.claude/hooks/
+    chmod +x ~/.claude/hooks/ingest-notify.sh
+  fi
+
+  # Copy API key helper if it exists
+  if [ -f "$source_dir/hooks/api-key-helper.sh" ]; then
+    cp "$source_dir/hooks/api-key-helper.sh" ~/.claude/hooks/
+    chmod +x ~/.claude/hooks/api-key-helper.sh
+  fi
+
+  # Copy bead-sync hook if it exists
+  if [ -f "$source_dir/hooks/bead-sync.sh" ]; then
+    cp "$source_dir/hooks/bead-sync.sh" ~/.claude/hooks/
+    chmod +x ~/.claude/hooks/bead-sync.sh
+  fi
+
   log_success "Files installed successfully"
 }
 
@@ -125,7 +148,7 @@ configure_settings() {
 
   local settings_file=~/.claude/settings.json
 
-  # Create settings.json with automatic memory hooks
+  # Create settings.json with automatic memory hooks (including auto-ingest)
   cat > "$settings_file" << 'EOF'
 {
   "hooks": {
@@ -137,6 +160,10 @@ configure_settings() {
             "type": "command",
             "command": "~/.claude/hooks/auto-recall.sh"
           },
+          {
+            "type": "command",
+            "command": "~/.claude/hooks/auto-ingest.sh"
+          },
           {
             "type": "command",
             "command": "~/.claude/hooks/store-memory.sh"
@@ -148,6 +175,10 @@ configure_settings() {
       {
         "matcher": "",
         "hooks": [
+          {
+            "type": "command",
+            "command": "~/.claude/hooks/auto-ingest.sh"
+          },
           {
             "type": "command",
             "command": "~/.claude/hooks/store-memory.sh"
@@ -310,6 +341,7 @@ print_success() {
   echo "Automatic Memory Features Enabled:"
   echo "  - Auto-recall: Relevant memories fetched on every prompt"
   echo "  - Auto-store: Every prompt and tool use captured"
+  echo "  - Auto-ingest: Files read by Claude auto-ingested to memory"
   echo "  - Episode summaries: Generated every 10 tool uses"
   echo ""
   echo "Manual Commands:"
@@ -319,6 +351,8 @@ print_success() {
   echo "Environment Variables:"
   echo "  NEXUS_VERBOSE=1        Enable debug output"
   echo "  NEXUS_RECALL_LIMIT=10  Number of memories to auto-recall"
+  echo "  NEXUS_AUTO_INGEST=0    Disable auto-ingestion of files"
+  echo "  NEXUS_FRESHNESS_DAYS=30  Days before document flagged as stale"
   echo ""
   echo "Documentation: https://github.com/adverant/nexus-memory-skill"
   echo ""

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adverant/nexus-memory-skill",
-  "version": "2.3.3",
+  "version": "2.4.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",