What Queries Can Be Performed on the codebase-memory-mcp Knowledge Graph

The codebase-memory-mcp project exposes eleven distinct MCP tools that enable semantic vector search, structural graph filtering, OpenCypher pattern matching, call-path tracing, change impact analysis, and source code retrieval against its persistent knowledge graph.

The DeusData/codebase-memory-mcp repository builds a persistent knowledge graph representing every symbol, file, package, and runtime artifact in a codebase. Developers interact with this graph through a suite of built-in MCP (Model Context Protocol) tools, each mapping to a specific query pattern implemented in the C core. These queries range from vector-similarity lookups to complex graph traversals, all executable via JSON-RPC or the CLI.

Semantic Vector Search

Natural Language Code Discovery

The semantic_query tool performs vector-based similarity search across the entire graph using bundled Nomic embeddings—requiring no external API calls. This allows you to find functionally similar code snippets using natural language or partial code examples, matching on semantic meaning rather than literal text.

codebase-memory-mcp cli semantic_query '{"project":"my-project","query":"def process_order(order):"}'

Structural Node Discovery

Labeled Node Filtering

search_graph executes regex, label, and degree-filtered searches for specific node types such as functions, classes, or HTTP routes. It supports pagination via limit and offset parameters for large result sets.

codebase-memory-mcp cli search_graph '{"project":"my-project","label":"Function","name_pattern":"Handler"}'

Full-Text Code Search

search_code provides grep-style text search limited to indexed files, backed by SQLite FTS5 with a camel-case aware tokenizer. This is ideal for locating literal strings like TODO comments or specific variable names.

codebase-memory-mcp cli search_code '{"project":"my-project","text":"TODO"}'

Graph Traversal and Path Analysis

Call Chain Tracing

trace_path performs a breadth-first traversal of CALLS edges to reveal inbound, outbound, or bidirectional dependencies for any function. You can specify traversal depth from 1 to 5 levels to map immediate callers or deep dependency chains.

codebase-memory-mcp cli trace_path '{"project":"my-project","function_name":"process_order","direction":"both"}'

OpenCypher Pattern Matching

query_graph exposes a read-only subset of OpenCypher for arbitrary graph exploration. You can write MATCH … WHERE … RETURN queries to traverse relationships, aggregate metrics, and filter complex patterns.

codebase-memory-mcp cli query_graph '{"project":"my-project","query":"MATCH (f:Function)-[:CALLS]->(g) RETURN g.name, count(*) AS cnt ORDER BY cnt DESC LIMIT 5"}'

Impact Analysis and Change Detection

Blast Radius Calculation

detect_changes maps a Git diff onto graph symbols to classify the blast radius of modifications as high-, medium-, or low-risk. This helps reviewers understand which downstream components are affected by a commit before merging.

codebase-memory-mcp cli detect_changes '{"project":"my-project","git_ref":"HEAD"}'

Schema Introspection and Metadata

Graph Schema Discovery

get_graph_schema returns node and edge counts, relationship patterns, and property definitions for each label. Use this to understand the graph structure before writing complex queries.

codebase-memory-mcp cli get_graph_schema '{"project":"my-project"}'

Architecture Overview

get_architecture generates a high-level summary including languages, packages, entry points, HTTP routes, hotspots, clusters, and Architecture Decision Records (ADRs).

codebase-memory-mcp cli get_architecture '{"project":"my-project"}'

Content Retrieval and Documentation

Source Code Extraction

get_code_snippet retrieves the complete source code of a function or method given its fully-qualified name (e.g., my_pkg.utils.process_order).

codebase-memory-mcp cli get_code_snippet '{"project":"my-project","qualified_name":"my_pkg.utils.process_order"}'

ADR Management

manage_adr provides CRUD operations for Architecture Decision Records stored within the graph itself, allowing versioned documentation to live alongside the code structure.

codebase-memory-mcp cli manage_adr '{"project":"my-project","action":"create","title":"Switch to SQLite","content":"We use SQLite for the graph store …"}'

Runtime Integration

Trace Ingestion

ingest_traces imports execution traces from APM tools or log files to validate or enrich HTTP_CALLS edges, bridging the gap between static analysis and runtime behavior.

codebase-memory-mcp cli ingest_traces '{"project":"my-project","trace_file":"trace.ndjson"}'

Implementation Architecture

According to the source code in internal/cbm/cbm.c and internal/cbm/cbm.h, the C core provides fast in-memory graph traversal with sub-millisecond latency for typical queries. The OpenCypher engine in the cypher/ directory handles parsing and execution for the query_graph tool, while optional persistent storage uses SQLite. All tools register with the MCP JSON-RPC server defined in the core files, making them available to both automated systems and the interactive 3-D visualization UI in graph-ui/index.html.

Summary

• Eleven query tools cover semantic search, structural filtering, graph traversal, impact analysis, and documentation management.
• Vector search uses local Nomic embeddings without external API dependencies.
• Traversal queries support up to 5 levels of breadth-first call-chain analysis.
• OpenCypher subset enables custom pattern matching via query_graph.
• Performance targets sub-millisecond response times for in-memory traversals, backed by the C core implementation in cbm.c.

Frequently Asked Questions

What query languages are supported by the knowledge graph?

The graph supports a read-only subset of OpenCypher through the query_graph tool, allowing MATCH, WHERE, and RETURN clauses. Additionally, specialized tools like search_graph and trace_path provide higher-level abstractions for common patterns without requiring Cypher syntax.

Does semantic search require an internet connection or API keys?

No. According to the README and source implementation, semantic_query uses bundled Nomic embeddings that run locally. This design ensures that semantic similarity search works offline with no external API dependencies or token costs.

How fast are graph traversals in codebase-memory-mcp?

The C core implementation in internal/cbm/cbm.c provides in-memory graph traversal with typical query latency under 1 millisecond. Persistent storage uses SQLite for durability, but hot paths remain in memory for performance.

Can I query the graph without running the MCP server?

Yes. All MCP tools are exposed through the CLI interface using codebase-memory-mcp cli <tool_name>. The CLI invokes the same underlying C functions defined in cbm.c, making it suitable for scripts and CI/CD pipelines without requiring a running JSON-RPC server.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}