Codebase Query

codebase-query

Query and analyze codebases using codebase-memory-mcp semantic graph.

Triggers

• /codebase-query, /cbm, /code-graph
• "query the codebase graph"
• "find functions that call X"
• "show me high complexity functions"
• "what implements this interface"
• "analyze code complexity"
• "map the architecture"
• "find technical debt"

Instructions

You are a codebase graph query assistant. Use codebase-memory-mcp to answer questions about code structure, complexity, dependencies, and architecture.

Core Capabilities

1. Search & Discovery

   • Find functions/methods, interfaces, types by name pattern
   • Get function implementations and signatures
   • Discover entry points and exported APIs
   • Grep-like code search via search_code

2. Call Graph Analysis

   • Trace callers and callees
   • Map execution flows
   • Find hot paths and bottlenecks

3. Complexity & Quality

   • Identify high-complexity functions
   • Find functions with many parameters
   • Detect unguarded recursion
   • Locate potential code smells

4. Architecture Insights

   • High-level overview via get_architecture
   • Schema discovery via get_graph_schema
   • Map service boundaries
   • Find cross-service dependencies
   • Discover interface implementations
   • Track HTTP endpoints and async patterns

Query Patterns

Note: In Claude Code, codebase-memory-mcp MCP tools are available natively. Prefer calling them directly over CLI. CLI examples use 2>&1 | grep -v "^level=" to suppress logs.

For Quick Overview (unfamiliar codebase)

Use get_architecture and get_graph_schema:

codebase-memory-mcp cli get_architecture '{"project": "...", "aspects": ["entry_points"]}' 2>&1 | grep -v "^level="
codebase-memory-mcp cli get_graph_schema '{"project": "..."}' 2>&1 | grep -v "^level=" | jq '.node_labels[] | {label: .label, count: .count}'

For Simple Lookups

Use search_graph or trace_path:

codebase-memory-mcp cli search_graph '{"project": "...", "name_pattern": ".*Router.*", "label": "Function"}' 2>&1 | grep -v "^level="
codebase-memory-mcp cli trace_path '{"project": "...", "function_name": "CreateEvent", "direction": "both", "max_depth": 2}' 2>&1 | grep -v "^level="

For Grep-Like Search

Use search_code when looking for string literals or patterns:

codebase-memory-mcp cli search_code '{"project": "...", "pattern": "GetOrgRegion", "file_pattern": "*.go", "limit": 10}' 2>&1 | grep -v "^level="

For Complex Analysis

Use query_graph with Cypher:

codebase-memory-mcp cli query_graph '{
  "project": "...",
  "query": "MATCH (f:Function) WHERE f.complexity > 15 AND f.is_test = false RETURN f.name, f.complexity, f.file_path ORDER BY f.complexity DESC LIMIT 10"
}' 2>&1 | grep -v "^level="

Project Name Detection

When in a repository:

1. First try list_projects to find the indexed project name
2. Project names follow pattern: Users-meain-dev-folder-repo (path with slashes replaced by dashes)
3. For /Users/acme/dev/myapp/backend → Users-acme-dev-myapp-backend
4. On an unfamiliar project, follow with get_graph_schema to discover available node types and properties

Common Queries

Find high complexity:

MATCH (f:Function) 
WHERE f.complexity > 15 AND f.is_test = false 
RETURN f.name, f.complexity, f.file_path 
ORDER BY f.complexity DESC LIMIT 10

Find interface implementations:

MATCH (s)-[:IMPLEMENTS]->(i:Interface {name: 'InterfaceName'}) 
RETURN s.name, s.file_path

Find functions with many parameters:

MATCH (f:Function) 
WHERE f.param_count > 7 AND f.is_test = false 
RETURN f.name, f.param_count, f.file_path 
ORDER BY f.param_count DESC LIMIT 10

Find entry points:

MATCH (f:Function) 
WHERE f.is_entry_point = true 
RETURN f.name, f.file_path

Find hot paths (most-called functions):

MATCH ()-[:CALLS]->(f:Function)
WHERE f.is_test = false
WITH f, count(*) as call_count
RETURN f.name, call_count, f.file_path
ORDER BY call_count DESC LIMIT 15

Find recursive functions:

MATCH (f:Function) 
WHERE f.recursive = true 
RETURN f.name, f.file_path

Find HTTP endpoints:

MATCH (f:Function)-[h:HTTP_CALLS]->(target) 
RETURN f.name, h.url_path, f.file_path 
LIMIT 15

Find external dependencies:

MATCH (p:Package) 
WHERE p.external = true 
RETURN p.name 
ORDER BY p.name

Find similar functions (duplication candidates):

MATCH (f1:Function)-[s:SIMILAR_TO]->(f2:Function)
WHERE s.same_file = false AND s.jaccard > 0.7
RETURN f1.name, f2.name, s.jaccard, f1.file_path, f2.file_path
LIMIT 10

Cypher Query Tips

Boolean comparisons:

• ✓ Use f.is_test = false
• ✗ Don't use NOT f.is_test (syntax error)

String operations:

• f.file_path STARTS WITH 'services/'
• f.file_path ENDS WITH '_test.go'
• f.file_path CONTAINS 'organchor'
• toLower(f.name) CONTAINS 'anchor'

Aggregation:

MATCH (f:Function)-[:CALLS]->(target)
WITH f, count(*) as call_count
RETURN f.name, call_count
ORDER BY call_count DESC

Limitations:

• Variable-length paths (*1..3) not supported
• Some boolean operators cause errors
• Keep queries focused with WHERE and LIMIT

Available Properties

Function / Method nodes (both types carry the same properties):

• name, qualified_name, file_path, signature
• complexity, cognitive (complexity metrics)
• param_count, loop_count, loop_depth
• is_exported, is_test, is_entry_point
• recursive, unguarded_recursion
• lines, docstring

Relationships:

• :CALLS - function calls
• :IMPLEMENTS - interface implementation
• :IMPORTS - module imports
• :USAGE - symbol usage (largest edge set)
• :TESTS - test relationships (may be sparse)
• :SIMILAR_TO - code similarity (has .jaccard and .same_file properties)
• :HTTP_CALLS - HTTP endpoints (has .url_path property)
• :ASYNC_CALLS - async patterns (has .broker property)
• :CONFIGURES - config access (has .config_key property)

Output Processing

Filter stderr and parse JSON:

codebase-memory-mcp cli query_graph '...' 2>&1 | grep -v "^level=" | jq .
# For user-friendly tabular output:
| jq -r '.rows[] | "\(.[0]): \(.[1]) (\(.[2]))"'