Codebase Memory MCP Tutorial: Millisecond Code Intelligence for AI Agents

Created

Ever had your AI agent burn through 412,000 tokens grepping through files to answer a simple structural question? Five graph queries should cost 3,400 tokens — but without a code intelligence layer, the agent resorts to dozens of grep/read calls, burning money and missing context.

Codebase Memory MCP solves this. It’s a pure-C code intelligence engine that builds a knowledge graph of your entire codebase in milliseconds, then exposes it via MCP so your AI agent can query call chains, cross-service dependencies, dead code, and more — 120x fewer tokens than file-by-file exploration.

What is Codebase Memory MCP? An open-source code intelligence engine (MIT license) by DeusData, built in pure C with zero dependencies. Uses tree-sitter AST analysis and Hybrid LSP semantic resolution to build persistent knowledge graphs across 158 languages. Exposes 14 MCP tools compatible with Claude Code, Codex, Gemini CLI, and 8 other AI coding agents. Ships as a single static binary.

Key Data:

  • 🌟 GitHub Stars: Rapidly growing (Repository)
  • 📦 Current Version: v0.8.0
  • ⚖️ License: MIT License
  • 🧠 Core Feature: 158 language support with Hybrid LSP semantic type resolution for 9 major languages
  • 📦 Core Feature: Linux kernel (28M LOC) indexed in 3 minutes, query latency <1ms
  • 🔒 Security: SLSA Level 3 + VirusTotal 70+ engines zero detections + CodeQL SAST
  • 📄 Research paper: arXiv:2603.27277

Prerequisites

Before installing Codebase Memory MCP, you need:

  • An AI coding tool: Claude Code, Codex CLI, Gemini CLI, Zed, VS Code, or any MCP-compatible agent
  • Operating system: macOS (arm64/amd64), Linux (arm64/amd64), or Windows (amd64)
  • No additional dependencies: no Docker, no API keys, no runtime requirements

Overview

This Codebase Memory MCP setup guide covers:

  1. One-command installation into your AI coding tool
  2. Indexing your first codebase
  3. Using 14 MCP tools for code queries
  4. Configuration across major AI tools

Step-by-Step Guide

Step 1: One-Command Install

macOS / Linux:

1
curl -fsSL https://raw.githubusercontent.com/DeusData/codebase-memory-mcp/main/install.sh | bash

With graph visualization UI:

1
curl -fsSL https://raw.githubusercontent.com/DeusData/codebase-memory-mcp/main/install.sh | bash -s -- --ui

Windows (PowerShell):

1
2
Invoke-WebRequest -Uri https://raw.githubusercontent.com/DeusData/codebase-memory-mcp/main/install.ps1 -OutFile install.ps1
.\install.ps1

The installer automatically:

  1. Downloads the single static binary for your platform
  2. Detects all installed AI coding tools
  3. Configures MCP server entries, instruction files, and hooks for each

Also available via package managers: Homebrew, AUR, npm, PyPI, Scoop, Winget, Chocolatey.

💡 Tip: Windows users may see a SmartScreen warning. Click “More info” → “Run anyway”. Every release has SHA-256 checksums for verification.

Step 2: Install in Your AI Tool

Codebase Memory MCP’s install command auto-detects and configures 11 AI coding tools:

AI Tool Config Instructions Hooks
Claude Code .claude/.mcp.json 4 Skills PreToolUse (Grep/Glob graph augment)
Codex CLI .codex/config.toml .codex/AGENTS.md SessionStart reminder
Gemini CLI .gemini/settings.json .gemini/GEMINI.md BeforeTool + SessionStart
VS Code Code/User/mcp.json — —
Zed settings.json — —
OpenCode opencode.json AGENTS.md —
Aider — CONVENTIONS.md —
OpenClaw openclaw.json — —
Others KiloCode / Antigravity / Kiro Auto-configured Auto-configured

Universal: The install script configures all detected agents. Restart your agent to activate.

Claude Code manual config (if auto-config didn’t work):

Add to ~/.claude/.mcp.json (global) or project .mcp.json:

1
2
3
4
5
6
7
8
{
  "mcpServers": {
    "codebase-memory-mcp": {
      "command": "/path/to/codebase-memory-mcp",
      "args": []
    }
  }
}

After restart, verify with /mcp — you should see codebase-memory-mcp with 14 tools.

Codex CLI manual config:

Add a Codebase Memory MCP reference in your project’s AGENTS.md, or configure the MCP server in .codex/config.toml.

Step 3: Index Your First Codebase

After restarting your agent, just say:

1
Index this project

Or via CLI:

1
codebase-memory-mcp cli index_repository '{"repo_path": "/path/to/your/repo"}'

Performance reference:

Operation Time Notes
Linux kernel full index 3 min 28M LOC, 75K files
Django full index ~6s 49K nodes, 196K edges
Cypher query <1ms Relationship traversal
Trace call path (depth=5) <10ms BFS traversal

Step 4: Use the 14 MCP Tools

Once indexed, ask questions in natural language or call tools directly:

Structural queries:

  • “Who calls ProcessOrder?” → trace_path
  • “Find all functions with zero callers” → dead code detection
  • “What’s the overall architecture?” → get_architecture

Search:

  • “Search for functions named Handler” → search_graph
  • “Run a Cypher query for all functions” → query_graph (openCypher subset)

Change analysis:

  • “What does this git diff affect?” → detect_changes (blast radius with risk classification)

Cross-service linking: HTTP route matching, gRPC/GraphQL/trPC detection, Socket.IO/EventEmitter channel detection.

Step 5: Enable Auto-Index

Auto-index new projects on first connection:

1
codebase-memory-mcp config set auto_index true

Configurable file limit: config set auto_index_limit 50000.

Step 6: Update

1
codebase-memory-mcp update

The MCP server also checks for updates on startup.

Core Features Deep Dive

Hybrid LSP: Semantic Resolution Beyond Tree-Sitter

Tree-sitter provides syntactic AST analysis but can’t resolve types across modules. Codebase Memory MCP includes Hybrid LSP — a lightweight C implementation of language type-resolution algorithms, compatible with tsserver, pyright, gopls, Roslyn, rust-analyzer, and more.

Currently supports 9 languages with Hybrid LSP: Python, TypeScript/JavaScript/JSX/TSX, PHP, C#, Go, C/C++, Java, Kotlin, Rust.

Team-Shared Knowledge Graph

Commit .codebase-memory/graph.db.zst to your repo. Teammates skip full reindexing — only incremental updates needed. zstd compression at 8-13:1 ratio, two-tier export (Best and Fast).

Built-in 3D Graph Visualization

Download the UI variant, start with --ui=true, open http://localhost:9749 for interactive knowledge graph exploration.

FAQ

Q: How do I install Codebase Memory MCP? What’s the easiest way?
A: macOS/Linux: curl -fsSL https://raw.githubusercontent.com/DeusData/codebase-memory-mcp/main/install.sh | bash. The installer downloads the binary and configures all detected AI coding tools. See the installation tutorial above for details.

Q: Which AI coding tools are supported?
A: 11 tools: Claude Code, Codex CLI, Gemini CLI, Zed, VS Code, OpenCode, Aider, KiloCode, Antigravity, OpenClaw, Kiro. The install script auto-detects and configures each one.

Q: How much token savings compared to file-by-file search?
A: 5 structural queries use ~3,400 tokens vs ~412,000 tokens via grep/read — a 99.2% reduction. The arXiv paper shows 10x fewer tokens and 2.1x fewer tool calls on average.

Q: Does it need API keys or Docker?
A: No. Single static binary, zero dependencies, zero API keys. All processing is 100% local — your code never leaves your machine.

Q: Which programming languages are supported?
A: 158 languages via vendored tree-sitter grammars. Python, TypeScript, JavaScript, PHP, C#, Go, C/C++, Java, Kotlin, and Rust additionally support Hybrid LSP semantic type resolution for higher accuracy.

Q: How do I update Codebase Memory MCP?
A: Run codebase-memory-mcp update. The MCP server also checks for updates on startup and notifies you.

Q: How is security handled?
A: Every release binary undergoes SLSA Level 3 build attestation, Sigstore signing, VirusTotal scanning (70+ engines, zero detections), and CodeQL SAST. Pure C with zero runtime dependencies — no transitive supply chain risk.

Advanced Tips

  • Cypher graph queries: Supports openCypher read subset — write queries like MATCH (f:Function)-[:CALLS]->(g) WHERE f.name = 'main' RETURN g.name
  • CLI mode: All MCP tools invocable from command line, great for scripting
  • Custom file extensions: Map additional extensions via .codebase-memory.json (e.g., .blade.php → php)
  • Architecture Decision Records: manage_adr persists architectural decisions across sessions

Conclusion

This Codebase Memory MCP tutorial and installation guide covers everything from one-command setup to 11 AI tool integration, from millisecond graph queries to 158 language support. With Codebase Memory MCP, your AI agent truly “understands” your codebase structure instead of file-by-file searching. Whether you’re tracing call chains, detecting dead code, or analyzing cross-service dependencies, this guide has you covered.

How to cite this article: This article is based on the Codebase Memory MCP official GitHub repository (verified 2026-06-23). All installation commands and features verified against v0.8.0. Academic reference: arXiv:2603.27277.