claudemem-search

name	claudemem-search
description	⚡ PRIMARY TOOL for semantic code search AND structural analysis. NEW: AST tree navigation with map, symbol, callers, callees, context commands. PageRank ranking. Recommended workflow: Map structure first, then search semantically, analyze callers before modifying.
allowed-tools	Bash, Task, AskUserQuestion

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

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 PageRank)
claudemem --agent dead-code --max-pagerank 0.005
# Include exported symbols (usually excluded)
claudemem --agent dead-code --include-exported```

**Algorithm:**
- Zero callers (nothing references the symbol)
- Low PageRank (< 0.001 default)
- Not exported (by default, exports may be used externally)

**Output fields**: file, line, kind, name, pagerank, last_caller_removed

**When to use**: Architecture cleanup, tech debt assessment, before major refactoring

**Empty Result Handling:**
```bash
RESULT=$(claudemem --agent dead-code )
if [ -z "$RESULT" ] || [ "$RESULT" = "No dead code found" ]; then
  echo "Codebase is clean - no dead code detected!"
  echo "This indicates good code hygiene."
else
  echo "$RESULT"
fi

Static Analysis Limitations:

• Dynamic imports (import()) may hide real callers
• Reflection-based access not captured
• External callers (other repos, CLI usage) not visible
• Exported symbols excluded by default for this reason

claudemem test-gaps

Find high-importance code without test coverage.

# Find all test coverage gaps
claudemem --agent test-gaps
# Only critical gaps (high PageRank)
claudemem --agent test-gaps --min-pagerank 0.05```

**Algorithm:**
- High PageRank (> 0.01 default) - Important code
- Zero callers from test files (*.test.ts, *.spec.ts, *_test.go)

**Output fields**: file, line, kind, name, pagerank, production_callers, test_callers

**When to use**: Test coverage analysis, QA planning, identifying critical gaps

**Empty Result Handling:**
```bash
RESULT=$(claudemem --agent test-gaps )
if [ -z "$RESULT" ] || [ "$RESULT" = "No test gaps found" ]; then
  echo "Excellent! All high-importance code has test coverage."
  echo "Consider lowering --min-pagerank threshold for additional coverage."
else
  echo "$RESULT"
fi

Static Analysis Limitations:

• Test file detection based on naming patterns only
• Integration tests calling code indirectly may not be detected
• Mocked dependencies may show false positives

claudemem impact

Analyze the impact of changing a symbol using BFS traversal.

# Get all transitive callers
claudemem --agent impact UserService
# Limit depth for large codebases
claudemem --agent impact UserService --max-depth 5```

**Algorithm:**
- BFS traversal from symbol to all transitive callers
- Groups results by depth level
- Shows file:line for each caller

**Output sections**: direct_callers, transitive_callers (with depth), grouped_by_file

**When to use**: Before ANY modification, refactoring planning, risk assessment

**Empty Result Handling:**
```bash
RESULT=$(claudemem --agent impact FunctionName )
if [ -z "$RESULT" ] || echo "$RESULT" | grep -q "No callers found"; then
  echo "No callers found - this symbol appears unused or is an entry point."
  echo "If unused, consider running: claudemem --agent dead-code "
  echo "If entry point (API handler, main), this is expected."
else
  echo "$RESULT"
fi

Static Analysis Limitations:

• Callback/event-based calls may not be detected
• Dependency injection containers hide static call relationships
• External service callers not visible

---

LLM Enrichment Document Types (v0.2.0+)

Claudemem v0.2.0+ supports LLM-enriched semantic search with specialized document types.

Document Types

Type	Purpose	Generated By
symbol_summary	Function behavior, params, returns, side effects	LLM analysis
file_summary	File purpose, exports, architectural patterns	LLM analysis
idiom	Common patterns in codebase	Pattern detection
usage_example	How to use APIs	Documentation extraction
anti_pattern	What NOT to do	Static analysis + LLM
project_doc	Project-level documentation	README, CLAUDE.md

Navigation Mode

For agent-optimized search with document type weighting:

# Navigation-focused search (prioritizes summaries)
claudemem --agent search "authentication" --use-case navigation
# Default search (balanced)
claudemem --agent search "authentication"```

**Navigation mode search weights:**
- `symbol_summary`: 1.5x (higher priority)
- `file_summary`: 1.3x (higher priority)
- `code_chunk`: 1.0x (normal)
- `idiom`: 1.2x (higher for pattern discovery)

### Symbol Summary Fields

```yaml
symbol: AuthService.authenticate
file: src/services/auth.ts
line: 45-89
behavior: "Validates user credentials and generates JWT token"
params:
  - name: credentials
    type: LoginCredentials
    description: "Email and password from login form"
returns:
  type: AuthResult
  description: "JWT token and user profile on success, error on failure"
side_effects:
  - "Updates user.lastLogin timestamp"
  - "Logs authentication attempt"
  - "May trigger rate limiting"

File Summary Fields

file: src/services/auth.ts
purpose: "Core authentication service handling login, logout, and session management"
exports:
  - AuthService (class)
  - authenticate (function)
  - validateToken (function)
patterns:
  - "Dependency Injection (constructor takes IUserRepository)"
  - "Factory Pattern (createSession)"
  - "Strategy Pattern (IAuthProvider interface)"
dependencies:
  - bcrypt (password hashing)
  - jsonwebtoken (JWT generation)
  - UserRepository (user data access)

Using Document Types in Investigation

# Find function behavior without reading code
claudemem --agent search "processPayment behavior" --use-case navigation
# Output includes symbol_summary:
# symbol: PaymentService.processPayment
# behavior: "Charges customer card via Stripe and saves transaction"
# side_effects: ["Updates balance", "Sends receipt email", "Logs to audit"]

# Find file purposes for architecture understanding
claudemem --agent search "file:services purpose" --use-case navigation
# Find anti-patterns to avoid
claudemem --agent search "anti_pattern SQL"```

### Regenerating Enrichments

If codebase changes significantly:

```bash
# Re-index with LLM enrichment
claudemem index --enrich

# Or enrich specific files
claudemem enrich src/services/payment.ts

---

Workflow Templates

Standardized investigation patterns for common scenarios. All templates include error handling for empty results and version compatibility checks.

Template 1: Bug Investigation

Trigger: "Why is X broken?", "Find bug", "Root cause"

# Step 1: Locate the symptom
SYMBOL=$(claudemem --agent symbol FunctionFromStackTrace )
if [ -z "$SYMBOL" ]; then
  echo "Symbol not found - check spelling or run: claudemem --agent map 'related keywords' "
  exit 1
fi

# Step 2: Get full context (callers + callees)
claudemem --agent context FunctionFromStackTrace
# Step 3: Trace backwards to find root cause
claudemem --agent callers suspectedSource
# Step 4: Check full impact of the bug (v0.4.0+)
IMPACT=$(claudemem --agent impact BuggyFunction  2>/dev/null)
if [ -n "$IMPACT" ]; then
  echo "$IMPACT"
else
  echo "Impact analysis requires claudemem v0.4.0+ or no callers found"
  echo "Fallback: claudemem --agent callers BuggyFunction "
fi

# Step 5: Read identified file:line ranges
# Fix bug, verify callers still work

# Step 6: Document impacted code for testing

Output Template:

## Bug Investigation Report

**Symptom:** [Description]
**Root Cause:** [Location and explanation]
**Call Chain:** [How we got here]
**Impact Radius:** [What else is affected]
**Fix Applied:** [What was changed]
**Verification:** [Tests run, callers checked]

Template 2: New Feature Implementation

Trigger: "Add feature", "Implement X", "Extend functionality"

# Step 1: Map the feature area
MAP=$(claudemem --agent map "feature area keywords" )
if [ -z "$MAP" ]; then
  echo "No matches found - try broader keywords"
fi

# Step 2: Identify extension points
claudemem --agent callees ExistingFeature
# Step 3: Get full context for modification point
claudemem --agent context ModificationPoint
# Step 4: Check existing patterns to follow
claudemem --agent search "similar pattern" --use-case navigation
# Step 5: Implement following existing patterns

# Step 6: Check test coverage gaps (v0.4.0+)
GAPS=$(claudemem --agent test-gaps  2>/dev/null)
if [ -n "$GAPS" ]; then
  echo "Test gaps to address:"
  echo "$GAPS"
else
  echo "test-gaps requires v0.4.0+ or no gaps found"
fi

Output Template:

## Feature Implementation Plan

**Feature:** [Description]
**Extension Point:** [Where to add]
**Dependencies:** [What it needs]
**Pattern to Follow:** [Existing similar code]
**Test Requirements:** [Coverage needs]

Template 3: Refactoring

Trigger: "Rename X", "Extract function", "Move code", "Refactor"

# Step 1: Find the symbol to refactor
SYMBOL=$(claudemem --agent symbol SymbolToRename )
if [ -z "$SYMBOL" ]; then
  echo "Symbol not found - check exact name"
  exit 1
fi

# Step 2: Get FULL impact (all transitive callers) (v0.4.0+)
IMPACT=$(claudemem --agent impact SymbolToRename  2>/dev/null)
if [ -n "$IMPACT" ]; then
  echo "$IMPACT"
  # (impact output includes grouped_by_file)
else
  echo "Using fallback (direct callers only):"
  claudemem --agent callers SymbolToRenamefi

# Step 3: Group by file for systematic updates

# Step 4: Update each caller location systematically

# Step 5: Verify all callers updated
claudemem --agent callers NewSymbolName
# Step 6: Run affected tests

Output Template:

## Refactoring Report

**Original:** [Old name/location]
**Target:** [New name/location]
**Direct Callers:** [Count]
**Transitive Callers:** [Count]
**Files Modified:** [List]
**Verification:** [All callers updated, tests pass]

Template 4: Architecture Understanding

Trigger: "How does X work?", "Explain architecture", "Onboarding"

# Step 1: Get full structural map
MAP=$(claudemem --agent map )
if [ -z "$MAP" ]; then
  echo "Index may be empty - run: claudemem index"
  exit 1
fi
echo "$MAP"

# Step 2: Identify architectural pillars (PageRank > 0.05)
# Document top 5 by PageRank

# Step 3: For each pillar, get full context
claudemem --agent context PillarSymbol
# Step 4: Trace major flows via callees
claudemem --agent callees EntryPoint
# Step 5: Identify dead code (cleanup opportunities) (v0.4.0+)
DEAD=$(claudemem --agent dead-code  2>/dev/null)
if [ -n "$DEAD" ]; then
  echo "Dead code found:"
  echo "$DEAD"
else
  echo "No dead code found (or v0.4.0+ required)"
fi

# Step 6: Identify test gaps (risk areas) (v0.4.0+)
GAPS=$(claudemem --agent test-gaps  2>/dev/null)
if [ -n "$GAPS" ]; then
  echo "Test gaps:"
  echo "$GAPS"
else
  echo "No test gaps found (or v0.4.0+ required)"
fi

Output Template:

## Architecture Report

**Core Abstractions (PageRank > 0.05):**
1. [Symbol] - [Role in system]
2. [Symbol] - [Role in system]
3. [Symbol] - [Role in system]

**Layer Structure:**

[Presentation Layer] | [Business Layer] | [Data Layer]

**Major Flows:**
- [Flow 1: Entry -> Processing -> Output]
- [Flow 2: Entry -> Processing -> Output]

**Health Indicators:**
- Dead Code: [Count] symbols
- Test Gaps: [Count] high-importance untested
- Tech Debt: [Summary]

Template 5: Security Audit

Trigger: "Security review", "Audit authentication", "Check permissions"

# Step 1: Map security-related code
claudemem --agent map "auth permission security token"
# Step 2: Find authentication entry points
SYMBOL=$(claudemem --agent symbol authenticate )
if [ -z "$SYMBOL" ]; then
  echo "No 'authenticate' symbol - try: login, verify, validate"
fi
claudemem --agent callers authenticate
# Step 3: Trace authentication flow
claudemem --agent callees authenticate
# Step 4: Check authorization patterns
claudemem --agent map "authorize permission check guard"
# Step 5: Find sensitive data handlers
claudemem --agent map "password hash token secret key"
# Step 6: Check for test coverage on security code (v0.4.0+)
GAPS=$(claudemem --agent test-gaps --min-pagerank 0.01  2>/dev/null)
if [ -n "$GAPS" ]; then
  # Filter for security-related symbols
  echo "$GAPS" | grep -E "(auth|login|password|token|permission|secret)"
fi

Output Template:

## Security Audit Report

**Authentication:**
- Entry Points: [List]
- Flow: [Description]
- Gaps: [Issues found]

**Authorization:**
- Permission Checks: [Where implemented]
- Coverage: [All routes covered?]

**Sensitive Data:**
- Password Handling: [How stored/compared]
- Token Management: [Generation/validation]
- Secrets: [How managed]

**Test Coverage:**
- Security Code Coverage: [X%]
- Critical Gaps: [List]

**Recommendations:**
1. [Priority 1 fix]
2. [Priority 2 fix]

---

Static Analysis Limitations

Claudemem uses static AST analysis. Some patterns are not captured:

Dynamic Imports

// NOT visible to static analysis
const module = await import(`./modules/${name}`);

Result: May show as "dead code" but is actually used dynamically. Action: Mark as "Potentially Dead - Manual Review"

External Callers

// Exported for external use
export function publicAPI() { ... }

Result: May show 0 callers but used by other repositories. Action: Use --include-exported carefully, or mark as "Externally Called - Manual Review Required"

Reflection/Eval

// NOT visible to static analysis
const fn = obj[methodName]();
eval("functionName()");

Result: Callers not detected. Action: Search codebase for eval, Object.keys, bracket notation.

Event-Driven Code

// NOT visible as direct callers
emitter.on('event', handler);
document.addEventListener('click', onClick);

Result: handler and onClick may show 0 callers. Action: Check for event registration patterns.

Dependency Injection

// Container registration hides relationships
container.register(IService, ServiceImpl);

Result: ServiceImpl may show 0 callers. Action: Check DI container configuration.

---

Scenarios

Scenario 1: Bug Fix

Task: "Fix the null pointer exception in user authentication"

# Step 1: Get overview of auth-related code
claudemem --agent map "authentication null pointer"
# Step 2: Locate the specific symbol mentioned in error
claudemem --agent symbol authenticate
# Step 3: Check what calls it (to understand how it's used)
claudemem --agent callers authenticate
# Step 4: Read the actual code at the identified location
# Now you know exactly which file:line to read

Scenario 2: Add New Feature

Task: "Add rate limiting to the API endpoints"

# Step 1: Understand API structure
claudemem --agent map "API endpoints rate"
# Step 2: Find the main API handler
claudemem --agent symbol APIController
# Step 3: See what the API controller depends on
claudemem --agent callees APIController
# Step 4: Check if rate limiting already exists somewhere
claudemem --agent search "rate limit"
# Step 5: Get full context for the modification point
claudemem --agent context APIController```

### Scenario 3: Refactoring

**Task**: "Rename DatabaseConnection to DatabasePool"

```bash
# Step 1: Find the symbol
claudemem --agent symbol DatabaseConnection
# Step 2: Find ALL callers (these all need updating)
claudemem --agent callers DatabaseConnection
# Step 3: The output shows every file:line that references it
# Update each location systematically

Scenario 4: Understanding Unfamiliar Codebase

Task: "How does the indexing pipeline work?"

# Step 1: Get high-level structure
claudemem --agent map "indexing pipeline"
# Step 2: Find the main entry point (highest PageRank)
claudemem --agent symbol Indexer
# Step 3: Trace the flow - what does Indexer call?
claudemem --agent callees Indexer
# Step 4: For each major callee, get its callees
claudemem --agent callees VectorStoreclaudemem --agent callees FileTracker
# Now you have the full pipeline traced

---

Token Efficiency Guide

Action	Token Cost	When to Use
map (focused)	~500	Always first - understand structure
symbol	~50	When you know the name
callers	~100-500	Before modifying anything
callees	~100-500	To understand dependencies
context	~200-800	For complex modifications
search	~1000-3000	When you need actual code
search --map	~1500-4000	For unfamiliar codebases

Optimal order: map → symbol → callers/callees → search (only if needed)

This pattern typically uses 80% fewer tokens than blind exploration.

---

Integration Pattern for Agents

For maximum efficiency, follow this pattern:

1. RECEIVE TASK
   ↓
2. claudemem --agent map "<task keywords>"   → Understand structure, identify key symbols
   ↓
3. claudemem --agent symbol <high-pagerank-symbol>   → Get exact location
   ↓
4. claudemem --agent callers <symbol>   (if modifying)
   → Know the impact radius
   ↓
5. claudemem --agent callees <symbol>   (if needed)
   → Understand dependencies
   ↓
6. READ specific file:line ranges (not whole files)
   ↓
7. MAKE CHANGES with full awareness
   ↓
8. CHECK callers still work

---

PageRank: Understanding Symbol Importance

PageRank measures how "central" a symbol is in the codebase:

PageRank	Meaning	Action
> 0.05	Core abstraction	Understand this first - everything depends on it
0.01-0.05	Important symbol	Key functionality, worth understanding
0.001-0.01	Standard symbol	Normal code, read as needed
< 0.001	Utility/leaf	Helper functions, read only if directly relevant

Why PageRank matters:

• High-PageRank symbols are heavily used → understand them first
• Low-PageRank symbols are utilities → read later if needed
• Focus on high-PageRank symbols to understand architecture quickly

---

💡 Better Approaches (Recommended Patterns)

Claudemem provides more efficient alternatives to common search patterns:

Instead of...	Try this	Benefit
cat src/core/*.ts | head -1000	claudemem --agent map "task"	Saves tokens, finds relevant files
grep -r "Database" src/	claudemem --agent symbol Database	Semantic relationships, not just strings
Edit without caller check	claudemem --agent callers X first	Know what depends on your changes
Search immediately	map first, then search	Context improves search accuracy
Read every matching file	Focus on high-PageRank symbols	Core code first, utilities later
claudemem search "query"	claudemem --agent search "query"	Clean output without ASCII art

Why These Patterns Work Better

1. Token Efficiency: map identifies relevant files before reading, avoiding wasted context
2. Semantic Understanding: symbol and callers understand code relationships, not just text
3. Impact Awareness: callers reveals dependencies before you modify code
4. PageRank Guidance: High-PageRank symbols are heavily connected - understand them first

Output Handling

Tip: Use Complete Claudemem Output

Results are ranked by PageRank - most important symbols appear first. Using the complete output ensures you see all relevant results.

Managing Large Output

If output is too large, use built-in flags instead of truncating:

Flag	Purpose	Example
--tokens N	Limit by token count	claudemem --agent map "query" --tokens 2000
-n N	Limit result count	claudemem --agent search "auth" -n 10
--page-size N	Pagination	claudemem --agent search "x" --page-size 20
--max-depth N	Limit traversal	claudemem --agent context Func --max-depth 3

Tip: Piping to file preserves full output: claudemem --agent map "query" > /tmp/map.txt

Quick Reference: Recommended Patterns

Instead of...	Try this	Why
Read files blindly	map first, then read specific lines	Ranked results, less tokens
grep -r "auth"	claudemem --agent symbol auth	Semantic understanding
Modify without callers	callers before any modification	Avoid breaking changes
Search immediately	map → symbol → search	Structural context first
cmd | head	Use -n or --tokens flags	Output is pre-optimized

---

The Correct Workflow Diagram

┌─────────────────────────────────────────────────────────────────┐
│                 CORRECT INVESTIGATION FLOW (v0.3.0)              │
├─────────────────────────────────────────────────────────────────┤
│                                                                  │
│  1. claudemem --agent map "task"                          │
│     → Understand structure, find high-PageRank symbols          │
│                                                                  │
│  2. claudemem --agent symbol <name>                       │
│     → Get exact file:line location                              │
│                                                                  │
│  3. claudemem --agent callers <name>                      │
│     → Know impact radius BEFORE modifying                       │
│                                                                  │
│  4. claudemem --agent callees <name>                      │
│     → Understand dependencies                                    │
│                                                                  │
│  5. Read specific file:line ranges (NOT whole files)            │
│                                                                  │
│  6. Make changes with full awareness                            │
│                                                                  │
│  ⚠️ NEVER: Start with Read/Glob for semantic questions          │
│  ⚠️ NEVER: Modify without checking callers                      │
│  ⚠️ NEVER: Search without mapping first                         │
│                                                                  │
└─────────────────────────────────────────────────────────────────┘

---

Installation & Setup

Check Installation

# Check if claudemem CLI is available
which claudemem || command -v claudemem

# Check version (must be 0.3.0+)
claudemem --version

Installation Options

# npm (recommended)
npm install -g claude-codemem

# Homebrew (macOS)
brew tap MadAppGang/claude-mem && brew install --cask claudemem

Index Codebase

# Index current project
claudemem index

# Check status
claudemem --version && ls -la .claudemem/index.db 2>/dev/null

---

Framework Documentation (v0.7.0+) ⭐NEW

Claudemem v0.7.0+ includes automatic framework documentation fetching for your project dependencies. Documentation is indexed alongside your code, enabling unified semantic search across both.

Quick Reference

# Core documentation commands
claudemem docs status            # Show indexed libraries and cache state
claudemem docs fetch             # Fetch docs for all detected dependencies
claudemem docs fetch react vue   # Fetch specific libraries
claudemem docs providers         # List available documentation providers
claudemem docs refresh           # Force refresh all cached documentation
claudemem docs clear             # Clear all documentation cache
claudemem docs clear react       # Clear specific library cache

Documentation Providers

Claudemem uses a provider hierarchy with automatic fallback:

Priority	Provider	Coverage	Requirements
1 (Best)	Context7	6000+ libraries with versioned code examples	API key (free tier available)
2	llms.txt	Official AI-friendly docs from framework sites	Free, no key needed
3	DevDocs	Consistent offline documentation, 100+ languages	Free, no key needed

Dependency Detection

Claudemem automatically detects dependencies from:

File	Ecosystem	Example
package.json	npm/yarn	React, Vue, Express
requirements.txt	Python/pip	Django, FastAPI, Pandas
go.mod	Go	Gin, Echo, GORM
Cargo.toml	Rust	Tokio, Actix, Serde

Setup

# Option 1: Run init (includes docs configuration)
claudemem init

# Option 2: Configure Context7 manually (optional, for best coverage)
export CONTEXT7_API_KEY=your_key

# Get free API key at: https://context7.com/dashboard

Usage Examples

# Check current documentation status
claudemem docs status

# Output:
# 📚 Documentation Status
#
#   Enabled:     Yes
#   Providers:   Context7, llms.txt, DevDocs
#   Libraries:   12 indexed
#   Cache Age:   2h 15m
#
#   Indexed Libraries:
#     react (v18) via Context7 - 145 chunks
#     typescript (v5) via Context7 - 89 chunks
#     express (v4) via llms.txt - 34 chunks
#     ...

# Fetch documentation for all project dependencies
claudemem docs fetch

# Output:
# 📚 Fetching Documentation
#
#   [1/8] react... ✓ 145 chunks via Context7
#   [2/8] typescript... ✓ 89 chunks via Context7
#   [3/8] express... ✓ 34 chunks via llms.txt
#   [4/8] lodash... ✓ 67 chunks via DevDocs
#   ...

# Fetch specific library
claudemem docs fetch fastapi

# View available providers
claudemem docs providers

# Force refresh (clears cache, refetches)
claudemem docs refresh

Unified Search (Code + Documentation)

After indexing documentation, claudemem search returns results from both your codebase and framework documentation:

claudemem --agent search "how to use React hooks"
# Output includes:
# --- Your Code ---
# file: src/components/UserProfile.tsx
# line: 12-45
# kind: function
# name: useUserProfile
# score: 0.89
# content: Custom hook for user profile management...
# ---
# --- React Documentation ---
# library: react
# section: Hooks Reference
# title: useEffect
# score: 0.87
# content: The useEffect Hook lets you perform side effects...
# ---
# library: react
# section: Hooks Reference
# title: useState
# score: 0.85
# content: useState is a Hook that lets you add state...

When to Use Documentation Commands

Scenario	Command	Why
New project setup	claudemem docs fetch	Index docs for all dependencies
Learning new library	claudemem docs fetch <library>	Get searchable reference
Updated dependencies	claudemem docs refresh	Refresh to get new versions
Check what's indexed	claudemem docs status	View cache state
Clear space	claudemem docs clear	Remove cached documentation

Integration with Investigation Workflow

Add documentation fetch to your investigation workflow:

# ENHANCED Investigation Workflow (v0.7.0+)

# Step 0: Ensure framework docs are available (one-time)
claudemem docs status || claudemem docs fetch

# Step 1: Map architecture (now includes library patterns)
claudemem --agent map "authentication"
# Step 2: Search both code AND framework docs
claudemem --agent search "JWT token validation"# Returns: your auth code + library docs on JWT handling

# Step 3: Understand how the library recommends usage
claudemem --agent search "react best practices hooks"# Returns: your patterns + React official guidance

Version Information

The claudemem docs command requires v0.7.0+. Check your version:

claudemem --version
# Expected: 0.7.0 or higher

Note: If claudemem docs help returns "Unknown command", upgrade your claudemem installation.

---

Search Feedback Protocol (v0.8.0+) ⭐NEW

Claudemem learns from your search patterns. After completing a task, report which search results were helpful to improve future searches.

Why Feedback Matters

Feedback Type	Effect	Over Time
Helpful	+10% boost	Files you consistently use rank higher
Unhelpful	-10% demotion	Irrelevant results rank lower
Document Type	Type weighting	Helpful types (e.g., symbol_summary) get priority

CLI Interface

# After using search results, report feedback
claudemem feedback --query "your original query" \
  --helpful id1,id2 \
  --unhelpful id3,id4

# Result IDs are shown in search output:
claudemem search "authentication" --agent# Output includes:
# id: abc123
# file: src/auth/middleware.ts
# ...

MCP Interface

{
  "tool": "report_search_feedback",
  "arguments": {
    "query": "authentication flow",
    "allResultIds": ["id1", "id2", "id3"],
    "helpfulIds": ["id1"],
    "unhelpfulIds": ["id3"]
  }
}

When to Track as Helpful

A result should be marked as helpful when:

• The file was read and contained relevant information
• The code was used to understand the problem
• The symbol was part of the call chain being traced
• The file contributed to the final answer

When to Track as Unhelpful

A result should be marked as unhelpful when:

• The file was read but contained irrelevant information
• The result was a false positive (matched query but wrong context)
• The file was skipped after reading initial content
• The symbol was not related to the investigation

When NOT to Track

Do not track feedback for:

• Results from map command (structural overview, not semantic search)
• Results from symbol command (exact lookup, not search)
• Results from callers/callees commands (call graph, not search)
• Only search command results should have feedback

Integration with Workflow Templates

Add feedback reporting to the end of each workflow template:

# Template 1: Bug Investigation (add at end)
# Step 7: Report feedback
if [ -n "$SEARCH_QUERY" ] && [ -n "$HELPFUL_IDS" ]; then
  # Check if feedback is available (v0.8.0+)
  if claudemem feedback --help 2>&1 | grep -qi "feedback"; then
    timeout 5 claudemem feedback --query "$SEARCH_QUERY" \
      --helpful "${HELPFUL_IDS}" \
      --unhelpful "${UNHELPFUL_IDS}" 2>/dev/null || true
  else
    echo "Note: Search feedback requires claudemem v0.8.0+"
  fi
fi

Feedback Workflow Example

# Full investigation with feedback tracking

# 0. Check if feedback is available (v0.8.0+)
FEEDBACK_AVAILABLE=false
if claudemem feedback --help 2>&1 | grep -qi "feedback"; then
  FEEDBACK_AVAILABLE=true
else
  echo "Note: Search feedback requires claudemem v0.8.0+"
fi

# 1. Search and capture IDs
RESULTS=$(claudemem --agent search "payment processing" -n 10 )
ALL_IDS=$(echo "$RESULTS" | grep "^id:" | awk '{print $2}')
SEARCH_QUERY="payment processing"

# 2. Initialize tracking arrays
HELPFUL=()
UNHELPFUL=()

# 3. Process results (during investigation)
# When you read a result and it's useful:
HELPFUL+=("abc123")
# When you read a result and it's not relevant:
UNHELPFUL+=("def456")

# 4. Report feedback (at end of investigation)
if [ "$FEEDBACK_AVAILABLE" = true ] && ([ ${#HELPFUL[@]} -gt 0 ] || [ ${#UNHELPFUL[@]} -gt 0 ]); then
  timeout 5 claudemem feedback \
    --query "$SEARCH_QUERY" \
    --helpful "$(IFS=,; echo "${HELPFUL[*]}")" \
    --unhelpful "$(IFS=,; echo "${UNHELPFUL[*]}")" \
    2>/dev/null ||  

Quality Checklist Update

Add to the existing Quality Checklist:

• Tracked result IDs during search (if using search command)
• Reported feedback at end of investigation (if applicable)

---

Index Freshness Check (v0.5.0)

Before proceeding with investigation, verify the index is current:

# Count files modified since last index
STALE_COUNT=$(find . -type f \( -name "*.ts" -o -name "*.tsx" -o -name "*.js" -o -name "*.jsx" -o -name "*.py" -o -name "*.go" -o -name "*.rs" \) \
  -newer .claudemem/index.db 2>/dev/null | grep -v "node_modules" | grep -v ".git" | grep -v "dist" | grep -v "build" | wc -l)
STALE_COUNT=$((STALE_COUNT + 0))  # Normalize to integer

if [ "$STALE_COUNT" -gt 0 ]; then
  # Get index time with explicit platform detection
  if [[ "$OSTYPE" == "darwin"* ]]; then
    INDEX_TIME=$(stat -f "%Sm" -t "%Y-%m-%d %H:%M" .claudemem/index.db 2>/dev/null)
  else
    INDEX_TIME=$(stat -c "%y" .claudemem/index.db 2>/dev/null | cut -d'.' -f1)
  fi
  INDEX_TIME=${INDEX_TIME:-"unknown time"}

  # Use AskUserQuestion to ask user how to proceed
  # Options: [1] Reindex now (Recommended), [2] Proceed with stale index, [3] Cancel
fi

AskUserQuestion Template:

AskUserQuestion({
  questions: [{
    question: `${STALE_COUNT} files have been modified since the last index (${INDEX_TIME}). The claudemem index may be outdated, which could cause missing or incorrect results. How would you like to proceed?`,
    header: "Index Freshness Warning",
    multiSelect: false,
    options: [
      {
        label: "Reindex now (Recommended)",
        description: "Run claudemem index to update. Takes ~1-2 minutes."
      },
      {
        label: "Proceed with stale index",
        description: "Continue investigation. May miss recent code changes."
      },
      {
        label: "Cancel investigation",
        description: "I'll handle this manually."
      }
    ]
  }]
})

---

Result Validation Guidelines

After Every Command

1. Check exit code - Non-zero indicates failure
2. Check for empty results - May need reindex or different query
3. Validate relevance - Results should match query semantics

Validation Examples

# map validation
RESULTS=$(claudemem --agent map "authentication" )
EXIT_CODE=$?

if [ "$EXIT_CODE" -ne 0 ]; then
  echo "ERROR: claudemem command failed"
  # Diagnose index health
  DIAGNOSIS=$(claudemem --version && ls -la .claudemem/index.db 2>&1)
  # Use AskUserQuestion
fi

if [ -z "$RESULTS" ]; then
  echo "WARNING: No results found - may need reindex or different query"
  # Use AskUserQuestion
fi

if ! echo "$RESULTS" | grep -qi "auth\|login\|user\|session"; then
  echo "WARNING: Results may not be relevant to authentication query"
  # Use AskUserQuestion
fi

# symbol validation
RESULTS=$(claudemem --agent symbol UserService )
if ! echo "$RESULTS" | grep -q "name: UserService"; then
  echo "WARNING: UserService not found - check spelling or reindex"
  # Use AskUserQuestion
fi

# search validation
RESULTS=$(claudemem --agent search "error handling" )
MATCH_COUNT=0
for kw in error handling catch try; do
  if   | grep -qi ; 
    MATCH_COUNT=$((MATCH_COUNT + ))
  

 [  -lt 2 ]; 
   
  

---

Fallback Options

If claudemem returns no results or the index isn't available:

1. Check index status - Run claudemem status to verify
2. Try different query - Rephrase or use more specific terms
3. Reindex if needed - Run claudemem index (~1-2 min)
4. Native tools available - grep/Glob work but without semantic ranking

Using Native Tools

Native search tools (grep, Glob, find) are available when needed. They work well for:

• Exact string matches
• File pattern searches
• When the index isn't available

For bypass, use: _bypass_claudemem: true in tool input.

Comparison

Feature	claudemem	grep/Glob
Semantic understanding	✓	-
Call graph analysis	✓	-
PageRank ranking	✓	-
Exact string match	✓	✓
Works without index	-	✓

Tip: After using native tools, consider running claudemem index to enable semantic search for future investigations.

See ultrathink-detective skill for complete Fallback Protocol documentation.

---

Quality Checklist

Before completing a claudemem workflow, ensure:

• claudemem CLI is installed (v0.3.0+)
• Codebase is indexed (check with claudemem status)
• Checked index freshness before starting ⭐NEW in v0.5.0
• Started with map to understand structure ⭐CRITICAL
• Used --agent for all commands
• Validated results after every command ⭐NEW in v0.5.0
• Checked callers before modifying any symbol
• Focused on high-PageRank symbols first
• Read only specific file:line ranges (not whole files)
• Never silently switched to grep ⭐NEW in v0.5.0
• Reported search feedback if search command was used ⭐NEW in v0.8.0

---

Notes

• Requires OpenRouter API key for embeddings (https://openrouter.ai)
• Default model: voyage/voyage-code-3 (best code understanding)
• All data stored locally in .claudemem/ directory
• Tree-sitter provides AST parsing for TypeScript, Go, Python, Rust
• PageRank based on symbol call graph analysis
• Can run as MCP server with --mcp flag
• Initial indexing takes ~1-2 minutes for typical projects
• NEW in v0.3.0: map, symbol, callers, callees, context commands
• NEW in v0.3.0: PageRank ranking for symbol importance
• NEW in v0.3.0: --agent flag for clean, parseable output
• NEW in v0.4.0: dead-code, test-gaps, impact commands for code analysis
• NEW in v0.4.0: BFS traversal for transitive caller analysis
• NEW in v0.7.0: docs command for framework documentation fetching
• NEW in v0.7.0: Context7, llms.txt, DevDocs documentation providers
• NEW in v0.7.0: Unified search across code AND framework documentation
• NEW in v0.7.0: Auto-detection of dependencies from package.json, requirements.txt, go.mod, Cargo.toml

---

Maintained by: Jack Rudenko @ MadAppGang Plugin: code-analysis v2.8.0 Last Updated: December 2025 (v0.8.0 - Search feedback protocol)