codebase-memory-mcp

Product Introduction

1. Definition: codebase-memory-mcp is an open-source Model Context Protocol (MCP) server that functions as a local code intelligence engine. It is a structural-analysis backend that parses source code repositories into a persistent, queryable knowledge graph.
2. Core Value Proposition: It exists to solve the inefficiency of AI coding agents (like Claude Code) exploring codebases by reading files sequentially. By providing a graph of functions, classes, dependencies, and semantic relationships, it enables agents to answer structural questions with approximately 120x fewer tokens, drastically reducing cost and latency while improving accuracy.

Main Features

1. Persistent Knowledge Graph Indexing: The server uses Tree-sitter to parse 162 programming languages into an AST, then constructs a persistent SQLite-based graph database. This graph contains nodes for code symbols (functions, classes) and edges for relationships (CALLS, IMPORTS, DATA_FLOWS). Indexing is RAM-first with LZ4 compression for speed, with the Linux kernel (28M LOC) indexing in about 3 minutes.
2. Hybrid LSP Semantic Type Resolution: Beyond syntactic parsing, it embeds a lightweight C implementation of language-server-type resolution algorithms for key languages (Python, TypeScript/JavaScript, Go, C#, C/C++, Java, Kotlin, Rust, PHP). This resolves imports, generics, inheritance, and method dispatch to create accurate RESOLVED_CALLS edges without requiring a running language server process or per-project configuration.
3. Local Semantic & Similarity Search: Incorporates nomic-embed-code text embeddings (768-dimensional, int8) compiled directly into the binary to enable vector-based semantic code search. This allows finding conceptually similar code (e.g., publish when searching for send). It also computes SEMANTICALLY_RELATED and SIMILAR_TO graph edges using MinHash + LSH for clone detection, all processed 100% locally with no API calls.
4. Comprehensive MCP Tool Suite: Exposes 17 MCP tools for AI agents to query, including search_graph (regex/semantic), trace_path (call-graph BFS), detect_changes (git diff impact analysis), query_graph (Cypher-style queries), get_architecture, manage_adr (Architecture Decision Records), and check_index_coverage.
5. Cross-Repository & Infrastructure Intelligence: Can index multiple repositories into a single store, linking them with CROSS_* edges for a unified view. It also parses infrastructure-as-code (Dockerfiles, Kubernetes manifests) into the graph and detects cross-service links like REST/GraphQL API calls and pub/sub channels (EMITS/LISTENS_ON).

Problems Solved

1. Pain Point: The exorbitant token cost and high latency incurred by AI agents using a "grep → read file" loop to understand codebase structure, leading to inefficient exploration, context window waste, and the "lost in the middle" problem for answers.
2. Target Audience: Developers and engineering teams using AI coding assistants (Claude Code, Cursor, GitHub Copilot, etc.) who work on medium to large codebases. It is particularly valuable for software architects, onboarding developers, and teams performing code reviews, dead code cleanup, or impact analysis.
3. Use Cases: Essential for scenarios requiring deep, cross-file code understanding: rapidly tracing the call chain of a function during debugging, performing architectural audits, identifying dead code, assessing the impact of a proposed change (detect_changes), finding all usages of an API, or understanding dependencies between microservices.

Unique Advantages

1. Differentiation: Unlike cloud-based code search platforms or LLM-powered chatbots, codebase-memory-mcp is a local, specialized graph database with no embedded LLM and no data leaving the machine. Compared to other local code graph tools, its native executable requires no Docker or language runtime, and its Hybrid LSP provides IDE-grade type resolution without external LSP servers.
2. Key Innovation: The integration of fast, syntactic Tree-sitter parsing for 162 languages with a selective, embedded Hybrid LSP layer for deep semantic resolution in key languages. This two-tier approach delivers broad language support with high-fidelity intelligence for the most common stacks, all in a single, dependency-free binary.

Frequently Asked Questions (FAQ)

1. How does codebase-memory-mcp handle real-time code changes? It includes a background file watcher that performs incremental re-indexing on detected changes, typically completing in sub-millisecond time for minor edits. A full manual re-index is only needed for the initial build or after large Git operations like a pull.
2. Is an internet connection or API key required for semantic search? No. The semantic search capability is powered by the nomic-embed-code model which is compiled directly into the binary. All embedding inference and vector similarity calculations happen 100% on-device, ensuring complete privacy and offline functionality.
3. Can codebase-memory-mcp be used in CI/CD pipelines or team environments? Yes. The indexed graph artifact (.codebase-memory/graph.db.zst) is a compressed, portable file that can be committed to source control. Teammates can bootstrap from this snapshot, skipping the full indexing step and ensuring a consistent, shared view of the codebase structure.
4. What is the performance overhead of running this tool continuously? The indexing phase is memory and CPU-intensive but is typically a one-time or incremental operation. The query server runs as a separate process with minimal idle overhead. The native executable is optimized, and memory is released to the OS after the initial graph build.
5. Does it work with any MCP client, or only specific AI agents? It is compatible with any MCP-compatible client. The installation script automatically configures surfaces for over 40 detected clients (like Claude Code, Cursor, Zed) and provides instructions for manual setup with others (like Continue.dev, JetBrains IDEs).