---
name: nexus-memory
description: Store and recall memories from Nexus GraphRAG across all projects. Use when you need to save important context, decisions, or learnings that should persist across sessions, or when you need to retrieve historical information from past work.
allowed-tools: Bash
---

# Nexus Memory Integration (Global)

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

### 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`:

```json
{
  "hooks": {
    "UserPromptSubmit": [
      {
        "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"}
        ]
      }
    ],
    "PostToolUse": [
      {
        "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"}
        ]
      }
    ]
  }
}
```

### 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 |
| `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) |

---

## IMPORTANT: First-Time Setup Check

**Before doing ANYTHING else, you MUST check if `NEXUS_API_KEY` is configured.**

Run this command first:

```bash
if [ -z "$NEXUS_API_KEY" ]; then echo "NOT_CONFIGURED"; else echo "CONFIGURED"; fi
```

### If NOT_CONFIGURED:

**STOP and help the user set up their API key.** Do NOT proceed with any memory operations.

1. **Tell the user:**
   > "The Nexus Memory skill requires an API key to authenticate with the Nexus GraphRAG service. Let me help you set this up."

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:**

   ```bash
   # Add to shell profile (detect which one exists)
   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" && mv "${SHELL_PROFILE}.tmp" "$SHELL_PROFILE"
     # Add the new key
     echo "export NEXUS_API_KEY='USER_PROVIDED_KEY_HERE'" >> "$SHELL_PROFILE"
     echo "Added NEXUS_API_KEY to $SHELL_PROFILE"
   fi
   ```

4. **Export it for the current session:**
   ```bash
   export NEXUS_API_KEY='USER_PROVIDED_KEY_HERE'
   ```

5. **Verify the setup worked:**
   ```bash
   if [ -z "$NEXUS_API_KEY" ]; then echo "FAILED"; else echo "SUCCESS - API key configured"; fi
   ```

6. **Only after successful setup, proceed with the user's original request.**

### If CONFIGURED:

Proceed with the memory operation the user requested.

---

## When to Use

- **Store Memory**: When you learn something important, make a significant decision, or complete a task that future sessions should know about
- **Recall Memory**: When you need context about past work, previous decisions, or historical information
- **Process Files**: When you need to process documents, videos, geospatial data, binaries, or other files into memory

## File Processing (SmartRouter)

The FileProcessAgent SmartRouter automatically routes files to the appropriate processing service based on content type:

| File Type | Target Service | Capabilities |
|-----------|----------------|--------------|
| **GitHub Repos** | GitHub Manager | AST parsing, code graphs, embeddings |
| **Videos/YouTube** | VideoAgent | Frame extraction, transcription, metadata |
| **Geospatial** | GeoAgent | GeoJSON, KML, Shapefile, LiDAR processing |
| **Binaries/Executables** | CyberAgent | Security analysis, decompilation, threat detection |
| **Documents** | MageAgent | OCR, text extraction, structure analysis |
| **Archives** | FileProcess | ZIP/TAR extraction, recursive processing |

### Process Any File via URL

```bash
curl -X POST "https://api.adverant.ai/fileprocess/api/process/url" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $NEXUS_API_KEY" \
  -d '{
    "fileUrl": "YOUR_URL_HERE",
    "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" \
  -F "file=@/path/to/file"
```

---

## GitHub Repository Ingestion

You can ingest entire GitHub repositories into Nexus memory. This creates a "digital twin" of the repository with:
- AST parsing (Tree-sitter) for code structure
- Code graphs in Neo4j for relationship queries
- Voyage AI embeddings in Qdrant for semantic search
- GraphRAG episodic memory for context

### Public Repositories

Submit a GitHub repository URL to the FileProcessAgent:

```bash
curl -X POST "https://api.adverant.ai/fileprocess/api/process/url" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $NEXUS_API_KEY" \
  -d '{
    "fileUrl": "https://github.com/owner/repo",
    "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`
- `https://github.com/owner/repo.git`
- `https://github.com/owner/repo/tree/branch`
- `git@github.com:owner/repo.git`

### Response

```json
{
  "success": true,
  "message": "GitHub repository connected and syncing into memory",
  "processingMethod": "github_manager_repo_ingestion",
  "repository": {
    "id": "uuid",
    "fullName": "owner/repo",
    "status": "synced",
    "isNewConnection": true
  },
  "syncStats": {
    "totalFiles": 150,
    "parsedFiles": 120,
    "entitiesExtracted": 500
  }
}
```

### After Ingestion

Once ingested, you can query the repository using natural language:

```bash
# Search for code patterns
echo '{"query": "authentication middleware implementation in owner/repo"}' | ~/.claude/hooks/recall-memory.sh

# Find specific functions
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

Process videos for transcription, frame analysis, and metadata extraction:

```bash
# YouTube videos
curl -X POST "https://api.adverant.ai/fileprocess/api/process/url" \
  -H "Authorization: Bearer $NEXUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"fileUrl": "https://youtube.com/watch?v=VIDEO_ID", "filename": "video"}'
```

**Capabilities:**
- Audio transcription (Whisper)
- Frame extraction and analysis
- Metadata extraction
- Support for MP4, MKV, WebM, AVI, MOV

---

## Geospatial File Processing

Process geospatial and LiDAR data:

```bash
# GeoJSON, KML, Shapefile, LAS/LAZ files
curl -X POST "https://api.adverant.ai/fileprocess/api/process" \
  -H "Authorization: Bearer $NEXUS_API_KEY" \
  -F "file=@/path/to/data.geojson"
```

**Supported Formats:**
- **Vector:** GeoJSON, KML, KMZ, Shapefile (.shp/.shx/.dbf), GeoPackage
- **Raster:** GeoTIFF, ECW, JPEG2000
- **Point Cloud:** LAS, LAZ, E57, PLY, XYZ
- **3D:** CityGML, IFC, COLLADA

**Capabilities:**
- Coordinate transformation
- Feature extraction
- Spatial indexing
- Point cloud classification

---

## Binary & Security Analysis

Analyze executables and suspicious files:

```bash
# Binary analysis with CyberAgent
curl -X POST "https://api.adverant.ai/fileprocess/api/process" \
  -H "Authorization: Bearer $NEXUS_API_KEY" \
  -F "file=@/path/to/binary.exe"
```

**Capabilities:**
- PE/ELF/Mach-O analysis
- Malware detection
- Decompilation (Ghidra)
- String extraction
- Import/export analysis
- Threat level assessment

**Response includes:**
- `threatLevel`: none/low/medium/high/critical
- `isMalicious`: boolean
- `analysis_summary`: detailed findings

---

## Document Processing

Process PDFs, Office documents, and text files:

```bash
# Documents via MageAgent
curl -X POST "https://api.adverant.ai/fileprocess/api/process" \
  -H "Authorization: Bearer $NEXUS_API_KEY" \
  -F "file=@/path/to/document.pdf"
```

**Supported Formats:**
- PDF (with OCR for scanned documents)
- Word (.docx, .doc)
- Excel (.xlsx, .xls)
- PowerPoint (.pptx, .ppt)
- Plain text, Markdown, HTML

**Capabilities:**
- Text extraction
- OCR (Tesseract/Vision)
- Table extraction
- Structure analysis
- Embedding generation

---

## 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
echo '{"content": "YOUR_CONTENT_HERE", "event_type": "TYPE"}' | ~/.claude/hooks/store-memory.sh
```

### Event Types
- `preference` - User/project preferences
- `learning` - Things discovered while coding
- `decision` - Architecture/design choices
- `fix` - Bug fixes and solutions
- `pattern` - Reusable code patterns
- `context` - Project-specific context

### Examples

```bash
# Store a preference
echo '{"content": "User prefers TypeScript strict mode", "event_type": "preference"}' | ~/.claude/hooks/store-memory.sh

# Store a learning
echo '{"content": "GraphRAG search returns {memories, documents, entities} not {results}", "event_type": "learning"}' | ~/.claude/hooks/store-memory.sh

# Store a fix
echo '{"content": "ENOENT path errors fixed by resolveFilePath in MessageRouter", "event_type": "fix"}' | ~/.claude/hooks/store-memory.sh
```

## Recall Memory

```bash
echo '{"query": "YOUR_SEARCH_QUERY"}' | ~/.claude/hooks/recall-memory.sh
```

### Examples

```bash
# Recall user preferences
echo '{"query": "user preferences coding style"}' | ~/.claude/hooks/recall-memory.sh

# Recall past fixes
echo '{"query": "ENOENT path error fix"}' | ~/.claude/hooks/recall-memory.sh

# Recall project context
echo '{"query": "nexus vscode plugin architecture"}' | ~/.claude/hooks/recall-memory.sh
```

## API Endpoints

The hooks use the Nexus API Gateway at `https://api.adverant.ai`:

| Operation | Endpoint | Method |
|-----------|----------|--------|
| Store Memory | `/api/memory/store` | POST |
| Recall Memory | `/api/memory/recall` | POST |

### Authentication

All requests require the Authorization header:

```
Authorization: Bearer <NEXUS_API_KEY>
```

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:
- Every prompt you send (UserPromptSubmit)
- Every tool execution (PostToolUse)
- Project context (directory name, path)
- Timestamps and session IDs

## Best Practices

1. **Be specific**: Store concrete, actionable information
2. **Include context**: Use appropriate event_type
3. **Search smart**: Use specific keywords when recalling
4. **Don't over-store**: Only store valuable cross-session info

## Troubleshooting

### NEXUS_API_KEY Not Set

If you see this error:
```
[store-memory] ERROR: NEXUS_API_KEY environment variable is required but not set.
```

**Solution:**
1. Get your API key from https://dashboard.adverant.ai/dashboard/api-keys
2. Add to your shell profile: `export NEXUS_API_KEY='your-key'`
3. Reload your shell: `source ~/.zshrc`

### 401 Unauthorized Error

Your API key may be invalid or expired.

**Solution:**
1. Verify your API key is set: `echo $NEXUS_API_KEY`
2. Generate a new key at https://adverant.ai/dashboard/api-keys
3. Update your shell profile with the new key

### Endpoint Not Found

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.