claudemem-search

# Claudemem Semantic Code Search Expert (v0.6.0)

This Skill provides comprehensive guidance on leveraging **claudemem** v0.7.0+ with **AST-based structural analysis**, **code analysis commands**, and **framework documentation** for intelligent codebase understanding.

## What's New in v0.3.0

```
┌─────────────────────────────────────────────────────────────────┐
│                  CLAUDEMEM v0.3.0 ARCHITECTURE                   │
├─────────────────────────────────────────────────────────────────┤
│                                                                  │
│  ┌───────────────────────────────────────────────────────────┐  │
│  │                 AST STRUCTURAL LAYER ⭐NEW                  │  │
│  │  Tree-sitter Parse → Symbol Graph → PageRank Ranking       │  │
│  │  map | symbol | callers | callees | context                │  │
│  └───────────────────────────────────────────────────────────┘  │
│                              ↓                                   │
│  ┌───────────────────────────────────────────────────────────┐  │
│  │                    SEARCH LAYER                             │  │
│  │  Query → Embed → Vector Search + BM25 → Ranked Results     │  │
│  └───────────────────────────────────────────────────────────┘  │
│                              ↓                                   │
│  ┌───────────────────────────────────────────────────────────┐  │
│  │                     INDEX LAYER                             │  │
│  │  AST Parse → Chunk → Embed → LanceDB + Symbol Graph        │  │
│  └───────────────────────────────────────────────────────────┘  │
│                                                                  │
└─────────────────────────────────────────────────────────────────┘
```

### Key Innovation: Structural Understanding

v0.3.0 adds **AST tree navigation** with symbol graph analysis:
- **PageRank ranking** - Symbols ranked by importance (how connected they are)
- **Call graph analysis** - Track callers/callees for impact assessment
- **Structural overview** - Map the codebase before reading code

---

## Quick Reference

```bash
# For agentic use, always use --agent flag for clean output
claudemem --agent <command>

# Core commands for agents
claudemem --agent map [query]              # Get structural overview (repo map)
claudemem --agent symbol <name>            # Find symbol definition
claudemem --agent callers <name>           # What calls this symbol?
claudemem --agent callees <name>           # What does this symbol call?
claudemem --agent context <name>           # Full context (symbol + dependencies)
claudemem --agent search <query>           # Semantic search (clean output)
claudemem --agent search <query> --map     # Search + include repo map context
```

---

## Version Compatibility

Claudemem has evolved significantly. **Check your version** before using commands:

```bash
claudemem --version
```

### Command Availability by Version

| Command | Minimum Version | Status | Purpose |
|---------|-----------------|--------|---------|
| `map` | v0.3.0 | ✅ Available | Architecture overview with PageRank |
| `symbol` | v0.3.0 | ✅ Available | Find exact file:line location |
| `callers` | v0.3.0 | ✅ Available | What calls this symbol? |
| `callees` | v0.3.0 | ✅ Available | What does this symbol call? |
| `context` | v0.3.0 | ✅ Available | Full call chain (callers + callees) |
| `search` | v0.3.0 | ✅ Available | Semantic vector search |
| `dead-code` | v0.4.0+ | ⚠️ Check version | Find unused symbols |
| `test-gaps` | v0.4.0+ | ⚠️ Check version | Find high-importance untested code |
| `impact` | v0.4.0+ | ⚠️ Check version | BFS transitive caller analysis |
| `docs` | v0.7.0+ | ✅ Available | Framework documentation fetching |

### Version Detection in Scripts

```bash
# Get version number
VERSION=$(claudemem --version 2>/dev/null | grep -oE '[0-9]+\.[0-9]+\.[0-9]+' | head -1)

# Check if v0.4.0+ features available
if [ -n "$VERSION" ] && printf '%s\n' "0.4.0" "$VERSION" | sort -V -C; then
  # v0.4.0+ available
  claudemem --agent dead-code  claudemem --agent test-gaps  claudemem --agent impact SymbolNameelse
  echo "Code analysis commands require claudemem v0.4.0+"
  echo "Current version: $VERSION"
  echo "Fallback to v0.3.0 commands (map, symbol, callers, callees)"
fi
```

### Graceful Degradation

When using v0.4.0+ commands, always provide fallback:

```bash
# Try impact analysis (v0.4.0+), fallback to callers (v0.3.0)
IMPACT=$(claudemem --agent impact SymbolName  2>/dev/null)
if [ -n "$IMPACT" ] && [ "$IMPACT" != "command not found" ]; then
  echo "$IMPACT"
else
  echo "Using fallback (direct callers only):"
  claudemem --agent callers SymbolNamefi
```

**Why This Matters:**
- v0.3.0 commands work for 90% of use cases (navigation, modification)
- v0.4.0+ commands are specialized (code analysis, cleanup planning)
- Scripts should work across versions with appropriate fallbacks

---

## The Correct Workflow ⭐CRITICAL

### Phase 1: Understand Structure First (ALWAYS DO THIS)

Before reading any code files, get the structural overview:

```bash
# For a specific task, get focused repo map
claudemem --agent map "authentication flow"
# Output shows relevant symbols ranked by importance (PageRank):
# file: src/auth/AuthService.ts
# line: 15-89
# kind: class
# name: AuthService
# pagerank: 0.0921
# signature: class AuthService
# ---
# file: src/middleware/auth.ts
# ...
```

This tells you:
- Which files contain relevant code
- Which symbols are most important (high PageRank = heavily used)
- The structure before you read actual code

### Phase 2: Locate Specific Symbols

Once you know what to look for:

```bash
# Find exact location of a symbol
claudemem --agent symbol AuthService
# Output:
# file: src/auth/AuthService.ts
# line: 15-89
# kind: class
# name: AuthService
# signature: class AuthService implements IAuthProvider
# exported: true
# pagerank: 0.0921
# docstring: Handles user authentication and session management
```

### Phase 3: Understan