@adverant/nexus-memory-skill 1.3.0 → 2.1.0

package/README.md

@@ -233,10 +233,17 @@ Once installed, Nexus Memory works **automatically** with no manual intervention
 | **A significant tool is used** | Tool inputs/outputs are captured (routine tools skipped) | `episode-summary.sh` |
 | **Every 10 tool uses** | Conversation segment is summarized as an "episode" with relationships | `episode-summary.sh` |
 
-### v1.3.0+ Enhanced Output
+### v2.0.0 Enhanced Memory Intelligence
+
+Major improvements in v2.0.0:
+- **Content Classification** — Automatically filters noise (routine commands, short content)
+- **Entity Extraction** — Fixed bug where entities were filtered out in API responses
+- **Facts Retrieval** — Facts are now properly queried from Neo4j knowledge graph
+- **Token Budget Management** — Intelligent truncation to stay within context limits
+- **Causal Chains** — Episode summaries link to previous episodes for temporal reasoning
 
 The auto-recall now provides rich context including:
-- **Relevant Memories** — Past fixes, decisions, and learnings
+- **Relevant Memories** — Past fixes, decisions, and learnings (filtered for quality)
 - **Entities Mentioned** — Knowledge graph nodes (files, functions, patterns)
 - **Key Facts** — Extracted facts from your coding history
 - **Recent Session Context** — Episodic memory from recent sessions

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

@@ -225,19 +225,43 @@ if [[ "$MEMORY_COUNT" == "0" ]] && [[ "$ENTITY_COUNT" == "0" ]] && [[ "$FACT_COU
   exit 0
 fi
 
+# Token budget management
+# Estimate tokens used (4 chars ~= 1 token)
+# Max output tokens is MAX_TOKENS (default 3000)
+TOKENS_USED=0
+MAX_MEMORY_TOKENS=$((MAX_TOKENS * 60 / 100))  # 60% for memories
+MAX_ENTITY_TOKENS=$((MAX_TOKENS * 15 / 100))  # 15% for entities
+MAX_FACT_TOKENS=$((MAX_TOKENS * 15 / 100))    # 15% for facts
+MAX_EPISODIC_TOKENS=$((MAX_TOKENS * 10 / 100)) # 10% for episodic
+
+log "Token budget: memories=$MAX_MEMORY_TOKENS, entities=$MAX_ENTITY_TOKENS, facts=$MAX_FACT_TOKENS"
+
 # Format output as rich context for Claude
 echo ""
 echo "<nexus-memory-context>"
-echo "The following relevant context was automatically recalled from Nexus Memory (GraphRAG):"
 echo ""
 
-# Output memories
+# Output memories (with token budget)
 if [[ "$MEMORY_COUNT" -gt 0 ]] && [[ "$MEMORY_COUNT" != "null" ]]; then
   echo "## Relevant Memories"
-  echo "$MEMORIES" | jq -r '.[] |
-    "- [\(.metadata.eventType // "context")] \(.content | if length > 300 then .[0:300] + "..." else . end)"
-  ' 2>/dev/null | head -n 10
+  # Process memories with token awareness
+  MEMORY_OUTPUT=""
+  MEMORY_TOKENS=0
+  MAX_CHARS=$((MAX_MEMORY_TOKENS * 4))  # ~4 chars per token
+
+  while IFS= read -r line; do
+    LINE_LEN=${#line}
+    LINE_TOKENS=$((LINE_LEN / 4))
+    if (( MEMORY_TOKENS + LINE_TOKENS > MAX_MEMORY_TOKENS )); then
+      break
+    fi
+    echo "$line"
+    MEMORY_TOKENS=$((MEMORY_TOKENS + LINE_TOKENS))
+  done < <(echo "$MEMORIES" | jq -r '.[] |
+    "- [\(.metadata.eventType // .metadata.contentClass // "context")] \(.content | if length > 250 then .[0:250] + "..." else . end)"
+  ' 2>/dev/null | head -n 8)
   echo ""
+  log "Memory tokens used: $MEMORY_TOKENS"
 fi
 
 # Output entities (knowledge graph nodes)
@@ -275,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