mnemex-search

name	mnemex-search
description	Performs semantic code search and AST analysis via mnemex MCP/CLI — map, symbol, callers, callees, context, PageRank. Use when searching code, mapping a codebase, or auditing callers before refactor.
allowed-tools	Bash, Task, AskUserQuestion
user-invocable	false

Claudemem Semantic Code Search Expert (v0.20.1 MCP)

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

Tool Selection: When to Use mnemex vs Native Tools

Before starting any investigation, classify the task to pick the right tool.

Classify the Task

Task Type	Example	Use
"How does X work?"	"How does authentication work?"	mnemex search
Find implementations	"Find all API endpoints"	mnemex search
Architecture questions	"Map the service layer"	mnemex --agent map
Trace data flow	"How does user data flow?"	mnemex search
Audit integrations	"Audit Prime API usage"	mnemex search
Exact string match	"Find 'DEPRECATED_FLAG'"	Grep
Count occurrences	"How many TODO comments?"	Grep -c
Find specific symbol	"Find class UserService"	Grep
File patterns	"Find all *.config.ts"	Glob

Rule: Use mnemex for semantic/conceptual queries. Use Grep/Glob for exact matches only.

Check mnemex Status (MANDATORY for Semantic)

mnemex status

Status	Meaning	Next Action
Shows chunk count ("938 chunks")	Indexed	USE mnemex
"No index found"	Not indexed	Offer to index
"command not found"	Not installed	Fall back to Grep

Why Semantic Search is More Efficient

Approach	Token Cost	Result Quality
Read 5+ files sequentially	~5000 tokens	No ranking
Glob → Read all matches	~3000+ tokens	No semantic understanding
mnemex search once	~500 tokens	Ranked by relevance

Claudemem results include context around matches — you often don't need to read full files.

---

Bulk Read Optimization

Before executing bulk file operations, consider semantic search alternatives.

Decision Matrix

Situation	Intercept?	Action
Read 1–2 specific files	No	Proceed with Read
Read 3+ files in investigation	YES	Convert to mnemex search
Glob for exact filename	No	Proceed with Glob
Glob for pattern discovery	YES	Convert to mnemex search
Grep for exact string	No	Proceed with Grep
Grep for semantic concept	YES	Convert to mnemex search
Files mentioned in prompt	YES	Search semantically first

Interception Examples

Instead of reading multiple files:

Read src/services/auth/login.ts
Read src/services/auth/session.ts
Read src/services/auth/jwt.ts
Read src/services/auth/middleware.ts

Do:

mnemex search "authentication login session JWT middleware" -n 15

Instead of glob + sequential reads:

Glob("src/**/*.controller.ts") → Read all 15 controllers

Do:

mnemex search "HTTP controller endpoint route handler" -n 20

Interception protocol:

1. mnemex status — check if indexed
2. If indexed: replace bulk reads with one semantic query
3. If not indexed: mnemex index -y, then search
4. Read only specific file:line ranges from results

---

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

---

MCP Tool Integration (v0.20.1+)

In Claude Code with code-analysis plugin enabled, mnemex tools are available directly as MCP tools — no CLI invocation needed.

Available MCP Tools

Navigation & Search (9 tools):

Tool	Purpose
map	Repository structure with PageRank ranking
symbol	Find symbol definition (file:line)
callers	What calls this symbol?
callees	What does this symbol call?
context	Full call chain (callers + callees + dependencies)
search	Semantic vector search
search-with-context	Search + repository context
references	All references to a symbol (LSP-backed)
definition	Symbol definition with surrounding context

Edit & Refactor (4 tools) — prefer over Read+Edit for symbol modifications:

Tool	Purpose
edit_symbol	Replace a symbol's body by name. IMPORTANT: Always call think first.
edit_lines	Replace a line range. Use when symbol boundary is unclear.
restore_edit	Undo the last edit. ALWAYS available as a safety net.
rename_symbol	Rename across the entire codebase via LSP refactoring. Use dryRun=true first.

LSP Navigation (2 tools):

Tool	Purpose
define	Jump to declaration via live LSP — more precise than symbol for overloaded names
hover	Get type signature and documentation — richer than symbol's docstring field

Memory (4 tools) — persist findings across sessions:

Tool	Purpose
memory_write	Write a named note. Key convention: {project}/{topic}
memory_read	Read a previously written note by key
memory_list	List all memory keys, optionally filtered
memory_delete	Delete a memory entry (irreversible)

Reasoning (1 tool):

Tool	Purpose
think	Structured reflection. Returns a self-check prompt. Call before any edit.

Legacy Tools (9) — available but lower priority than Navigation & Search equivalents:

Tool	Purpose
dead-code	Find unreferenced symbols for cleanup
test-gaps	High-importance symbols missing tests
impact	BFS transitive caller analysis
dependency-graph	Transitive dependency visualization
import-paths	Analyze import patterns
test-impact	Impact analysis for tests
trace-execution	Execution flow analysis
dependency-analyzer	Dependency tree analysis
ast-structure	AST visualization

ANTI-PATTERNS

Anti-Pattern	Why It's Wrong	Preferred Alternative
Read whole file to find a function	Wastes tokens; index has exact locations	symbol → Read specific line range
Grep for text to find call sites	Misses type-aliased calls, cross-file calls	callers (AST-backed)
Manual search-and-replace for rename	Misses type annotations, generics, docs	rename_symbol with dryRun=true
Read + Edit to modify function body	Line numbers go stale after edits	edit_symbol (symbol-name-based)
define on every symbol	Expensive LSP call; index is usually sufficient	Use define only for overloaded names
memory_read on all available keys	Unnecessary context; slows session start	Read only keys relevant to task name

Dual-Mode: MCP + CLI

Both modes access the same index. Choose based on context:

Mode	When to Use	How
MCP tools	Direct invocation in Claude Code	Call map, symbol, etc. directly
CLI via Bash	Shell scripts, orchestration	Bash("mnemex --agent map 'query'")

---

Dual-Mode Quick Reference

# MCP mode (preferred in Claude Code — call tools directly)
# Call the 'map' MCP tool with query: "authentication flow"
# Call the 'symbol' MCP tool with name: "AuthService"

# CLI mode (Bash tool — for scripts or orchestration)
mnemex --agent map "authentication flow"
mnemex --agent symbol AuthService

---

Quick Reference (CLI)

# For agentic use, always use --agent flag for clean output
mnemex --agent <command>

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

---

Version Compatibility

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

mnemex --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=$(mnemex --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
  mnemex --agent dead-code  mnemex --agent test-gaps  mnemex --agent impact SymbolNameelse
  echo "Code analysis commands require mnemex 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=$(mnemex --agent impact SymbolName  2>/dev/null)
if [ -n "$IMPACT" ] && [ "$IMPACT" != "command not found" ]; then
  echo "$IMPACT"
else
  echo "Using fallback (direct callers only):"
  mnemex --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
mnemex --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
mnemex --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)
mnemex --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)
mnemex --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:

mnemex --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
mnemex --agent search "password hashing"
# Search with repo map context (recommended for complex tasks)
mnemex --agent search "password hashing" --map```

---

## Advanced Tool Workflows

### Edit Tools Workflow

Use `edit_symbol` to modify a function or class body without knowing the exact line numbers.

**Decision tree:**

Need to modify code? ├─ Modifying a whole function/class/method body? → edit_symbol ├─ Modifying a few lines within a body (and you have line numbers)? → edit_lines ├─ Result is wrong? → restore_edit (then try again) └─ Renaming across codebase? → rename_symbol with dryRun=true first

**Workflow: Edit a symbol**
1. Call `symbol` to confirm the exact symbol name
2. Call `think` — IMPORTANT: structured reflection before any edit
3. Call `edit_symbol` with the symbol name and new body
4. If result is incorrect: call `restore_edit` immediately, then revise approach

**Anti-patterns:**
- DO NOT use Read + Edit tool to replace function bodies — prefer `edit_symbol` (it's symbol-name-based, not line-number-based, and survives concurrent edits)
- DO NOT call `edit_symbol` without calling `think` first — edits without reflection have higher failure rates
- DO NOT use `edit_lines` when you know the symbol name — line numbers go stale after any edit

**IMPORTANT: Line numbers go stale.** After any `edit_symbol` or `edit_lines` call, all previously-obtained line numbers are invalid. Re-query if needed.

### LSP Navigation Workflow

Use `define` and `hover` to get live, language-server-backed type information before editing.

**`hover` vs `symbol` docstring field:**
- `symbol` docstring: extracted from AST at index time — may be stale
- `hover`: queried from live LSP — always current, includes inferred types

**`define` vs `symbol`:**
- `symbol`: AST-indexed lookup, fast, works offline
- `define`: LSP textDocument/definition, handles overloaded names and generics correctly

**Workflow: Understand a symbol before editing**
1. Call `hover` on the symbol to get its current type signature
2. Call `define` if the symbol is overloaded or if `symbol` returned multiple matches
3. Proceed with edit using confirmed type information

**When to prefer LSP Navigation:**
- Overloaded function names in Java, C++, or TypeScript
- Generic types where you need the concrete instantiation
- After the index may be stale (check `index_status` first)

### Rename Workflow

`rename_symbol` uses LSP to rename a symbol consistently across the entire codebase.

**ALWAYS run with `dryRun=true` first** to see the full scope of changes before committing.

**Workflow:**
1. Call `symbol` to confirm the exact canonical name
2. Call `rename_symbol` with `dryRun=true` — review the change list
3. If scope looks correct: call `rename_symbol` without `dryRun` to apply
4. Verify with `symbol` on the new name

**Example (Scenario 3: Refactoring from codebase-detective)**:

Task: Rename DatabaseConnection to DatabasePool

Old approach (error-prone): mnemex callers DatabaseConnection → manual grep → edit each file

New approach (correct): rename_symbol("DatabaseConnection", "DatabasePool", dryRun=true) → Review: 47 files affected, 82 occurrences rename_symbol("DatabaseConnection", "DatabasePool") → Done. All callers, imports, type annotations updated.

**Anti-pattern:** DO NOT use `callers` + manual edit for rename operations. `rename_symbol` handles:
- String literals that match the name (configurable)
- Type annotations and generics
- Import statements
- Test files

### Memory Workflow

Use memory tools to persist investigation findings across sessions.

**Key naming convention**: `{project}/{topic}` format
- Example: `auth/architecture` — authentication module architecture notes
- Example: `payment/known-issues` — known bugs in payment flow
- Example: `global/code-style` — project-wide coding conventions

**Workflow: Write findings**
1. After completing an investigation, call `memory_write` with a descriptive key
2. Content: bullet-point summary (not full code — keep it < 500 chars)
3. Start new sessions with `memory_list` to see what's already known

**Workflow: Read findings**
1. Call `memory_list` at session start to see available notes
2. Call `memory_read` only when the key is relevant to current task
3. DO NOT read all memories — only read those relevant by key name

**Anti-patterns:**
- DO NOT write large code blocks to memory — write summaries and file:line references instead
- DO NOT call `memory_read` for every available key — infer relevance from the key name
- DO NOT `memory_delete` without user confirmation — deletion is irreversible

---

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

### mnemex map [query]

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

```bash
# Full repo map (top symbols by PageRank)
mnemex --agent map
# Focused on specific task
mnemex --agent map "authentication"
# Limit tokens
mnemex --agent map "auth" --tokens 500```

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

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

### mnemex symbol <name>

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

```bash
mnemex --agent symbol Indexermnemex --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

mnemex callers

Find all symbols that call/reference the given symbol.

mnemex --agent callers AuthService```

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

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

### mnemex callees <name>

Find all symbols that the given symbol calls/references.

```bash
mnemex --agent callees AuthService```

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

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

### mnemex context <name>

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

```bash
mnemex --agent context Indexermnemex --agent context Indexer --callers 10 --callees 20```

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

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

### mnemex search <query>

Semantic search across the codebase.

```bash
mnemex --agent search "error handling"mnemex --agent search "error handling" --map   # include repo map
mnemex --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)

mnemex dead-code

Find unused symbols in the codebase.

# Find all unused symbols
mnemex --agent dead-code
# Stricter threshold (only very low PageRank)
mnemex --agent dead-code --max-pagerank 0.005
# Include exported symbols (usually excluded)
mnemex --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=$(mnemex --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

mnemex test-gaps

Find high-importance code without test coverage.

# Find all test coverage gaps
mnemex --agent test-gaps
# Only critical gaps (high PageRank)
mnemex --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=$(mnemex --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

mnemex impact

Analyze the impact of changing a symbol using BFS traversal.

# Get all transitive callers
mnemex --agent impact UserService
# Limit depth for large codebases
mnemex --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=$(mnemex --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: mnemex --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)
mnemex --agent search "authentication" --use-case navigation
# Default search (balanced)
mnemex --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
mnemex --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
mnemex --agent search "file:services purpose" --use-case navigation
# Find anti-patterns to avoid
mnemex --agent search "anti_pattern SQL"```

### Regenerating Enrichments

If codebase changes significantly:

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

# Or enrich specific files
mnemex 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=$(mnemex --agent symbol FunctionFromStackTrace )
if [ -z "$SYMBOL" ]; then
  echo "Symbol not found - check spelling or run: mnemex --agent map 'related keywords' "
  exit 1
fi

# Step 2: Get full context (callers + callees)
mnemex --agent context FunctionFromStackTrace
# Step 3: Trace backwards to find root cause
mnemex --agent callers suspectedSource
# Step 4: Check full impact of the bug (v0.4.0+)
IMPACT=$(mnemex --agent impact BuggyFunction  2>/dev/null)
if [ -n "$IMPACT" ]; then
  echo "$IMPACT"
else
  echo "Impact analysis requires mnemex v0.4.0+ or no callers found"
  echo "Fallback: mnemex --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=$(mnemex --agent map "feature area keywords" )
if [ -z "$MAP" ]; then
  echo "No matches found - try broader keywords"
fi

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

# Step 6: Check test coverage gaps (v0.4.0+)
GAPS=$(mnemex --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=$(mnemex --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=$(mnemex --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):"
  mnemex --agent callers SymbolToRenamefi

# Step 3: Group by file for systematic updates

# Step 4: Update each caller location systematically

# Step 5: Verify all callers updated
mnemex --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=$(mnemex --agent map )
if [ -z "$MAP" ]; then
  echo "Index may be empty - run: mnemex 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
mnemex --agent context PillarSymbol
# Step 4: Trace major flows via callees
mnemex --agent callees EntryPoint
# Step 5: Identify dead code (cleanup opportunities) (v0.4.0+)
DEAD=$(mnemex --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=$(mnemex --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
mnemex --agent map "auth permission security token"
# Step 2: Find authentication entry points
SYMBOL=$(mnemex --agent symbol authenticate )
if [ -z "$SYMBOL" ]; then
  echo "No 'authenticate' symbol - try: login, verify, validate"
fi
mnemex --agent callers authenticate
# Step 3: Trace authentication flow
mnemex --agent callees authenticate
# Step 4: Check authorization patterns
mnemex --agent map "authorize permission check guard"
# Step 5: Find sensitive data handlers
mnemex --agent map "password hash token secret key"
# Step 6: Check for test coverage on security code (v0.4.0+)
GAPS=$(mnemex --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
mnemex --agent map "authentication null pointer"
# Step 2: Locate the specific symbol mentioned in error
mnemex --agent symbol authenticate
# Step 3: Check what calls it (to understand how it's used)
mnemex --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
mnemex --agent map "API endpoints rate"
# Step 2: Find the main API handler
mnemex --agent symbol APIController
# Step 3: See what the API controller depends on
mnemex --agent callees APIController
# Step 4: Check if rate limiting already exists somewhere
mnemex --agent search "rate limit"
# Step 5: Get full context for the modification point
mnemex --agent context APIController```

### Scenario 3: Refactoring

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

```bash
# Step 1: Find the symbol
mnemex --agent symbol DatabaseConnection
# Step 2: Find ALL callers (these all need updating)
mnemex --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
mnemex --agent map "indexing pipeline"
# Step 2: Find the main entry point (highest PageRank)
mnemex --agent symbol Indexer
# Step 3: Trace the flow - what does Indexer call?
mnemex --agent callees Indexer
# Step 4: For each major callee, get its callees
mnemex --agent callees VectorStoremnemex --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. mnemex --agent map "<task keywords>"   → Understand structure, identify key symbols
   ↓
3. mnemex --agent symbol <high-pagerank-symbol>   → Get exact location
   ↓
4. mnemex --agent callers <symbol>   (if modifying)
   → Know the impact radius
   ↓
5. mnemex --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	mnemex --agent map "task"	Saves tokens, finds relevant files
grep -r "Database" src/	mnemex --agent symbol Database	Semantic relationships, not just strings
Edit without caller check	mnemex --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
mnemex search "query"	mnemex --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	mnemex --agent map "query" --tokens 2000
-n N	Limit result count	mnemex --agent search "auth" -n 10
--page-size N	Pagination	mnemex --agent search "x" --page-size 20
--max-depth N	Limit traversal	mnemex --agent context Func --max-depth 3

Tip: Piping to file preserves full output: mnemex --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"	mnemex --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. mnemex --agent map "task"                          │
│     → Understand structure, find high-PageRank symbols          │
│                                                                  │
│  2. mnemex --agent symbol <name>                       │
│     → Get exact file:line location                              │
│                                                                  │
│  3. mnemex --agent callers <name>                      │
│     → Know impact radius BEFORE modifying                       │
│                                                                  │
│  4. mnemex --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 mnemex CLI is available
which mnemex || command -v mnemex

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

Installation Options

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

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

Index Codebase

# Index current project
mnemex index

# Check status
mnemex --version && ls -la .mnemex/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
mnemex docs status            # Show indexed libraries and cache state
mnemex docs fetch             # Fetch docs for all detected dependencies
mnemex docs fetch react vue   # Fetch specific libraries
mnemex docs providers         # List available documentation providers
mnemex docs refresh           # Force refresh all cached documentation
mnemex docs clear             # Clear all documentation cache
mnemex 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)
mnemex 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
mnemex 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
mnemex 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
mnemex docs fetch fastapi

# View available providers
mnemex docs providers

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

Unified Search (Code + Documentation)

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

mnemex --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	mnemex docs fetch	Index docs for all dependencies
Learning new library	mnemex docs fetch <library>	Get searchable reference
Updated dependencies	mnemex docs refresh	Refresh to get new versions
Check what's indexed	mnemex docs status	View cache state
Clear space	mnemex 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)
mnemex docs status || mnemex docs fetch

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

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

Version Information

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

mnemex --version
# Expected: 0.7.0 or higher

Note: If mnemex docs help returns "Unknown command", upgrade your mnemex 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
mnemex feedback --query "your original query" \
  --helpful id1,id2 \
  --unhelpful id3,id4

# Result IDs are shown in search output:
mnemex 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 mnemex feedback --help 2>&1 | grep -qi "feedback"; then
    timeout 5 mnemex feedback --query "$SEARCH_QUERY" \
      --helpful "${HELPFUL_IDS}" \
      --unhelpful "${UNHELPFUL_IDS}" 2>/dev/null || true
  else
    echo "Note: Search feedback requires mnemex 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 mnemex feedback --help 2>&1 | grep -qi "feedback"; then
  FEEDBACK_AVAILABLE=true
else
  echo "Note: Search feedback requires mnemex v0.8.0+"
fi

# 1. Search and capture IDs
RESULTS=$(mnemex --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 mnemex feedback \
    --query "$SEARCH_QUERY" \
    --helpful "$(IFS=,; echo "${HELPFUL[*]}")" \
    --unhelpful "$(IFS=,; echo "${UNHELPFUL[*]}")" \
    2>/dev/null || echo 

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 .mnemex/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" .mnemex/index.db 2>/dev/null)
  else
    INDEX_TIME=$(stat -c "%y" .mnemex/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 mnemex 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 mnemex 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=$(mnemex --agent map "authentication" )
EXIT_CODE=$?

if [ "$EXIT_CODE" -ne 0 ]; then
  echo "ERROR: mnemex command failed"
  # Diagnose index health
  DIAGNOSIS=$(mnemex --version && ls -la .mnemex/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=$(mnemex --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=$(mnemex --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 mnemex returns no results or the index isn't available:

1. Check index status - Run mnemex status to verify
2. Try different query - Rephrase or use more specific terms
3. Reindex if needed - Run mnemex 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

Comparison

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

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

---

Quality Checklist

Before completing a mnemex workflow, ensure:

• mnemex CLI is installed (v0.3.0+)
• Codebase is indexed (check with mnemex 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 .mnemex/ 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 v5.0.0 Last Updated: March 2026 (v5.0.0 - Absorbed code-search-selector and search-interceptor)