I was giving my coding agent context the wrong way...
In a Nutshell
Codebase Memory MCP turns large codebases into searchable relationship graphs by extracting functions, classes, and messages programmatically, enabling agents to trace dependencies and blast radius without reading entire files. It reduces token consumption by ~50% during PR reviews and code searches by returning targeted graph results instead of raw code dumps. The system uses pre-tool hooks to inject graph context automatically, making it work seamlessly with existing grep workflows without requiring agents to learn new tools.
These notes were generated by AI and may contain inaccuracies.
When asking a coding agent to change something in a big codebase, the agent typically returns a wall of matches and opens 20 files one by one, still missing half the places that might break things. The codebase is already a map—every import, every function call is an edge. However, the agent throws away this structure and reads it as flat text. The solution is to turn the codebase into a map the agent can actually follow, enabling clear understanding of blast radius during PR reviews while cutting token consumption by almost 50%.
Codebase Memory MCP functions like providing a GPS map to the coding agent. Whenever cloud code makes changes to a file, it informs the coding agent about all related files. Many previous MCP tools attempted to solve codebase indexing and retrieval problems but failed because they used large language model pipelines to generate knowledge maps that quickly go out of date, or they didn't fit well into coding agent workflows.
Codebase Memory MCP is built mostly in C and C++, making it the fastest and most efficient code intelligence engine for coding agents. It can index the entire Linux kernel codebase in 3 minutes, and for normal smaller-sized codebases, it generates the index within seconds.
The problem it addresses occurs when agents work on big codebases, particularly monorepos. When asking about how certain functions are used, default tools start with grep searches returning numerous files. The agent must trace through different files one by one to get the full picture. Each file read dumps gigantic code files into the context window, which can blow up easily. Cloud Code has sub-agents to manage context for code search tasks, but this approach is quite slow. This problem becomes more significant with production codebases that often span multiple repos, making it difficult for agents to understand dependencies across different repositories.
Codebase Memory MCP extracts root functions, messages, and classes from code to build relationship graphs that help quickly understand code files without loading thousands of lines of code. These relationships can be built across different files—extracting functions, classes, and messages from three different files to create cross-file graphs. The same process applies across all files to build a gigantic codebase graph, even across different repositories.
This process happens quickly because there's no large language model involvement—it's purely programmatic. The agent has tooling to get a full picture much faster through:
- get architecture tool that returns a quick overview of codebase architecture for understanding overall structure
- search graph to locate specific nodes of functions when making changes
- trace path to map out code chains and understand function usage and dependencies
- graph queries to get information otherwise difficult to obtain, such as searching all files that call a handle order function but lack test coverage
Additional capabilities include getting code snippets of specific functions and detecting changes during PR reviews to easily understand architectural impact.
The most interesting aspect making this project more useful than others is its use of hooks. Previous projects failed because agents found it confusing when to use memory search tools versus normal grep tools. Coding agent providers like Cloud Code or Codex optimize their own grep tools, but this project addresses this by utilizing a pre-tool use hook.
Even if the agent forgets to do graph search and just uses normal grep search for a certain function, it will still perform normal grep and return information. Meanwhile, the pre-tool use hook captures the credit graph including additional rich information as part of the grep tool result. This design doesn't rely on the agent always calling the special MCP tool, representing a better design pattern than most MCP tools.
If you're building MCP tools, highly recommend adopting the pattern of utilizing Cloud Code or Codex hooks.
Installation offers two different commands: a basic version or one with graphic visualization of the graph. The UI version is recommended. Run the command with --UI flag to install MCP to the coding agent.
When opening the coding agent and telling it "Help me use codebase memory MCP," it starts asking for index setup. If the codebase already has good documentation, it applies filters—for example, identifying and ignoring Lexi folders. The entire codebase indexing takes only a few seconds, even for semi-complex monorepos with multiple subfolders.
Once indexing is complete, the agent can use tools like search graph to return everything related to a feature or search for certain patterns and queries. Call chains for specific functions can be easily traced to understand what else calls each function and get a full picture rather than missing important connections.
The UI version includes a web interface accessible by running "codebase memory MCP --UI=true" with a defined port. This provides a web UI for reviewing the graph.
To demonstrate capabilities, the codebase for Superdesign (a vibe design platform) was indexed. The backend function create design draft node serves as a tool agents call when given prompts, adding design nodes to an infinite canvas. A hidden feature called canvas lock prevents conflicts and race conditions when multiple agents create designs on the same canvas, ensuring everything flows through a queue.
The canvas lock is hidden—it isn't part of the create design tool file because the function delegates through layers rather than calling it directly. This protection is invisible from where the work starts, whether reading the file or grepping for "lock."
When asked to trace the create design draft node and canvas lock flow from memory notes, it runs a search for create design draft node execution and returns the full flow within seconds.
Practical usage includes asking what would break if changes are made to the lock, which identifies three different ways the lock is used. A comparison session without using Codebase Memory MCP shows significant token consumption differences.
For the first question, the context message part takes about 11,000 tokens with Codebase Memory MCP, versus around 38,000 tokens without it. For the second question "Trace what would break if I change the lock?", Codebase Memory MCP identifies all 13 different core sites while using 33,000 tokens total, compared to 64,000 tokens without it—doubling the consumption.
The setup code base harness skill has been updated to include this MCP. Running this skill sets up the codebase alongside other useful components like end-to-end tests, script toolkit for running server locally, and crap box for parallel agent testing in remote sandboxes. Additional skills help set up new loop engineers with best practices.
The project is open-source, with links included in the description. Searching for "GitHub AI Builder Club skill" leads to the repository as the first option.
Keep AI Jason in your library
Save the videos and channels worth coming back to, and find them again in one place.
