codebase-memory-mcp-intelligence

# codebase-memory-mcp Intelligence > Skill by [ara.so](https://ara.so) — MCP Skills collection. ## Overview codebase-memory-mcp is a high-performance code intelligence MCP server that indexes codebases into persistent knowledge graphs. It parses 155 languages using tree-sitter ASTs, resolves call graphs, detects HTTP routes, and enables sub-millisecond structural queries. The Linux kernel (28M LOC) indexes in 3 minutes; average repos in milliseconds. Key capabilities: - **Graph-based code intelligence**: Functions, classes, calls, imports, inheritance as queryable nodes/edges - **Structural search**: Find symbols by pattern, trace call chains, detect dead code - **Architecture analysis**: Community detection, hotspots, layering, cross-service HTTP linking - **Semantic search**: Vector search with bundled embeddings (no API key required) - **155 languages**: Tree-sitter grammars compiled into a single static binary - **14 MCP tools**: All accessible via natural language in any compatible agent ## Installation ### Quick Install (macOS/Linux) ```bash # Standard version curl -fsSL https://raw.githubusercontent.com/DeusData/codebase-memory-mcp/main/install.sh | bash # With graph visualization UI curl -fsSL https://raw.githubusercontent.com/DeusData/codebase-memory-mcp/main/install.sh | bash -s -- --ui ``` ### Windows (PowerShell) ```powershell Invoke-WebRequest -Uri https://raw.githubusercontent.com/DeusData/codebase-memory-mcp/main/install.ps1 -OutFile install.ps1 .\install.ps1 ``` ### Manual Installation Download from [releases](https://github.com/DeusData/codebase-memory-mcp/releases/latest): ```bash # Extract and run installer tar xzf codebase-memory-mcp-*.tar.gz ./install.sh ``` The installer auto-detects Claude Code, Cursor, Codex CLI, Gemini CLI, Zed, OpenCode, Aider, VS Code, and other agents, configuring MCP entries automatically. ### Verify Installation ```bash codebase-memory-mcp --version ``` Restart your coding agent after installation. ## Core Usage Patterns ### Indexing a Codebase **Via agent (recommended):** ``` User: Index this project ``` The MCP server will call `index_repository` with the current working directory. **Via CLI:** ```bash codebase-memory-mcp index /path/to/repo ``` **Enable auto-indexing:** ```bash codebase-memory-mcp config set auto_index true codebase-memory-mcp config set auto_index_limit 50000 ``` Auto-index runs on MCP session start for new projects and registers existing projects with the background file watcher. ### Architecture Overview Get a complete architectural summary in one call: ``` User: Show me the architecture of this codebase ``` This invokes `get_architecture` which returns: - Languages and package structure - Entry points (main functions, HTTP handlers) - HTTP/gRPC/GraphQL routes - Hotspot functions (high in/out degree) - Module boundaries via Louvain clustering - Layering analysis (presentation/business/data) **Example response structure:** ```json { "languages": ["TypeScript", "Python", "Go"], "packages": ["src/api", "src/services", "src/models"], "entry_points": [ {"name": "main", "file": "src/index.ts", "type": "Function"} ], "routes": [ {"path": "/api/users", "method": "GET", "handler": "getUsers", "file": "src/api/users.ts"} ], "hotspots": [ {"name": "processRequest", "in_degree": 15, "out_degree": 8, "file": "src/services/request.ts"} ], "boundaries": [ {"module": "Community_0", "members": ["src/api/*"], "internal_edges": 45, "external_edges": 12} ] } ``` ### Searching the Graph **Find symbols by name pattern:** ``` User: Find all functions with "Handler" in the name ``` Uses `search_graph`: ```json { "name_pattern": ".*Handler.*", "labels": ["Function"] } ``` **Find high-degree nodes:** ``` User: Show me the most called functions ``` ```json { "labels": ["Function"], "min_in_degree": 5, "limit": 20 } ``` **Scope to specific files:** ``` User: Find all classes in the auth module ``` ```json { "labels": ["Class"], "file_pattern": ".*/auth/.*" } ``` ### Call Tracing **Find all callers:** ``` User: What calls the authenticate function? ``` Uses `get_callers`: ```json { "symbol_name": "authenticate", "max_depth": 3 } ``` **Trace call chain:** ``` User: Trace the execution path from main to database functions ``` Uses `trace_symbol`: ```json { "symbol_name": "main", "direction": "outgoing", "max_depth": 5, "edge_types": ["CALLS"] } ``` ### Semantic Search **Find related code by concept:** ``` User: Find authentication-related functions ``` Uses `semantic_query`: ```json { "query": "authentication jwt token validation", "limit": 10 } ``` Semantic search uses bundled Nomic embeddings (no API key required) with 11-signal scoring: - TF-IDF relevance - AST structural similarity - API signature matching - Data flow patterns - MinHash near-clone detection ### Cypher-Like Queries **Advanced graph queries:** ``` User: Run a Cypher query to find all functions that call database operations ``` Uses `cypher_query`: ```cypher MATCH (f:Function)-[:CALLS]->(db:Function) WHERE db.name CONTAINS 'query' OR db.name CONTAINS 'exec' RETURN f.name, f.file, COUNT(db) as db_calls ORDER BY db_calls DESC LIMIT 20 ``` **Find inheritance hierarchies:** ```cypher MATCH (c:Class)-[:INHERITS*1..3]->(base:Class) WHERE base.name = 'BaseModel' RETURN c.name, c.file ``` **HTTP route to implementation:** ```cypher MATCH (r:Route)-[:HANDLED_BY]->(h:Function)-[:CALLS]->(s:Function) WHERE r.path CONTAINS '/api/users' RETURN r.path, h.name, COLLECT(s.name) as services ``` ### Dead Code Detection ``` User: Find unused functions ``` Uses `find_dead_code`: ```json { "entry_points": ["main", "handler"], "min_depth": 2 } ``` Returns functions with zero incoming `CALLS` edges, excluding recognized entry points (main, init, handlers, tests). ### Change Impact Analysis **Detect impact of uncommitted changes:** ``` User: What's affected by my recent changes? ``` Uses `detect_changes`: ```json { "include_tests": true } ``` Returns: - Changed symbols with confidence scores - Affected downstream symbols (via call graph) - Risk classification (CRITICAL/HIGH/MEDIUM/LOW) - Test coverage mapping **Example response:** ```json { "changed_symbols": [ { "name": "authenticate", "type": "Function", "file": "src/auth.ts", "confidence": 0.95, "change_type": "modified" } ], "affected_symbols": [ { "name": "loginHandler", "type": "Function", "file": "src/handlers/login.ts", "distance": 1, "risk": "HIGH" } ] } ``` ### Architecture Decision Records (ADR) **Create ADR:** ``` User: Document our decision to use Redis for session storage ``` Uses `manage_adr`: ```json { "action": "create", "title": "Use Redis for Session Storage", "status": "accepted", "context": "Need fast, distributed session management", "decision": "Adopt Redis with session TTL and clustering", "consequences": "Requires Redis infrastructure; enables horizontal scaling" } ``` **List ADRs:** ``` User: Show all architecture decisions ``` ```json { "action": "list" } ``` **Update ADR:** ```json { "action": "update", "id": "ADR-001", "status": "superseded" } ``` ### Cross-Service Analysis **Find HTTP call sites:** ``` User: Show all external API calls ``` Uses `search_graph` with HTTP edge filters: ```json { "edge_types": ["HTTP_CALLS"], "labels": ["Function"] } ``` **Trace cross-service dependencies:** ```cypher MATCH (f:Function)-[:HTTP_CALLS]->(r:Route) RETURN f.name, f.file, r.path, r.method ``` ## Configuration ### View Current Config ```bash codebase-memory-mcp config list ``` ### Key Settings ```bash # Auto-index on session start codebase-memory-mcp config set auto_index true # File limit for auto-indexing codebase-memory-mcp config set auto_index_limit 50000 # Enable background file watcher codebase-memory-mcp config set watch true # Embedding model (default: nomic-embed-code) codebase-memory-mcp config set embedding_model nomic-embed-code # Graph visualization port codebase-memory-mcp config set ui_port 9749 ``` ### Ignore Patterns Create `.cbmignore` in your repo root (gitignore syntax): ``` node_modules/ *.test.ts dist/ build/ *.min.js vendor/ ``` Default ignores: `node_modules`, `.git`, `dist`, `build`, `vendor`, `.venv`, `__pycache__` ## Advanced Features ### Graph Visualization UI Launch with UI enabled: ```bash codebase-memory-mcp --ui=true --port=9749 ``` Open `http://localhost:9749` for 3D interactive graph exploration. Features: - Force-directed layout with community coloring - Filter by label, file, package - Click nodes to see properties and edges - Multi-galaxy layout for cross-repo graphs ### Team-Shared Graph Artifact Commit compressed graph to avoid reindexing: ```bash # After indexing, compress the graph codebase-memory-mcp export --output=.codebase-memory/graph.db.zst # Commit to repo git add .codebase-memory/graph.db.zst git commit -m "Add codebase graph snapshot" ``` Teammates run: ```bash codebase-memory-mcp import --input=.codebase-memory/graph.db.zst ``` ### CLI Mode Use without MCP for scripting: ```bash # Search codebase-memory-mcp cli search_graph '{"name_pattern": ".*Service$", "labels": ["Class"]}' # Cypher query codebase-memory-mcp cli cypher_query 'MATCH (f:Function) WHERE f.name = "main" RETURN f' # Get architecture codebase-memory-mcp cli get_architecture '{}' # Semantic search codebase-memory-mcp cli semantic_query '{"query": "database connection pooling", "limit": 5}' ``` ### Language-Specific Features **Go:** - Package resolution via `go.mod` - Interface implementation detection - Struct method resolution