@adverant/nexus-memory-skill 2.0.0 → 2.1.0

package/SKILL.md

@@ -528,3 +528,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