@adverant/nexus-memory-skill 1.0.0 → 1.1.0

package/README.md

@@ -10,6 +10,8 @@
 
 ### Give Your AI Perfect Recall — Across Every Session, Every Project, Forever
 
+[![npm version](https://img.shields.io/npm/v/@adverant/nexus-memory-skill.svg)](https://www.npmjs.com/package/@adverant/nexus-memory-skill)
+[![npm downloads](https://img.shields.io/npm/dm/@adverant/nexus-memory-skill.svg)](https://www.npmjs.com/package/@adverant/nexus-memory-skill)
 [![MIT License](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
 [![Claude Code](https://img.shields.io/badge/Claude%20Code-Skill-blue.svg)](https://claude.ai/code)
 [![GraphRAG](https://img.shields.io/badge/Powered%20by-GraphRAG-purple.svg)](https://adverant.ai)
@@ -114,20 +116,44 @@ Unlike simple vector search, **GraphRAG** (Graph-based Retrieval Augmented Gener
 
 ## Quick Start
 
-### One-Command Install
+### One-Line Install (Recommended)
 
 ```bash
-git clone https://github.com/adverant/nexus-memory-skill.git ~/.claude/skills/nexus-memory \
-  && cp ~/.claude/skills/nexus-memory/hooks/*.sh ~/.claude/hooks/ \
-  && chmod +x ~/.claude/hooks/*.sh \
-  && echo "✅ Nexus Memory installed!"
+curl -fsSL https://raw.githubusercontent.com/adverant/nexus-memory-skill/main/install.sh | bash
+```
+
+This will:
+1. Install all skill files and hooks
+2. Configure automatic memory (auto-recall + auto-store)
+3. Open a browser to get your free API key
+4. Verify everything works
+
+### Install via npm
+
+```bash
+npm install -g @adverant/nexus-memory-skill
+```
+
+Then run the installer:
+```bash
+$(npm root -g)/@adverant/nexus-memory-skill/install.sh
+```
+
+### Install via Git
+
+```bash
+git clone https://github.com/adverant/nexus-memory-skill.git
+cd nexus-memory-skill
+./install.sh
 ```
 
 ### Verify Installation
 
 ```bash
-ls -la ~/.claude/skills/nexus-memory/SKILL.md && echo "✅ Skill installed"
-ls -la ~/.claude/hooks/store-memory.sh && echo "✅ Hooks installed"
+ls -la ~/.claude/skills/nexus-memory/SKILL.md && echo "Skill installed"
+ls -la ~/.claude/hooks/auto-recall.sh && echo "Auto-recall hook installed"
+ls -la ~/.claude/hooks/store-memory.sh && echo "Store hook installed"
+ls -la ~/.claude/hooks/episode-summary.sh && echo "Episode summary hook installed"
 ```
 
 ### Manual Installation
@@ -140,28 +166,103 @@ ls -la ~/.claude/hooks/store-memory.sh && echo "✅ Hooks installed"
    git clone https://github.com/adverant/nexus-memory-skill.git
    ```
 
-2. **Copy skill to Claude Code**
+2. **Create directories**
    ```bash
-   mkdir -p ~/.claude/skills
-   cp -r nexus-memory-skill ~/.claude/skills/nexus-memory
+   mkdir -p ~/.claude/skills/nexus-memory ~/.claude/hooks
    ```
 
-3. **Install hooks**
+3. **Copy skill and hooks**
    ```bash
+   cp nexus-memory-skill/SKILL.md ~/.claude/skills/nexus-memory/
    cp nexus-memory-skill/hooks/*.sh ~/.claude/hooks/
    chmod +x ~/.claude/hooks/*.sh
    ```
 
-4. **Verify**
+4. **Configure settings.json for automatic memory**
    ```bash
-   cat ~/.claude/skills/nexus-memory/SKILL.md | head -10
+   cat > ~/.claude/settings.json << 'EOF'
+   {
+     "hooks": {
+       "UserPromptSubmit": [
+         {
+           "matcher": "",
+           "hooks": [
+             {"type": "command", "command": "~/.claude/hooks/auto-recall.sh"},
+             {"type": "command", "command": "~/.claude/hooks/store-memory.sh"}
+           ]
+         }
+       ],
+       "PostToolUse": [
+         {
+           "matcher": "",
+           "hooks": [
+             {"type": "command", "command": "~/.claude/hooks/store-memory.sh"},
+             {"type": "command", "command": "~/.claude/hooks/episode-summary.sh"}
+           ]
+         }
+       ]
+     }
+   }
+   EOF
+   ```
+
+5. **Get your API key**
+
+   Visit https://dashboard.adverant.ai/dashboard/api-keys and create a free API key.
+
+6. **Configure API key**
+   ```bash
+   echo "export NEXUS_API_KEY='your-api-key-here'" >> ~/.zshrc
+   source ~/.zshrc
    ```
 
 </details>
 
 ---
 
-## Usage
+## Automatic Memory (Zero-Config)
+
+Once installed, Nexus Memory works **automatically** with no manual intervention:
+
+### What Happens Automatically
+
+| Event | Action | Hook |
+|-------|--------|------|
+| **You send a prompt** | Relevant memories are recalled and injected as context | `auto-recall.sh` |
+| **You send a prompt** | Your prompt is stored for future recall | `store-memory.sh` |
+| **A tool is used** | Tool inputs/outputs are captured | `store-memory.sh` |
+| **Every 10 tool uses** | Conversation segment is summarized as an "episode" | `episode-summary.sh` |
+
+### Example: Automatic Context
+
+When you ask Claude about something you've worked on before:
+
+```
+You: "How did we fix that CORS issue?"
+
+[auto-recall.sh retrieves relevant memories]
+
+Claude: "Based on my memory, you fixed the CORS issue by adding
+credentials: 'include' to fetch options in src/api/client.ts.
+This was needed because the server requires cookie authentication."
+```
+
+**No manual recall needed** — relevant context is automatically provided.
+
+### Environment Variables
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `NEXUS_API_KEY` | (required) | Your API key from dashboard.adverant.ai |
+| `NEXUS_RECALL_LIMIT` | `5` | Number of memories to auto-recall per prompt |
+| `NEXUS_EPISODE_THRESHOLD` | `10` | Tool uses before generating episode summary |
+| `NEXUS_VERBOSE` | `0` | Set to `1` to see debug output |
+
+---
+
+## Manual Usage
+
+You can also manually store and recall memories:
 
 ### Store Memory
 

package/SKILL.md

@@ -8,6 +8,69 @@ allowed-tools: Bash
 
 This skill integrates Claude Code with Nexus GraphRAG for persistent memory across ALL sessions and projects.
 
+## Automatic Memory Features
+
+When properly configured, Nexus Memory provides **fully automatic** memory management:
+
+### Auto-Recall (On Every Prompt)
+- Triggered automatically when you send a prompt
+- Retrieves relevant context from past sessions
+- Enriches Claude's responses with historical knowledge
+- No manual intervention required
+
+### Auto-Store (Continuous Capture)
+- **UserPromptSubmit**: Every prompt you send is captured
+- **PostToolUse**: Every tool execution result is stored
+- Includes project context, timestamps, and session IDs
+- Fire-and-forget async storage (non-blocking)
+
+### Episode Summaries (Periodic)
+- Automatically generated after every 10 tool uses
+- Summarizes conversation segments for long-term memory
+- Captures: topics discussed, decisions made, problems solved
+- Stored with `event_type: "episode"` for easy retrieval
+
+### Configuration
+
+The automatic features are controlled by `~/.claude/settings.json`:
+
+```json
+{
+  "hooks": {
+    "UserPromptSubmit": [
+      {
+        "matcher": "",
+        "hooks": [
+          {"type": "command", "command": "~/.claude/hooks/auto-recall.sh"},
+          {"type": "command", "command": "~/.claude/hooks/store-memory.sh"}
+        ]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "",
+        "hooks": [
+          {"type": "command", "command": "~/.claude/hooks/store-memory.sh"},
+          {"type": "command", "command": "~/.claude/hooks/episode-summary.sh"}
+        ]
+      }
+    ]
+  }
+}
+```
+
+### Environment Variables
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `NEXUS_API_KEY` | (required) | API key from dashboard.adverant.ai |
+| `NEXUS_API_URL` | `https://api.adverant.ai` | API endpoint |
+| `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 |
+
+---
+
 ## IMPORTANT: First-Time Setup Check
 
 **Before doing ANYTHING else, you MUST check if `NEXUS_API_KEY` is configured.**
@@ -28,6 +91,12 @@ if [ -z "$NEXUS_API_KEY" ]; then echo "NOT_CONFIGURED"; else echo "CONFIGURED";
 2. **Ask the user to get their API key:**
    > "Please get your API key from: **https://dashboard.adverant.ai/dashboard/api-keys**
    >
+   > **Important:** When creating your API key in the dashboard:
+   > - Log in or create an account (this automatically creates your organization)
+   > - Navigate to API Keys section
+   > - Click "Create New Key"
+   > - Your key will be automatically scoped to your organization for proper data isolation
+   >
    > Once you have it, paste it here and I'll configure it for you."
 
 3. **When the user provides the API key, configure it automatically:**
@@ -95,24 +164,20 @@ The FileProcessAgent SmartRouter automatically routes files to the appropriate p
 curl -X POST "https://api.adverant.ai/fileprocess/api/process/url" \
   -H "Content-Type: application/json" \
   -H "Authorization: Bearer $NEXUS_API_KEY" \
-  -H "X-Company-ID: adverant" \
-  -H "X-App-ID: claude-code" \
   -d '{
     "fileUrl": "YOUR_URL_HERE",
-    "filename": "filename",
-    "userId": "user-id"
+    "filename": "filename"
   }'
 ```
 
+> **Note:** The `X-Company-ID` header is automatically derived from your API key. Your data is isolated to your account.
+
 ### Upload Files Directly
 
 ```bash
 curl -X POST "https://api.adverant.ai/fileprocess/api/process" \
   -H "Authorization: Bearer $NEXUS_API_KEY" \
-  -H "X-Company-ID: adverant" \
-  -H "X-App-ID: claude-code" \
-  -F "file=@/path/to/file" \
-  -F "userId=user-id"
+  -F "file=@/path/to/file"
 ```
 
 ---
@@ -125,7 +190,7 @@ You can ingest entire GitHub repositories into Nexus memory. This creates a "dig
 - Voyage AI embeddings in Qdrant for semantic search
 - GraphRAG episodic memory for context
 
-### Usage
+### Public Repositories
 
 Submit a GitHub repository URL to the FileProcessAgent:
 
@@ -133,15 +198,45 @@ Submit a GitHub repository URL to the FileProcessAgent:
 curl -X POST "https://api.adverant.ai/fileprocess/api/process/url" \
   -H "Content-Type: application/json" \
   -H "Authorization: Bearer $NEXUS_API_KEY" \
-  -H "X-Company-ID: adverant" \
-  -H "X-App-ID: claude-code" \
   -d '{
     "fileUrl": "https://github.com/owner/repo",
-    "filename": "repository",
-    "userId": "user-id"
+    "filename": "repository"
+  }'
+```
+
+### Private Repositories
+
+For private repositories, you need to provide a GitHub Personal Access Token (PAT) via the `X-GitHub-Token` header:
+
+**Step 1: Create a GitHub PAT**
+1. Go to GitHub → Settings → Developer settings → Personal access tokens → Tokens (classic)
+2. Click "Generate new token (classic)"
+3. Select scopes: `repo` (Full control of private repositories)
+4. Copy the generated token
+
+**Step 2: Set the token as an environment variable (recommended)**
+```bash
+export GITHUB_PAT='ghp_your_token_here'
+```
+
+**Step 3: Ingest the private repository**
+```bash
+curl -X POST "https://api.adverant.ai/fileprocess/api/process/url" \
+  -H "Content-Type: application/json" \
+  -H "Authorization: Bearer $NEXUS_API_KEY" \
+  -H "X-GitHub-Token: $GITHUB_PAT" \
+  -d '{
+    "fileUrl": "https://github.com/owner/private-repo",
+    "filename": "repository"
   }'
 ```
 
+**Security Notes:**
+- Never commit your GitHub PAT to version control
+- Use fine-grained tokens with minimal permissions when possible
+- The token is only used for cloning and is not stored permanently
+- Consider using GitHub App tokens for organization repositories
+
 ### Supported URL Formats
 
 - `https://github.com/owner/repo`
@@ -182,6 +277,47 @@ echo '{"query": "authentication middleware implementation in owner/repo"}' | ~/.
 echo '{"query": "how does the login function work in owner/repo"}' | ~/.claude/hooks/recall-memory.sh
 ```
 
+### Check Sync Status
+
+After starting a repository ingestion, you can check the progress and ETA:
+
+```bash
+# Get repository ID from the ingestion response, then check status
+REPO_ID="your-repo-id-from-response"
+
+curl -s "https://api.adverant.ai/github/api/repositories/$REPO_ID/sync/status" \
+  -H "Authorization: Bearer $NEXUS_API_KEY" | jq '.data.currentJob.progress'
+```
+
+**Response Example:**
+```json
+{
+  "phase": "generating_embeddings",
+  "percentage": 72,
+  "filesProcessed": 450,
+  "totalFiles": 625,
+  "currentFile": "src/services/auth.ts",
+  "message": "Generating embeddings for parsed files",
+  "elapsedTime": "3m 45s",
+  "eta": "1m 30s",
+  "estimatedCompletionAt": "2025-12-29T18:05:00Z"
+}
+```
+
+**Sync Phases:**
+1. `cloning` - Cloning the repository
+2. `parsing` - Discovering and parsing source files
+3. `building_graph` - Building code graph in Neo4j
+4. `generating_embeddings` - Creating Voyage AI embeddings
+5. `extracting` - Extracting blame and history data
+6. `complete` - Sync finished
+
+**Quick Status Check (one-liner):**
+```bash
+curl -s "https://api.adverant.ai/github/api/repositories/$REPO_ID/sync/status" \
+  -H "Authorization: Bearer $NEXUS_API_KEY" | jq '{state: .data.state, phase: .data.currentJob.progress.phase, progress: "\(.data.currentJob.progress.percentage)%", eta: .data.currentJob.progress.eta}'
+```
+
 ---
 
 ## Video & YouTube Processing
@@ -192,8 +328,6 @@ Process videos for transcription, frame analysis, and metadata extraction:
 # YouTube videos
 curl -X POST "https://api.adverant.ai/fileprocess/api/process/url" \
   -H "Authorization: Bearer $NEXUS_API_KEY" \
-  -H "X-Company-ID: adverant" \
-  -H "X-App-ID: claude-code" \
   -H "Content-Type: application/json" \
   -d '{"fileUrl": "https://youtube.com/watch?v=VIDEO_ID", "filename": "video"}'
 ```
@@ -214,10 +348,7 @@ Process geospatial and LiDAR data:
 # GeoJSON, KML, Shapefile, LAS/LAZ files
 curl -X POST "https://api.adverant.ai/fileprocess/api/process" \
   -H "Authorization: Bearer $NEXUS_API_KEY" \
-  -H "X-Company-ID: adverant" \
-  -H "X-App-ID: claude-code" \
-  -F "file=@/path/to/data.geojson" \
-  -F "userId=user-id"
+  -F "file=@/path/to/data.geojson"
 ```
 
 **Supported Formats:**
@@ -242,10 +373,7 @@ Analyze executables and suspicious files:
 # Binary analysis with CyberAgent
 curl -X POST "https://api.adverant.ai/fileprocess/api/process" \
   -H "Authorization: Bearer $NEXUS_API_KEY" \
-  -H "X-Company-ID: adverant" \
-  -H "X-App-ID: claude-code" \
-  -F "file=@/path/to/binary.exe" \
-  -F "userId=user-id"
+  -F "file=@/path/to/binary.exe"
 ```
 
 **Capabilities:**
@@ -271,10 +399,7 @@ Process PDFs, Office documents, and text files:
 # Documents via MageAgent
 curl -X POST "https://api.adverant.ai/fileprocess/api/process" \
   -H "Authorization: Bearer $NEXUS_API_KEY" \
-  -H "X-Company-ID: adverant" \
-  -H "X-App-ID: claude-code" \
-  -F "file=@/path/to/document.pdf" \
-  -F "userId=user-id"
+  -F "file=@/path/to/document.pdf"
 ```
 
 **Supported Formats:**
@@ -350,17 +475,16 @@ The hooks use the Nexus API Gateway at `https://api.adverant.ai`:
 
 ### Authentication
 
-All requests require the following headers:
+All requests require the Authorization header:
 
 ```
 Authorization: Bearer <NEXUS_API_KEY>
-X-Company-ID: adverant
-X-App-ID: claude-code
-X-User-ID: <user>
 ```
 
 The `NEXUS_API_KEY` environment variable provides the Bearer token for authentication.
 
+**Multi-tenancy:** Your company_id and user_id are automatically derived from your API key. There's no need to manually set `X-Company-ID` or `X-User-ID` headers - the backend determines tenant context from your API key ownership.
+
 ## Automatic Storage
 
 The hooks automatically store:

package/hooks/auto-recall.sh

@@ -0,0 +1,161 @@
+#!/bin/bash
+#
+# Nexus Memory - Auto Recall Hook
+# Automatically recalls relevant context from Nexus GraphRAG on every user prompt.
+#
+# This hook is triggered on UserPromptSubmit to enrich Claude's context with
+# relevant memories from past sessions, decisions, fixes, and learnings.
+#
+# Usage (automatic via settings.json):
+#   Triggered on every user prompt submission
+#
+# Environment Variables:
+#   NEXUS_API_KEY     - API key for authentication (REQUIRED)
+#   NEXUS_API_URL     - API endpoint (default: https://api.adverant.ai)
+#   NEXUS_COMPANY_ID  - Company identifier (default: adverant)
+#   NEXUS_APP_ID      - Application identifier (default: claude-code)
+#   NEXUS_VERBOSE     - Set to 1 for debug output
+#   NEXUS_RECALL_LIMIT - Number of memories to recall (default: 5)
+#
+# Output:
+#   Returns relevant memories as context for Claude to use
+#
+
+set -o pipefail
+
+# Configuration with environment variable overrides
+NEXUS_API_KEY="${NEXUS_API_KEY:-}"
+NEXUS_API_URL="${NEXUS_API_URL:-https://api.adverant.ai}"
+COMPANY_ID="${NEXUS_COMPANY_ID:-adverant}"
+APP_ID="${NEXUS_APP_ID:-claude-code}"
+VERBOSE="${NEXUS_VERBOSE:-0}"
+RECALL_LIMIT="${NEXUS_RECALL_LIMIT:-5}"
+
+# Logging function
+log() {
+  if [[ "$VERBOSE" == "1" ]]; then
+    echo "[auto-recall] $1" >&2
+  fi
+}
+
+log_error() {
+  echo "[auto-recall] ERROR: $1" >&2
+}
+
+# Skip if no API key (silently - don't block conversation)
+if [[ -z "$NEXUS_API_KEY" ]]; then
+  log "NEXUS_API_KEY not set, skipping auto-recall"
+  exit 0
+fi
+
+# Check dependencies silently
+if ! command -v jq &> /dev/null; then
+  log "jq not installed, skipping auto-recall"
+  exit 0
+fi
+
+if ! command -v curl &> /dev/null; then
+  log "curl not installed, skipping auto-recall"
+  exit 0
+fi
+
+# Read input from stdin (the user's prompt)
+INPUT=$(cat)
+
+if [[ -z "$INPUT" ]]; then
+  log "No input provided, skipping"
+  exit 0
+fi
+
+log "Received prompt: ${INPUT:0:100}..."
+
+# Extract the user's prompt/query
+QUERY=$(echo "$INPUT" | jq -r '.prompt // .content // .tool_input.command // empty' 2>/dev/null)
+
+# Skip if no query content
+if [[ -z "$QUERY" ]] || [[ "$QUERY" == "null" ]]; then
+  log "No query content, skipping"
+  exit 0
+fi
+
+# Truncate very long queries for recall
+if [[ ${#QUERY} -gt 500 ]]; then
+  QUERY="${QUERY:0:500}"
+  log "Query truncated to 500 characters for recall"
+fi
+
+# Get current project for context
+PROJECT_NAME=$(basename "$(pwd)")
+PROJECT_DIR=$(pwd)
+
+log "Query: ${QUERY:0:100}..."
+log "Project: $PROJECT_NAME"
+log "Limit: $RECALL_LIMIT"
+
+# Build the recall payload with project context
+PAYLOAD=$(jq -n \
+  --arg query "$QUERY" \
+  --argjson limit "$RECALL_LIMIT" \
+  --arg project "$PROJECT_NAME" \
+  '{
+    query: $query,
+    limit: $limit,
+    filters: {
+      project: $project
+    }
+  }')
+
+log "Recalling from $NEXUS_API_URL/api/memory/recall"
+
+# Search GraphRAG for relevant memories via API Gateway
+# Use short timeout to not block conversation
+RESPONSE=$(curl -s -w "\n%{http_code}" -X POST "$NEXUS_API_URL/api/memory/recall" \
+  -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}" \
+  -d "$PAYLOAD" \
+  --max-time 5 2>&1)
+
+# Parse response
+HTTP_CODE=$(echo "$RESPONSE" | tail -n1)
+BODY=$(echo "$RESPONSE" | sed '$d')
+
+log "Response code: $HTTP_CODE"
+
+# Check for errors (silently fail - don't block conversation)
+if [[ "$HTTP_CODE" != "200" ]]; then
+  log "Failed to recall memories (HTTP $HTTP_CODE), continuing without context"
+  exit 0
+fi
+
+# Validate JSON response
+if ! echo "$BODY" | jq . &>/dev/null; then
+  log "Invalid JSON response, continuing without context"
+  exit 0
+fi
+
+# Extract memories and format as context
+MEMORIES=$(echo "$BODY" | jq -r '.memories // []' 2>/dev/null)
+MEMORY_COUNT=$(echo "$MEMORIES" | jq 'length' 2>/dev/null || echo "0")
+
+log "Found $MEMORY_COUNT relevant memories"
+
+# If we have memories, output them as context for Claude
+if [[ "$MEMORY_COUNT" -gt 0 ]] && [[ "$MEMORY_COUNT" != "null" ]]; then
+  # Format memories as readable context
+  echo ""
+  echo "<nexus-memory-context>"
+  echo "The following relevant context was automatically recalled from Nexus Memory:"
+  echo ""
+
+  echo "$MEMORIES" | jq -r '.[] |
+    "- [\(.metadata.eventType // "context")] \(.content | if length > 300 then .[0:300] + "..." else . end)"
+  ' 2>/dev/null | head -n 10
+
+  echo ""
+  echo "</nexus-memory-context>"
+fi
+
+exit 0

package/hooks/episode-summary.sh

@@ -0,0 +1,223 @@
+#!/bin/bash
+#
+# Nexus Memory - Episode Summary Hook
+# Generates periodic summaries of conversation segments as "episodes" for long-term memory.
+#
+# This hook can be triggered:
+# - At session end (Stop hook)
+# - After N tool uses (counter-based)
+# - Manually to summarize current conversation
+#
+# Episodes capture:
+# - Topics discussed
+# - Decisions made
+# - Problems solved
+# - Key learnings
+#
+# Usage:
+#   echo '{"conversation_summary": "...", "tool_count": 5}' | episode-summary.sh
+#
+# Environment Variables:
+#   NEXUS_API_KEY        - API key for authentication (REQUIRED)
+#   NEXUS_API_URL        - API endpoint (default: https://api.adverant.ai)
+#   NEXUS_COMPANY_ID     - Company identifier (default: adverant)
+#   NEXUS_APP_ID         - Application identifier (default: claude-code)
+#   NEXUS_VERBOSE        - Set to 1 for debug output
+#   NEXUS_EPISODE_THRESHOLD - Tool count threshold for episode generation (default: 10)
+#
+
+set -o pipefail
+
+# Configuration with environment variable overrides
+NEXUS_API_KEY="${NEXUS_API_KEY:-}"
+NEXUS_API_URL="${NEXUS_API_URL:-https://api.adverant.ai}"
+COMPANY_ID="${NEXUS_COMPANY_ID:-adverant}"
+APP_ID="${NEXUS_APP_ID:-claude-code}"
+VERBOSE="${NEXUS_VERBOSE:-0}"
+EPISODE_THRESHOLD="${NEXUS_EPISODE_THRESHOLD:-10}"
+
+# State file for tracking tool count
+STATE_DIR="${HOME}/.claude/session-env"
+COUNTER_FILE="${STATE_DIR}/episode_counter"
+
+# Logging function
+log() {
+  if [[ "$VERBOSE" == "1" ]]; then
+    echo "[episode-summary] $1" >&2
+  fi
+}
+
+log_error() {
+  echo "[episode-summary] ERROR: $1" >&2
+}
+
+# Skip if no API key
+if [[ -z "$NEXUS_API_KEY" ]]; then
+  log "NEXUS_API_KEY not set, skipping episode summary"
+  exit 0
+fi
+
+# Check dependencies
+if ! command -v jq &> /dev/null; then
+  log "jq not installed, skipping episode summary"
+  exit 0
+fi
+
+if ! command -v curl &> /dev/null; then
+  log "curl not installed, skipping episode summary"
+  exit 0
+fi
+
+# Ensure state directory exists
+mkdir -p "$STATE_DIR"
+
+# Read input from stdin
+INPUT=$(cat)
+
+if [[ -z "$INPUT" ]]; then
+  log "No input provided"
+  exit 0
+fi
+
+log "Received input: ${INPUT:0:100}..."
+
+# Extract fields from input
+FORCE_SUMMARY=$(echo "$INPUT" | jq -r '.force // false' 2>/dev/null)
+SESSION_END=$(echo "$INPUT" | jq -r '.session_end // false' 2>/dev/null)
+CONTENT=$(echo "$INPUT" | jq -r '.content // .conversation_summary // .prompt // empty' 2>/dev/null)
+
+# Get current counter
+if [[ -f "$COUNTER_FILE" ]]; then
+  CURRENT_COUNT=$(cat "$COUNTER_FILE" 2>/dev/null || echo "0")
+else
+  CURRENT_COUNT=0
+fi
+
+# Increment counter
+NEW_COUNT=$((CURRENT_COUNT + 1))
+echo "$NEW_COUNT" > "$COUNTER_FILE"
+
+log "Tool count: $NEW_COUNT (threshold: $EPISODE_THRESHOLD)"
+
+# Determine if we should generate an episode summary
+SHOULD_SUMMARIZE=false
+
+if [[ "$FORCE_SUMMARY" == "true" ]]; then
+  SHOULD_SUMMARIZE=true
+  log "Forced summary requested"
+elif [[ "$SESSION_END" == "true" ]]; then
+  SHOULD_SUMMARIZE=true
+  log "Session end summary"
+elif [[ "$NEW_COUNT" -ge "$EPISODE_THRESHOLD" ]]; then
+  SHOULD_SUMMARIZE=true
+  log "Threshold reached, generating episode"
+  # Reset counter
+  echo "0" > "$COUNTER_FILE"
+fi
+
+# Exit if we shouldn't summarize
+if [[ "$SHOULD_SUMMARIZE" != "true" ]]; then
+  log "Not generating episode yet (count: $NEW_COUNT/$EPISODE_THRESHOLD)"
+  exit 0
+fi
+
+# Get project context
+PROJECT_NAME=$(basename "$(pwd)")
+PROJECT_DIR=$(pwd)
+TIMESTAMP=$(date -u +%Y-%m-%dT%H:%M:%SZ)
+SESSION_ID=$(date +%Y%m%d-%H%M%S)
+
+# Skip if no content to summarize
+if [[ -z "$CONTENT" ]] || [[ "$CONTENT" == "null" ]]; then
+  # Try to get recent content from session
+  CONTENT="Conversation segment in $PROJECT_NAME project"
+fi
+
+# Truncate very long content
+if [[ ${#CONTENT} -gt 5000 ]]; then
+  CONTENT="${CONTENT:0:5000}... [truncated]"
+fi
+
+# Generate episode summary
+# For now, we create a structured episode from the content
+# Future enhancement: Use LLM to generate smart summaries
+EPISODE_CONTENT=$(cat <<EOF
+[Episode Summary - $PROJECT_NAME]
+Timestamp: $TIMESTAMP
+Project: $PROJECT_NAME
+Directory: $PROJECT_DIR
+
+Session Activity:
+$CONTENT
+
+---
+This episode was automatically generated after $NEW_COUNT tool interactions.
+EOF
+)
+
+log "Generating episode summary for $PROJECT_NAME"
+
+# Build the payload
+PAYLOAD=$(jq -n \
+  --arg content "$EPISODE_CONTENT" \
+  --arg session "$SESSION_ID" \
+  --arg project "$PROJECT_NAME" \
+  --arg projectDir "$PROJECT_DIR" \
+  --arg timestamp "$TIMESTAMP" \
+  --argjson toolCount "$NEW_COUNT" \
+  '{
+    content: $content,
+    tags: ["claude-code", "type:episode", "project:\($project)", "session:\($session)"],
+    metadata: {
+      sessionId: $session,
+      eventType: "episode",
+      projectDir: $projectDir,
+      projectName: $project,
+      timestamp: $timestamp,
+      toolCount: $toolCount,
+      isEpisodeSummary: true
+    }
+  }')
+
+log "Storing episode to $NEXUS_API_URL/api/memory/store"
+
+# Store to GraphRAG via API Gateway
+if [[ "$VERBOSE" == "1" ]]; then
+  # Sync mode with output for debugging
+  RESPONSE=$(curl -s -w "\n%{http_code}" -X POST "$NEXUS_API_URL/api/memory/store" \
+    -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}" \
+    -d "$PAYLOAD" \
+    --max-time 10 2>&1)
+
+  HTTP_CODE=$(echo "$RESPONSE" | tail -n1)
+  BODY=$(echo "$RESPONSE" | sed '$d')
+
+  log "Response code: $HTTP_CODE"
+  log "Response body: $BODY"
+
+  if [[ "$HTTP_CODE" != "200" ]] && [[ "$HTTP_CODE" != "201" ]]; then
+    log_error "Failed to store episode (HTTP $HTTP_CODE)"
+  else
+    log "Episode stored successfully"
+  fi
+else
+  # Async mode (fire-and-forget) for normal operation
+  (curl -s -X POST "$NEXUS_API_URL/api/memory/store" \
+    -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}" \
+    -d "$PAYLOAD" \
+    --max-time 5 &>/dev/null) &
+fi
+
+# Reset counter after successful summary
+echo "0" > "$COUNTER_FILE"
+
+log "Episode summary complete"
+exit 0

package/install.sh

@@ -0,0 +1,355 @@
+#!/bin/bash
+#
+# Nexus Memory - Installation Script
+# Installs the Nexus Memory skill for Claude Code with automatic memory features.
+#
+# Usage:
+#   curl -fsSL https://raw.githubusercontent.com/adverant/nexus-memory-skill/main/install.sh | bash
+#   OR
+#   ./install.sh
+#
+# What this script does:
+# 1. Creates necessary directories (~/.claude/skills, ~/.claude/hooks)
+# 2. Copies skill and hook files
+# 3. Configures settings.json for automatic memory
+# 4. Helps you set up your API key (opens browser if needed)
+# 5. Verifies the installation
+#
+
+set -e
+
+# Colors for output
+RED='\033[0;31m'
+GREEN='\033[0;32m'
+YELLOW='\033[1;33m'
+BLUE='\033[0;34m'
+NC='\033[0m' # No Color
+
+# Logging functions
+log_info() {
+  echo -e "${BLUE}[INFO]${NC} $1"
+}
+
+log_success() {
+  echo -e "${GREEN}[SUCCESS]${NC} $1"
+}
+
+log_warn() {
+  echo -e "${YELLOW}[WARN]${NC} $1"
+}
+
+log_error() {
+  echo -e "${RED}[ERROR]${NC} $1"
+}
+
+# Check for required commands
+check_dependencies() {
+  local missing=()
+
+  if ! command -v curl &> /dev/null; then
+    missing+=("curl")
+  fi
+
+  if ! command -v jq &> /dev/null; then
+    missing+=("jq")
+  fi
+
+  if [ ${#missing[@]} -ne 0 ]; then
+    log_error "Missing required dependencies: ${missing[*]}"
+    echo ""
+    echo "Please install them first:"
+    if [[ "$OSTYPE" == "darwin"* ]]; then
+      echo "  brew install ${missing[*]}"
+    else
+      echo "  sudo apt-get install ${missing[*]}"
+    fi
+    exit 1
+  fi
+}
+
+# Get the script directory (works for both local and remote install)
+get_source_dir() {
+  if [ -d "$(dirname "$0")/hooks" ]; then
+    echo "$(cd "$(dirname "$0")" && pwd)"
+  else
+    # Remote install - download to temp directory
+    local temp_dir=$(mktemp -d)
+    log_info "Downloading Nexus Memory skill..."
+    git clone --depth 1 https://github.com/adverant/nexus-memory-skill.git "$temp_dir" 2>/dev/null || {
+      log_error "Failed to download. Please check your internet connection."
+      exit 1
+    }
+    echo "$temp_dir"
+  fi
+}
+
+# Create required directories
+create_directories() {
+  log_info "Creating directories..."
+  mkdir -p ~/.claude/skills/nexus-memory
+  mkdir -p ~/.claude/hooks
+  mkdir -p ~/.claude/session-env
+}
+
+# Copy skill and hooks
+install_files() {
+  local source_dir="$1"
+
+  log_info "Installing skill file..."
+  cp "$source_dir/SKILL.md" ~/.claude/skills/nexus-memory/SKILL.md
+
+  log_info "Installing hooks..."
+  cp "$source_dir/hooks/store-memory.sh" ~/.claude/hooks/
+  cp "$source_dir/hooks/recall-memory.sh" ~/.claude/hooks/
+  cp "$source_dir/hooks/auto-recall.sh" ~/.claude/hooks/
+  cp "$source_dir/hooks/episode-summary.sh" ~/.claude/hooks/
+
+  # Make hooks executable
+  chmod +x ~/.claude/hooks/store-memory.sh
+  chmod +x ~/.claude/hooks/recall-memory.sh
+  chmod +x ~/.claude/hooks/auto-recall.sh
+  chmod +x ~/.claude/hooks/episode-summary.sh
+
+  # Copy upload-document.sh if it exists
+  if [ -f "$source_dir/hooks/upload-document.sh" ]; then
+    cp "$source_dir/hooks/upload-document.sh" ~/.claude/hooks/
+    chmod +x ~/.claude/hooks/upload-document.sh
+  fi
+
+  log_success "Files installed successfully"
+}
+
+# Configure settings.json
+configure_settings() {
+  log_info "Configuring Claude Code settings..."
+
+  local settings_file=~/.claude/settings.json
+
+  # Create settings.json with automatic memory hooks
+  cat > "$settings_file" << 'EOF'
+{
+  "hooks": {
+    "UserPromptSubmit": [
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "~/.claude/hooks/auto-recall.sh"
+          },
+          {
+            "type": "command",
+            "command": "~/.claude/hooks/store-memory.sh"
+          }
+        ]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "~/.claude/hooks/store-memory.sh"
+          },
+          {
+            "type": "command",
+            "command": "~/.claude/hooks/episode-summary.sh"
+          }
+        ]
+      }
+    ]
+  }
+}
+EOF
+
+  log_success "Settings configured for automatic memory"
+}
+
+# Open browser to get API key
+open_browser() {
+  local url="$1"
+
+  if [[ "$OSTYPE" == "darwin"* ]]; then
+    open "$url" 2>/dev/null || true
+  elif [[ "$OSTYPE" == "linux-gnu"* ]]; then
+    xdg-open "$url" 2>/dev/null || true
+  elif [[ "$OSTYPE" == "msys" ]] || [[ "$OSTYPE" == "cygwin" ]]; then
+    start "$url" 2>/dev/null || true
+  fi
+}
+
+# Setup API key
+setup_api_key() {
+  echo ""
+  log_info "Checking API key configuration..."
+
+  if [ -n "$NEXUS_API_KEY" ]; then
+    log_success "NEXUS_API_KEY is already configured"
+    return 0
+  fi
+
+  echo ""
+  echo -e "${YELLOW}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${NC}"
+  echo -e "${YELLOW}                    API Key Setup Required                               ${NC}"
+  echo -e "${YELLOW}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${NC}"
+  echo ""
+  echo "Nexus Memory requires an API key to store and recall memories."
+  echo ""
+  echo "Steps to get your API key:"
+  echo "  1. A browser window will open to the Nexus Dashboard"
+  echo "  2. Log in or create a free account"
+  echo "  3. Navigate to 'API Keys' section"
+  echo "  4. Click 'Create New Key'"
+  echo "  5. Copy your new API key"
+  echo ""
+
+  read -p "Press Enter to open the dashboard in your browser..."
+
+  open_browser "https://dashboard.adverant.ai/dashboard/api-keys"
+
+  echo ""
+  echo "Paste your API key below (it will be hidden):"
+  read -s api_key
+  echo ""
+
+  if [ -z "$api_key" ]; then
+    log_warn "No API key provided. You can set it later with:"
+    echo "  export NEXUS_API_KEY='your-api-key-here'"
+    return 1
+  fi
+
+  # Detect shell profile
+  local shell_profile=""
+  if [ -f ~/.zshrc ]; then
+    shell_profile=~/.zshrc
+  elif [ -f ~/.bashrc ]; then
+    shell_profile=~/.bashrc
+  elif [ -f ~/.bash_profile ]; then
+    shell_profile=~/.bash_profile
+  fi
+
+  if [ -n "$shell_profile" ]; then
+    # Remove any existing NEXUS_API_KEY line
+    grep -v "^export NEXUS_API_KEY=" "$shell_profile" > "${shell_profile}.tmp" 2>/dev/null && mv "${shell_profile}.tmp" "$shell_profile"
+
+    # Add the new key
+    echo "export NEXUS_API_KEY='$api_key'" >> "$shell_profile"
+    log_success "API key added to $shell_profile"
+  fi
+
+  # Export for current session
+  export NEXUS_API_KEY="$api_key"
+
+  # Verify the key works
+  log_info "Verifying API key..."
+  local response=$(curl -s -o /dev/null -w "%{http_code}" -X POST "https://api.adverant.ai/api/memory/recall" \
+    -H "Content-Type: application/json" \
+    -H "Authorization: Bearer $api_key" \
+    -d '{"query": "test", "limit": 1}' \
+    --max-time 10 2>/dev/null)
+
+  if [ "$response" = "200" ] || [ "$response" = "201" ]; then
+    log_success "API key verified successfully!"
+  elif [ "$response" = "401" ]; then
+    log_warn "API key verification failed (401). Please check your key is correct."
+  else
+    log_warn "Could not verify API key (HTTP $response). Please check your internet connection."
+  fi
+
+  echo ""
+  log_info "To apply the API key in your current terminal, run:"
+  echo "  source $shell_profile"
+}
+
+# Verify installation
+verify_installation() {
+  echo ""
+  log_info "Verifying installation..."
+
+  local errors=0
+
+  if [ -f ~/.claude/skills/nexus-memory/SKILL.md ]; then
+    log_success "Skill file: OK"
+  else
+    log_error "Skill file: MISSING"
+    ((errors++))
+  fi
+
+  for hook in store-memory.sh recall-memory.sh auto-recall.sh episode-summary.sh; do
+    if [ -x ~/.claude/hooks/$hook ]; then
+      log_success "Hook $hook: OK"
+    else
+      log_error "Hook $hook: MISSING or not executable"
+      ((errors++))
+    fi
+  done
+
+  if [ -f ~/.claude/settings.json ]; then
+    log_success "Settings file: OK"
+  else
+    log_error "Settings file: MISSING"
+    ((errors++))
+  fi
+
+  if [ $errors -gt 0 ]; then
+    log_error "Installation completed with $errors error(s)"
+    return 1
+  fi
+
+  return 0
+}
+
+# Print success message
+print_success() {
+  echo ""
+  echo -e "${GREEN}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${NC}"
+  echo -e "${GREEN}               Nexus Memory Installation Complete!                        ${NC}"
+  echo -e "${GREEN}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${NC}"
+  echo ""
+  echo "Automatic Memory Features Enabled:"
+  echo "  - Auto-recall: Relevant memories fetched on every prompt"
+  echo "  - Auto-store: Every prompt and tool use captured"
+  echo "  - Episode summaries: Generated every 10 tool uses"
+  echo ""
+  echo "Manual Commands:"
+  echo "  Store:  echo '{\"content\": \"...\", \"event_type\": \"learning\"}' | ~/.claude/hooks/store-memory.sh"
+  echo "  Recall: echo '{\"query\": \"...\"}' | ~/.claude/hooks/recall-memory.sh"
+  echo ""
+  echo "Environment Variables:"
+  echo "  NEXUS_VERBOSE=1        Enable debug output"
+  echo "  NEXUS_RECALL_LIMIT=10  Number of memories to auto-recall"
+  echo ""
+  echo "Documentation: https://github.com/adverant/nexus-memory-skill"
+  echo ""
+}
+
+# Main installation function
+main() {
+  echo ""
+  echo -e "${BLUE}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${NC}"
+  echo -e "${BLUE}                    Nexus Memory Installer                                ${NC}"
+  echo -e "${BLUE}        Give Your AI Perfect Recall — Across Every Session                ${NC}"
+  echo -e "${BLUE}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${NC}"
+  echo ""
+
+  check_dependencies
+
+  local source_dir
+  source_dir=$(get_source_dir)
+
+  create_directories
+  install_files "$source_dir"
+  configure_settings
+  setup_api_key
+
+  if verify_installation; then
+    print_success
+  else
+    log_error "Installation verification failed. Please check the errors above."
+    exit 1
+  fi
+}
+
+# Run main
+main "$@"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adverant/nexus-memory-skill",
-  "version": "1.0.0",
+  "version": "1.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",
@@ -30,7 +30,8 @@
     "README.md",
     "LICENSE",
     "hooks/",
-    "docs/"
+    "docs/",
+    "install.sh"
   ],
   "publishConfig": {
     "access": "public",