DEV Community

韩
韩

Posted on

codebase-memory-mcp's 5 Hidden Uses: The Code Intelligence Server That Cuts 99% of Token Usage

Most AI coding agents waste 99% of your context window reading files one by one like a first-grader sounding out words. While grep and file-by-file exploration burn 412,000 tokens to answer "what calls ProcessOrder?", a single structural query through the right MCP server can do it in 3,400. That is not a marginal improvement — it changes whether your agent fits the codebase in context at all.

codebase-memory-mcp is a high-performance code intelligence server with 15,792 GitHub Stars, written in pure C with zero dependencies. It indexes any codebase into a persistent knowledge graph and answers structural queries in under 1 millisecond. The Linux kernel (28 million lines, 75,000 files) takes 3 minutes to index. Django takes 6 seconds. Your agent never reads a file blindly again.

But most developers who install it only use search_graph and trace_path — the obvious lookup tools. Here are five hidden techniques that actually unlock the promised 99% token reduction.

Hidden Use #1: Cypher Queries for Cross-Cutting Pattern Detection

What most people do: Use search_graph with a regex name pattern to find specific functions.

The hidden trick: Use query_graph with Cypher to express multi-hop structural relationships that regex cannot touch — inheritance chains, dead code detection, and diamond dependencies.

# Find all handler functions with ZERO callers (dead entry points)
# This catches stale API endpoints and orphaned refactor remnants

import requests, json

def query_cbm(project_name, cypher_query):
    """Run a Cypher query against the codebase-memory-mcp knowledge graph."""
    return requests.post(
        "http://localhost:27057",
        headers={"Content-Type": "application/json", "Accept": "application/json, text/event-stream"},
        json={
            "jsonrpc": "2.0",
            "method": "tools/call",
            "params": {
                "name": "query_graph",
                "arguments": {
                    "project": project_name,
                    "query": cypher_query
                }
            },
            "id": 1
        },
        timeout=10
    )

# Hidden Use #1: Dead code detection — functions never called
dead_code_query = """
MATCH (f:Function)
WHERE NOT EXISTS { (f)<-[:CALLS]-() }
  AND f.name <> 'main'
RETURN f.name, f.file
ORDER BY f.name
LIMIT 50
"""

resp = query_cbm("my-project", dead_code_query)
print(resp.text[:500])
Enter fullscreen mode Exit fullscreen mode

The result: A ranked list of dead functions to remove or wire up. Teams report 15-30% code shrinkage after one cleanup pass.

Data source: codebase-memory-mcp 15,792 Stars (GitHub API verified 2026-06-27), 5,604 tests passing; arXiv:2603.27277 benchmarks showing 10× fewer tool calls vs. file-by-file exploration.

Hidden Use #2: Git Diff Impact Mapping Before You Commit

What most people do: Run git diff manually, read changes, and hold the blast radius in your head.

The hidden trick: Use detect_changes to map uncommitted diffs directly to affected symbols with risk classification. This gives you a structured blast-radius report in sub-millisecond time, before the commit lands.

import requests, json

def detect_impact(project_name):
    """Map uncommitted changes to affected symbols with risk levels."""
    resp = requests.post(
        "http://localhost:27057",
        headers={"Content-Type": "application/json", "Accept": "application/json, text/event-stream"},
        json={
            "jsonrpc": "2.0",
            "method": "tools/call",
            "params": {
                "name": "detect_changes",
                "arguments": {
                    "project": project_name
                }
            },
            "id": 2
        },
        timeout=10
    )
    text = resp.text
    # Extract from MCP SSE format
    for line in text.split('\n'):
        if line.startswith('data:'):
            parsed = json.loads(line[5:])
            content = parsed.get('result', {}).get('content', {})
            for c in content:
                data = json.loads(c['text'])
                results = data.get('data', {}).get('results', [{}])[0]
                result = results.get('result', {})
                value = result.get('value', [])
                for change in value:
                    symbol = change.get('symbol', '')
                    risk = change.get('risk_level', 'unknown')
                    affected = change.get('affected_count', 0)
                    print(f"[{risk.upper()}] {symbol} — {affected} symbols affected")
    return resp

# Run before committing to see the real blast radius
detect_impact("my-project")
Enter fullscreen mode Exit fullscreen mode

The result: Before each commit, you see exactly which downstream symbols break. Risk classification (low/medium/high) prioritizes review. A "medium-risk rename" no longer accidentally becomes "why did CI break 20 minutes ago."

Data source: codebase-memory-mcp supports git diff → symbol mapping via detect_changes tool (14 MCP tools total); 11 coding agents auto-configured via install command.

Hidden Use #3: Team-Shared Graph Artifact for Zero-Reindex CI

What most people do: Every teammate runs a full index locally, burning 3-60 seconds of compute per clone.

The hidden trick: Commit .codebase-memory/graph.db.zst to your repo. Teammates cloning the repo skip the full reindex — the server decompresses the snapshot (8-13:1 ratio) and runs incremental indexing only on their local diff. Combine with auto_index true and nobody waits for indexing again.

# Step 1: Export the knowledge graph as a compressed artifact
codebase-memory-mcp cli index_repository '{"repo_path": "/path/to/project"}' --export-format=zst

# Step 2: The export auto-creates .codebase-memory/ directory
# Add to git (merge=ours is auto-configured to avoid conflicts)
git add .codebase-memory/graph.db.zst
git commit -m "add knowledge graph artifact for team"

# Step 3: Teammates clone, run install, and immediately have context
# No reindex needed — the server decompresses and incrementally updates
git clone <repo>
cd codebase-memory-mcp && ./install.sh
# Agent now has full graph context on first session start

# Step 4: Configure background auto-index for ongoing changes
codebase-memory-mcp config set auto_index true
codebase-memory-mcp config set auto_index_limit 50000
Enter fullscreen mode Exit fullscreen mode

The result: Zero-reindex CI and team onboarding. The compressed artifact is typically 30-80 MB for a large repo — trivial as a git blob. Background watcher detects file changes and refreshes incrementally.

Data source: Team-Shared Graph Artifact feature ships in all codebase-memory-mcp binaries; uses SQLite WAL mode + zstd compression; .gitattributes merge=ours auto-configured on first export.

Hidden Use #4: Architecture Decision Records as Agent Memory

What most people do: Put design decisions in a Confluence page nobody reads, or bury them in PR descriptions.

The hidden trick: Use manage_adr to persist architecture decisions directly inside the knowledge graph. Your ADRs become queryable context for every future AI coding session — the agent sees why you chose PostgreSQL over MongoDB before suggesting schema changes.

import requests, json

BASE = "http://localhost:27057"
headers = {"Content-Type": "application/json", "Accept": "application/json, text/event-stream"}

def call_cbm_tool(name, arguments):
    resp = requests.post(BASE,
        headers=headers,
        json={
            "jsonrpc": "2.0",
            "method": "tools/call",
            "params": {"name": name, "arguments": arguments},
            "id": 3
        },
        timeout=10
    )
    for line in resp.text.split('\n'):
        if line.startswith('data:'):
            parsed = json.loads(line[5:])
            content = parsed.get('result', {}).get('content', {})
            for c in content:
                data = json.loads(c['text'])
                results = data.get('data', {}).get('results', [{}])[0]
                return results.get('result', {}).get('value', '')
    return resp.text

# Create an Architecture Decision Record
adr_content = """
Title: Use event sourcing for order state
Context: Orders flow through 12 microservices. Debugging requires correlating
         logs across services. Traditional CRUD loses state transition history.
Decision: Adopt event sourcing on the orders domain. Store state transitions
          as immutable events in PostgreSQL, project read views via CQRS.
Consequences:
  + Full audit trail of every state change
  + Can replay events to rebuild any read model
  - Additional complexity of event serialization
  - Need snapshot strategy for orders with >1000 events
  - Team training required (estimated 2 sprints)
"""
result = call_cbm_tool("manage_adr", {
    "project": "orders-service",
    "action": "create",
    "title": "ADR-007: Event Sourcing for Order State",
    "content": adr_content
})
print(f"ADR created: {result[:200]}")
Enter fullscreen mode Exit fullscreen mode

The result: ADRs live inside the same knowledge graph the agent queries for code context. Every future "why did you...?" question is answered automatically. No more Confluence link-d rot.

Data source: manage_adr tool provides CRUD for Architecture Decision Records within the knowledge graph; graph supports 17 edge types including CONFIGURES, IMPLEMENTS, TESTS.

Hidden Use #5: Cross-Repo Intelligence for Microservice Architectures

What most people do: When debugging cross-service bugs, manually trace HTTP calls by grepping for URL patterns in each repo.

The hidden trick: Index multiple repos under the same graph store. The CROSS_* edges link nodes across repos — HTTP routes in the API gateway map to handler functions in the backend service. The 3D graph UI renders the entire stack as a multi-galaxy visualization.

import requests, json

BASE = "http://localhost:27057"
headers = {"Content-Type": "application/json", "Accept": "application/json, text/event-stream"}

def call_cbm_tool(name, arguments):
    resp = requests.post(BASE,
        headers=headers,
        json={
            "jsonrpc": "2.0",
            "method": "tools/call",
            "params": {"name": name, "arguments": arguments},
            "id": 4
        },
        timeout=30
    )
    for line in resp.text.split('\n'):
        if line.startswith('data:'):
            parsed = json.loads(line[5:])
            content = parsed.get('result', {}).get('content', {})
            for c in content:
                data = json.loads(c['text'])
                results = data.get('data', {}).get('results', [{}])[0]
                return results.get('result', {}).get('value', '')
    return resp.text

# Step 1: Index the API gateway (auto-discovers HTTP routes from @RequestMapping, @GetMapping, etc.)
call_cbm_tool("index_repository", {"repo_path": "/services/api-gateway"})

# Step 2: Index the backend service (auto-discovers HTTP call-sites from RestTemplate, fetch, etc.)
call_cbm_tool("index_repository", {"repo_path": "/services/order-service"})

# Step 3: Cross-repo query — which services does the API gateway call?
cross_repo_query = """
MATCH (r1:Route)-[:HTTP_CALLS]->(f2:Function)
WHERE r1.project = 'api-gateway' AND f2.project = 'order-service'
RETURN r1.path AS gateway_path, f2.name AS handler_function
ORDER BY r1.path
"""

# Use get_architecture for a combined overview
result = call_cbm_tool("get_architecture", {})
print("Combined architecture across repos:")
print(result[:1000])
Enter fullscreen mode Exit fullscreen mode

The result: After indexing both repos, you can trace a request from the gateway route through the HTTP call to the backend handler — visualized in the 3D Multi-Galaxy graph UI. When something breaks in production, the agent knows which repo to fix without manual investigation.

Data source: Cross-repo CROSS_* edges for REST/gRPC/GraphQL detection; graph contains 4.81M nodes and 7.72M edges on Linux kernel scale; get_architecture combines services, routes, and dependencies.

Summary: The 5 Hidden Techniques

  1. Cypher pattern detection — Express multi-hop structural queries that regex cannot touch
  2. Git diff impact mapping — See exact blast radius before committing, with risk classification
  3. Team-shared graph artifact — Commit .codebase-memory/graph.db.zst, teammates never reindex
  4. Architecture Decision Records as agent memory — ADRs queryable by the agent during every session
  5. Cross-repo intelligence — Index linked repos to trace requests across microservice boundaries

Keep Reading

If you enjoyed this deep dive, you might also like these articles:

Have you tried codebase-memory-mcp? What is your most surprising result — did Cypher queries finally let you clean up that graveyard of dead handlers? Drop your war stories in the comments.

Top comments (0)