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

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

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

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

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

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

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

Before modifying code, understand what depends on it:

# What calls AuthService? (impact of changes)
claudemem --agent callers AuthService
# 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

# What does AuthService call? (its dependencies)
claudemem --agent callees AuthService
# 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:

claudemem --agent context AuthService
# 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:

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

---

## Output Format

When using `--agent` flag, commands output machine-readable format:

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 --agent map
# Focused on specific task
claudemem --agent map "authentication"
# Limit tokens
claudemem --agent map "auth" --tokens 500```

**Output fields**: file, line, kind, name, signature, pagerank, exported

**When to use**: Always first - understand structure before reading code

### claudemem symbol <name>

Find a symbol by name. Disambiguates using PageRank and export status.

```bash
claudemem --agent symbol Indexerclaudemem --agent symbol "search" --file retriever   # hint which file

Output fields: file, line, kind, name, signature, pagerank, exported, docstring

When to use: When you know the symbol name and need exact location

claudemem callers <name>

Find all symbols that call/reference the given symbol.

claudemem --agent callers AuthService```

**Output fields**: caller (name), file, line, kind (call/import/extends/etc)

**When to use**: Before modifying anything - know the impact radius

### claudemem callees <name>

Find all symbols that the given symbol calls/references.

```bash
claudemem --agent callees AuthService```

**Output fields**: callee (name), file, line, kind

**When to use**: To understand dependencies and trace data flow

### claudemem context <name>

Get full context: the symbol plus its callers and callees.

```bash
claudemem --agent context Indexerclaudemem --agent context Indexer --callers 10 --callees 20```

**Output sections**: [symbol], [callers], [callees]

**When to use**: For complex modifications requiring full awareness

### claudemem search <query>

Semantic search across the codebase.

```bash
claudemem --agent search "error handling"claudemem --agent search "error handling" --map   # include repo map
claudemem --agent search "auth" -n 5   # limit results

Output fields: file, line, kind, name, score, content (truncated)

When to use: When you need actual code snippets (after mapping)

---

Code Analysis Commands (v0.4.0+ Required)

claudemem dead-code

Find unused symbols in the codebase.

# Find all unused symbols
claudemem --agent dead-code
# Stricter threshold (only very low PageRan

---

*Content truncated.*