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: Understand Dependencies Before modifying code, understand what depends on it: ```bash # 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 ``` ```bash # 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: ```bash 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: ```bash # 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. ```bash 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. ```bash # 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. ```bash # 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 <symbol> Analyze the impact of changing a symbol using BFS traversal. ```bash # 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 |