claudemem-search

What this skill does

# 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
# Always run with --nologo for clean output
claudemem --nologo <command>

# Core commands for agents
claudemem map [query]              # Get structural overview (repo map)
claudemem symbol <name>            # Find symbol definition
claudemem callers <name>           # What calls this symbol?
claudemem callees <name>           # What does this symbol call?
claudemem context <name>           # Full context (symbol + dependencies)
claudemem search <query>           # Semantic search with --raw for parsing
claudemem 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 --nologo dead-code --raw
  claudemem --nologo test-gaps --raw
  claudemem --nologo impact SymbolName --raw
else
  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 --nologo impact SymbolName --raw 2>/dev/null)
if [ -n "$IMPACT" ] && [ "$IMPACT" != "command not found" ]; then
  echo "$IMPACT"
else
  echo "Using fallback (direct callers only):"
  claudemem --nologo callers SymbolName --raw
fi
```

**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 --nologo map "authentication flow" --raw

# 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 --nologo symbol AuthService --raw

# 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: Understand Dependencies

Before modifying code, understand what depends on it:

```bash
# What calls AuthService? (impact of changes)
claudemem --nologo callers AuthService --raw

# Output:
# caller: LoginController.authenticate
# file: src/controllers/login.ts
# line: 34
# kind: call
# ---
# caller: SessionMiddleware.validate
# file: src/middleware/session.ts
# line: 12
# kind: call
```

```bash
# What does AuthService call? (its dependencies)
claudemem --nologo callees AuthService --raw

# Output:
# callee: Database.query
# file: src/db/database.ts
# line: 45
# kind: call
# ---
# callee: TokenManager.generate
# file: src/auth/tokens.ts
# line: 23
# kind: call
```

### Phase 4: Get Full Context

For complex modifications, get everything at once:

```bash
claudemem --nologo context AuthService --raw

# Output includes:
# [symbol]
# file: src/auth/AuthService.ts
# line: 15-89
# kind: class
# name: AuthService
# ...
# [callers]
# caller: LoginController.authenticate
# ...
# [callees]
# callee: Database.query
# ...
```

### Phase 5: Search for Code (Only If Needed)

When you need actual code snippets:

```bash
# Semantic search
claudemem --nologo search "password hashing" --raw

# Search with repo map context (recommended for complex tasks)
claudemem --nologo search "password hashing" --map --raw
```

---

## Output Format

All commands support `--raw` flag for machine-readable output:

```
# Raw output format (line-based, easy to parse)
file: src/core/indexer.ts
line: 45-120
kind: class
name: Indexer
signature: class Indexer
pagerank: 0.0842
exported: true
---
file: src/core/store.ts
line: 12-89
kind: class
name: VectorStore
...
```

Records are separated by `---`. Each field is `key: value` on its own line.

---

## Command Reference

### claudemem map [query]

Get structural overview of the codebase. Optionally focused on a query.

```bash
# Full repo map (top symbols by PageRank)
claudemem --nologo map --raw

# Focused on specific task
claudemem --nologo map "authentication" --raw