codebase-memory-mcp

Parses source code in 66 languages using tree-sitter grammar bindings (vendored C components) to extract structural entities: function/method definitions, class hierarchies, variable declarations, imports, and type annotations. The parsing engine operates as the first pass in a 7-pass indexing pipeline, converting raw source text into an intermediate AST representation that feeds downstream semantic analysis. Uses tree-sitter's incremental parsing to avoid re-parsing unchanged file regions during incremental reindexing.

Builds and maintains a queryable knowledge graph stored in SQLite WAL mode at ~/.cache/codebase-memory-mcp/codebase-memory.db. The graph schema models code entities (functions, classes, modules) as nodes and relationships (calls, inheritance, imports, type references) as edges. Exposes a Cypher query engine (src/store/store.c) for graph traversal, enabling sub-millisecond queries for structural patterns like 'find all callers of function X' or 'trace inheritance chain for class Y'. Supports incremental updates via content-hash-based change detection — only modified files trigger re-parsing and graph updates.

Performs community detection on the code graph to identify clusters of related entities (functions, classes, modules) that form logical architectural components. The indexing pipeline (Pass 6) uses graph clustering algorithms to group entities based on call frequency, shared dependencies, and module boundaries. Results are stored in the graph as 'BELONGS_TO_COMMUNITY' relationships, queryable via tools like 'find_communities' and 'find_community_members'. Useful for understanding codebase architecture, identifying tightly coupled components, and visualizing system structure.

Identifies test functions and links them to the code they test by analyzing test file naming conventions, test decorators, and assertion patterns. The indexing pipeline (Pass 7) detects test functions (e.g., functions starting with 'test_', methods in classes ending with 'Test', functions decorated with @test or @pytest.mark) and attempts to link them to the functions they test based on naming patterns and call graph analysis. Results are stored in the graph as 'TESTS' relationships, queryable via tools like 'find_tests_for_function' and 'find_tested_functions'.

Provides direct access to source code files and code snippets via tools like 'get_file_content' and 'get_code_snippet'. Supports retrieving entire files or specific line ranges, with optional syntax highlighting and context expansion. Useful for AI agents that need to read actual code after identifying relevant functions via graph queries. Integrates with graph queries to provide seamless navigation from structural queries (find_callers) to actual code inspection.

Detects references to configuration files, environment variables, and external dependencies by analyzing code patterns, imports, and config file references. The indexing pipeline (Pass 5) identifies config file paths (e.g., 'config.yaml', 'settings.json'), environment variable references (e.g., 'os.getenv("DATABASE_URL")'), and external dependencies (e.g., 'import requests', 'require("express")') and links them to the code that references them. Results are stored in the graph as 'REFERENCES_CONFIG', 'USES_ENV_VAR', and 'DEPENDS_ON' relationships.

Indexes codebases containing multiple programming languages (Python, Go, TypeScript, Rust, Java, C++, C#, Kotlin, Lua, Haskell, OCaml, Swift, Dart, MATLAB, Lean 4, Wolfram, and 48 more) in a single unified indexing pass. Each language is parsed using language-specific tree-sitter grammars, and semantic analysis (call resolution, type inference, HTTP route detection) is adapted to each language's semantics. Results are stored in a unified graph that enables cross-language queries (e.g., 'find all Python functions that call Go functions').

Executes a multi-stage indexing pipeline (src/pipeline/pipeline.c) that progressively enriches the graph: Pass 1 extracts structure (definitions, imports), Pass 2 resolves calls to their definitions, Pass 3 infers types and inheritance, Pass 4 detects HTTP links and routes, Pass 5 identifies config file references, Pass 6 performs community detection (clustering related entities), Pass 7 indexes test coverage. Each pass operates on the graph built by previous passes, enabling sophisticated analyses like 'find all functions that handle HTTP POST requests' or 'identify dead code by tracing reachability from entry points'. Type inference uses language-specific heuristics (e.g., Python type hints, Go explicit types, TypeScript annotations) to build a best-effort type map.

Detects file changes using content hashing (comparing SHA-256 hashes of file contents) and re-parses only modified files during incremental reindexing. The file watcher (src/pipeline/pipeline_incremental.c) polls the filesystem with adaptive intervals (5-60 seconds) and triggers incremental re-indexing when changes are detected. This approach avoids full-codebase re-parsing on every change, achieving ~4× faster reindexing than scanning all files. The graph is updated in-place, preserving query performance for unchanged portions of the codebase.

Exposes 14 code intelligence tools via the Model Context Protocol (MCP) specification, communicating with MCP clients (Claude Code, Cursor, Windsurf, Gemini CLI, VS Code, Zed) over stdio transport. The MCP server (src/mcp/mcp.c) implements a single-threaded event loop that parses incoming JSON-RPC requests, routes them to tool handlers, and returns structured results. Each tool maps to a specific graph query or code access operation (e.g., 'find_callers', 'find_callees', 'get_file_content'). Additionally, exposes all tools via CLI mode (codebase-memory-mcp cli <tool_name>) for scripting and testing without an MCP client.

Provides a web-based graph visualization UI (docs/index.html) that renders the indexed knowledge graph as an interactive node-link diagram. Users can click nodes to expand relationships, search for entities by name, and explore call graphs, inheritance hierarchies, and dependency chains visually. The UI queries the SQLite graph via the MCP tools, enabling real-time exploration without re-indexing. Useful for understanding codebase structure, identifying architectural patterns, and communicating code organization to team members.

Exposes graph query tools that answer project-level structural questions by traversing the knowledge graph. 'find_callers' returns all functions/methods that call a given function; 'find_callees' returns all functions called by a given function; 'trace_calls' returns the full call path from a source function to a target function. These queries operate on the pre-built graph, returning results in milliseconds without re-parsing. Supports filtering by language, module, or file path to narrow results in large codebases.

Detects HTTP routes and their handler functions by analyzing route definitions (decorators, function calls, config files) across frameworks (Express, FastAPI, Django, Spring, etc.). The indexing pipeline (Pass 4) uses pattern matching and AST analysis to identify route declarations (e.g., @app.route('/api/users'), router.get('/users/:id')) and link them to their handler functions. Supports extracting route parameters, HTTP methods, and middleware chains. Results are stored in the graph and queryable via tools like 'find_routes' and 'find_route_handlers'.

Resolves type relationships and inheritance hierarchies by analyzing class definitions, interface implementations, and type annotations. The indexing pipeline (Pass 3) uses language-specific heuristics to identify parent classes, implemented interfaces, and type parameters. Results are stored in the graph as 'INHERITS_FROM' and 'IMPLEMENTS' relationships, queryable via tools like 'find_subclasses', 'find_implementations', and 'trace_inheritance'. Supports both single and multiple inheritance, generic types, and mixins (where applicable).

Identifies unreachable code by performing reachability analysis from entry points (main functions, exported APIs, test entry points). The indexing pipeline uses graph traversal to mark all functions reachable from entry points, identifying functions with no incoming edges as potentially dead code. Supports filtering by module, file path, or function type (private vs. public) to reduce false positives. Results are queryable via tools like 'find_dead_code' and 'find_unreachable_functions'.