@adverant/nexus-memory-skill 2.0.0 → 2.2.0

package/SKILL.md

@@ -418,6 +418,145 @@ curl -X POST "https://api.adverant.ai/fileprocess/api/process" \
 
 ---
 
+## Upload Document Hook (Full Knowledge Extraction)
+
+The `upload-document.sh` hook provides a streamlined way to upload files with **full auto-discovery and knowledge extraction** enabled by default.
+
+### Auto-Discovery Features (All Enabled by Default)
+
+When you upload a document, the system automatically:
+
+| Feature | Description | Accuracy |
+|---------|-------------|----------|
+| **Smart File Detection** | Magic byte detection for accurate MIME type | 100% |
+| **Intelligent Routing** | Auto-routes to MageAgent, VideoAgent, or CyberAgent | Automatic |
+| **3-Tier OCR Cascade** | Tesseract → GPT-4o Vision → Claude Opus | Auto-escalates |
+| **Layout Analysis** | Document structure preservation | 99.2% |
+| **Table Extraction** | Tables converted to structured data | 97.9% |
+| **Document DNA** | Triple-layer storage (semantic + structural + original) | Full fidelity |
+| **Entity Extraction** | People, places, organizations → Neo4j | Automatic |
+| **Vector Embeddings** | VoyageAI embeddings → Qdrant | Automatic |
+
+### Basic Usage
+
+```bash
+# Upload a single file
+~/.claude/hooks/upload-document.sh ./document.pdf
+
+# Upload and wait for processing to complete
+~/.claude/hooks/upload-document.sh ./book.pdf --wait
+
+# Upload with custom tags for easier recall
+~/.claude/hooks/upload-document.sh ./research.pdf --wait --tags=research,ai,papers
+```
+
+### Batch Upload (Multiple Files)
+
+```bash
+# Upload 3 books at once
+~/.claude/hooks/upload-document.sh book1.pdf book2.pdf book3.pdf --batch --wait
+
+# Upload entire directory of PDFs
+~/.claude/hooks/upload-document.sh ./docs/*.pdf --batch --wait --tags=documentation
+```
+
+### Processing Options
+
+| Flag | Description |
+|------|-------------|
+| `--wait` | Wait for processing to complete and show results |
+| `--batch` | Enable batch mode for multiple files |
+| `--tags=a,b,c` | Add custom tags for easier recall |
+| `--no-entities` | Skip entity extraction (faster, less rich) |
+| `--prefer-speed` | Use faster OCR (may reduce accuracy) |
+| `--poll-interval=N` | Poll interval in seconds (default: 5) |
+
+### Supported File Types
+
+The upload hook supports **ALL file types** through intelligent routing:
+
+- **Documents**: PDF, DOCX, DOC, TXT, MD, HTML, CSV, XML, JSON
+- **Images**: JPEG, PNG, GIF, TIFF, WebP (with OCR)
+- **Videos**: MP4, MOV, AVI, MKV, WebM, FLV
+- **Archives**: ZIP, RAR, 7z, TAR, TAR.GZ, TAR.BZ2
+- **Geospatial**: GeoJSON, Shapefile, GeoTIFF, KML
+- **Point Cloud**: LAS, LAZ, PLY, PCD, E57
+- **Code**: Any programming language
+- **Any binary format** (routed to CyberAgent if suspicious)
+
+### Example Output (--wait mode)
+
+```
+[upload-document] Uploading: research-paper.pdf (12MB)
+Job ID: abc123-def456-ghi789
+
+╔══════════════════════════════════════════════════════════════╗
+║              PROCESSING COMPLETE: research-paper.pdf
+╚══════════════════════════════════════════════════════════════╝
+
+📄 Document Type:     academic_paper
+📑 Pages:             42
+📝 Words:             15,230
+
+🔍 Auto-Discovery Results:
+   • OCR Tier Used:   tesseract (text-based PDF)
+   • Tables Found:    8
+   • Entities:        127
+   • GraphRAG:        true
+
+🏷️  Extracted Entities:
+   • Dr. Emily Chen (person)
+   • Stanford University (organization)
+   • NeurIPS 2024 (event)
+   • Transformer Architecture (concept)
+   ... and 123 more
+
+💡 To recall this content:
+   echo '{"query": "<your search>"}' | recall-memory.sh
+```
+
+### Recalling Uploaded Content
+
+After upload, documents are immediately searchable:
+
+```bash
+# Search by content
+echo '{"query": "transformer architecture research"}' | ~/.claude/hooks/recall-memory.sh
+
+# Search by entity
+echo '{"query": "papers by Dr. Emily Chen"}' | ~/.claude/hooks/recall-memory.sh
+
+# Search by tag
+echo '{"query": "research papers tagged ai"}' | ~/.claude/hooks/recall-memory.sh
+```
+
+### Environment Variables
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `NEXUS_API_KEY` | (required) | API key for authentication |
+| `NEXUS_API_URL` | `https://api.adverant.ai` | API endpoint |
+| `NEXUS_COMPANY_ID` | `adverant` | Company identifier |
+| `NEXUS_APP_ID` | `claude-code` | Application identifier |
+| `NEXUS_VERBOSE` | `0` | Set to `1` for debug output |
+
+### Troubleshooting
+
+**File too large:**
+Maximum file size is 5GB. For larger files, consider splitting or using the direct API.
+
+**Processing takes too long:**
+- Large PDFs with many images trigger OCR cascade
+- Use `--prefer-speed` for faster (but less accurate) processing
+- Increase `--poll-interval` for large batches
+
+**Entities not extracted:**
+- Ensure you didn't use `--no-entities`
+- Check NEXUS_VERBOSE=1 for detailed logs
+- Some file types don't support entity extraction
+
+---
+
 ## Store Memory
 
 ```bash
@@ -528,3 +667,155 @@ Your API key may be invalid or expired.
 If you see "Endpoint not found" errors, the hooks may be using outdated endpoints. Update to:
 - Store: `/api/memory/store`
 - Recall: `/api/memory/recall`
+
+---
+
+## Beads: Git-Backed Issue Tracking
+
+> **Attribution**: Beads (bd) is created by [Steve Yegge](https://github.com/steveyegge).
+> Repository: https://github.com/steveyegge/beads
+> License: See the beads repository for license terms.
+>
+> This integration extends beads with GraphRAG sync capabilities for cross-device memory.
+
+Beads (bd) integrates issue/task tracking with your memory system. Beads are stored both locally in git (`.beads/beads.jsonl`) and synced to GraphRAG as searchable memories. This enables:
+
+- **Local git versioning** of issues (distributed, offline-capable)
+- **Semantic search** across all issues via GraphRAG
+- **Cross-device sync** through bidirectional GraphRAG sync
+- **Dependency tracking** (blocks, relates, discovered-from)
+- **Ready-work queries** (what tasks have no blockers?)
+
+### First-Time Setup
+
+The `bd` binary auto-installs on first use:
+
+```bash
+# Install bd binary (or let it auto-install)
+~/.claude/hooks/bead-sync.sh install
+
+# Initialize beads in your repository
+bd init
+```
+
+### Core Commands
+
+| Command | Description |
+|---------|-------------|
+| `bd list` | List all open beads |
+| `bd ready` | Show beads with no blockers (ready to work) |
+| `bd create "title" -p P1` | Create new bead with priority |
+| `bd work <id>` | Mark bead as in-progress |
+| `bd close <id>` | Mark bead as complete |
+| `bd dep add <a> blocks <b>` | Create dependency (A blocks B) |
+| `bd show <id>` | Show bead details |
+| `bd graph` | Visualize dependency graph |
+
+### Sync Commands
+
+```bash
+# Full bidirectional sync (push local + pull remote)
+~/.claude/hooks/bead-sync.sh sync
+
+# Push local beads to GraphRAG only
+~/.claude/hooks/bead-sync.sh push
+
+# Pull beads from GraphRAG (cross-device sync)
+~/.claude/hooks/bead-sync.sh pull
+
+# Search beads in GraphRAG
+~/.claude/hooks/bead-sync.sh query "authentication bug"
+```
+
+### How Beads Become Memories
+
+Beads are automatically synced to GraphRAG with:
+- `event_type: "bead"`
+- `metadata.bead_id: "bd-xxxx"`
+- `tags: ["bead", "status:open", "priority:P1", "project:my-project"]`
+
+This integration enables:
+- **Auto-recall** surfaces relevant beads when discussing tasks
+- **Semantic search** finds beads by meaning, not just ID
+- **Causal chains** link beads to related code changes
+- **Cross-project** search works across all repositories
+
+### Typical Workflow
+
+1. **See what's ready**: `bd ready`
+2. **Claim a task**: `bd work bd-a1b2`
+3. **Do the work**: (make code changes)
+4. **Complete**: `bd close bd-a1b2`
+5. **Sync to memory**: `~/.claude/hooks/bead-sync.sh sync`
+
+### Dependencies
+
+```bash
+# A blocks B (B can't start until A is done)
+bd dep add bd-a1b2 blocks bd-c3d4
+
+# A relates to B (informational link)
+bd dep add bd-a1b2 relates bd-c3d4
+
+# Discover new issue from existing work
+bd create "Found bug while fixing auth" --discovered-from bd-a1b2
+
+# See dependency graph
+bd graph
+```
+
+### Priority Levels
+
+| Priority | Meaning |
+|----------|---------|
+| P0 | Critical - drop everything |
+| P1 | High - do this sprint |
+| P2 | Medium - normal priority (default) |
+| P3 | Low - nice to have |
+| P4 | Backlog - someday/maybe |
+
+### Multi-Agent Coordination (Molecules)
+
+For coordinating work across multiple agents:
+
+```bash
+# Create a molecule (epic/theme)
+bd mol create "Authentication Overhaul"
+
+# Add beads to molecule
+bd mol add <mol-id> bd-a1b2
+bd mol add <mol-id> bd-c3d4
+
+# Check molecule progress
+bd mol status <mol-id>
+```
+
+### Environment Variables
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `BD_VERSION` | `latest` | Version of bd to install |
+| `NEXUS_VERBOSE` | `0` | Set to 1 for debug output |
+
+### Troubleshooting
+
+**bd command not found:**
+```bash
+# Install or reinstall
+~/.claude/hooks/bead-sync.sh install
+
+# Check installation
+ls -la ~/.local/bin/bd
+```
+
+**Beads not syncing:**
+```bash
+# Check API key is set
+echo $NEXUS_API_KEY
+
+# Manual sync with verbose output
+NEXUS_VERBOSE=1 ~/.claude/hooks/bead-sync.sh sync
+```
+
+**No beads in auto-recall:**
+Make sure you've run `~/.claude/hooks/bead-sync.sh push` at least once to sync local beads to GraphRAG.

package/hooks/auto-recall.sh

@@ -299,6 +299,43 @@ if [[ "$EPISODIC_COUNT" -gt 0 ]] && [[ "$EPISODIC_COUNT" != "null" ]]; then
   echo ""
 fi
 
+# Output active beads (if bd is available and initialized)
+BD_BIN="${HOME}/.local/bin/bd"
+BD_CMD=""
+if [[ -x "$BD_BIN" ]]; then
+  BD_CMD="$BD_BIN"
+elif command -v bd &> /dev/null; then
+  BD_CMD="bd"
+fi
+
+if [[ -n "$BD_CMD" ]]; then
+  # Check if beads is initialized in this directory
+  if [[ -d ".beads" ]] || "$BD_CMD" list &>/dev/null 2>&1; then
+    ACTIVE_BEADS=$("$BD_CMD" list --json 2>/dev/null | jq -c '[.[] | select(.status == "open" or .status == "in_progress")]' 2>/dev/null || echo "[]")
+    ACTIVE_COUNT=$(echo "$ACTIVE_BEADS" | jq 'length' 2>/dev/null || echo "0")
+
+    if [[ "$ACTIVE_COUNT" -gt 0 ]] && [[ "$ACTIVE_COUNT" != "0" ]]; then
+      echo "## Active Beads"
+      echo "$ACTIVE_BEADS" | jq -r '.[:5] | .[] |
+        "- [\(.id // .ID)] \(.title // .Title) (\(.status // .Status))"
+      ' 2>/dev/null
+      echo ""
+    fi
+
+    # Show ready work (no blockers)
+    READY_BEADS=$("$BD_CMD" ready --json 2>/dev/null || echo "[]")
+    READY_COUNT=$(echo "$READY_BEADS" | jq 'length' 2>/dev/null || echo "0")
+
+    if [[ "$READY_COUNT" -gt 0 ]] && [[ "$READY_COUNT" != "0" ]]; then
+      echo "## Ready Work (No Blockers)"
+      echo "$READY_BEADS" | jq -r '.[:3] | .[] |
+        "- [\(.id // .ID)] \(.title // .Title)"
+      ' 2>/dev/null
+      echo ""
+    fi
+  fi
+fi
+
 # Output suggested follow-ups
 FOLLOWUP_COUNT=$(echo "$FOLLOWUPS" | jq 'length' 2>/dev/null || echo "0")
 if [[ "$FOLLOWUP_COUNT" -gt 0 ]] && [[ "$FOLLOWUP_COUNT" != "null" ]] && [[ "$INCLUDE_FOLLOWUPS" == "true" ]]; then