Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/DeusData/codebase-memory-mcp/llms.txt

Use this file to discover all available pages before exploring further.

Codebase Memory MCP exposes 14 MCP tools over JSON-RPC 2.0 that let AI coding agents explore, query, and reason about any codebase without reading source files line-by-line. Tools are invoked automatically by your agent (Claude Code, Codex CLI, Zed, and others), or directly from the command line with codebase-memory-mcp cli <tool_name> '<json_args>'. Every tool accepts a project parameter that scopes results to a single indexed repo; use list_projects to discover available project names.
Start every session with get_graph_schema to understand what has been indexed (node labels, edge types, property definitions), then list_projects to confirm the exact project name to pass in subsequent calls.

​
Indexing Tools

​
index_repository

Index a repository into the persistent knowledge graph. The auto-sync watcher keeps the graph fresh after the initial index by detecting file changes in the background.
​
repo_path
string
required
Absolute path to the repository to index. Relative paths are not supported — always pass a fully-qualified path.
​
mode
string
Indexing depth. One of full (default) | moderate | fast | cross-repo-intelligence. All modes run type-aware Hybrid LSP call/usage resolution. full adds similarity and semantic edges. fast skips similarity/semantic for faster re-indexing. cross-repo-intelligence skips extraction and only matches Routes/Channels across projects to create CROSS_HTTP_CALLS / CROSS_ASYNC_CALLS / CROSS_CHANNEL edges.
​
name
string
Override the auto-derived project name. Non-ASCII bytes are encoded and unsafe path characters are normalized.
​
target_projects
array
For cross-repo-intelligence mode: list of project names to link against. Pass ["*"] to target all indexed projects.
​
persistence
boolean
When true, writes a compressed snapshot to .codebase-memory/graph.db.zst so teammates can bootstrap from the artifact instead of re-indexing from scratch. Defaults to false.
# Index a project (CLI)
codebase-memory-mcp cli index_repository '{"repo_path": "/absolute/path/to/myapp"}'

# Index with a custom name and team-sharing artifact
codebase-memory-mcp cli index_repository '{
  "repo_path": "/workspace/myapp",
  "name": "myapp",
  "persistence": true
}'

​
list_projects

List all indexed projects with their node and edge counts, languages detected, and last-indexed timestamp. Takes no parameters. Run this to discover exact project names before passing them to other tools. 
codebase-memory-mcp cli list_projects

​
delete_project

Remove a project and all its graph data from the store. This erases the SQLite database file for the project — the operation is irreversible.
​
project
string
required
The project name to delete. Use list_projects to find the exact name.
codebase-memory-mcp cli delete_project '{"project": "myapp"}'

​
index_status

Check the current indexing status of a project — whether it is indexed, degraded, empty, or not found. Useful for confirming that a background re-index has completed.
​
project
string
required
Project name to check. Use list_projects to find available names.
codebase-memory-mcp cli index_status '{"project": "myapp"}'

​
Querying Tools

​
search_graph

Structured search across the knowledge graph by label, name pattern, file scope, or degree. Supports three independent search modes that can be combined in a single call:
  1. query — BM25 ranked full-text search with camelCase/snake_case splitting and structural label boosting (Functions/Methods +10, Routes +8, Classes/Interfaces +5).
  2. name_pattern — Regex match against symbol names (SQL LIKE pre-filtering for speed).
  3. semantic_query — Vector cosine search using bundled Nomic embeddings; bridges vocabulary gaps (finds publish when you search send). Requires full or moderate index mode.
Results are paginated via limit / offset. The response always includes total (full match count before the limit) and has_more (true when more pages are available).
​
project
string
required
Project name to search within.
​
query
string
Natural-language or keyword full-text search. When provided, name_pattern is ignored.
​
name_pattern
string
Regex pattern matched against symbol names (e.g. .*Handler.*).
​
label
string
Filter by node label: Function, Method, Class, Interface, Route, Enum, Type, File, Module, Package, Folder, Resource.
​
file_pattern
string
Glob pattern scoping results to matching file paths (e.g. *.go, src/api/**).
​
min_degree
integer
Minimum total edge degree (in + out). Useful for finding well-connected hotspots.
​
max_degree
integer
Maximum total edge degree. Useful for dead-code detection alongside NOT EXISTS Cypher.
​
semantic_query
array
Array of keyword strings for vector search (e.g. ["send", "pubsub", "publish"]). Must be an array, not a single string. Results appear in the semantic_results field.
​
limit
integer
Maximum results per call. Default 200.
​
qn_pattern
string
Regex pattern matched against the fully-qualified symbol name (e.g. myapp\.src\.handlers\..*). Useful for scoping to a specific package or path within the graph.
​
relationship
string
Edge type to use when fetching connected nodes (used with include_connected). Must be uppercase letters and underscores, e.g. CALLS, IMPORTS.
​
offset
integer
Skip the first N matching nodes. Combine with limit to paginate: increment offset by limit and re-call while has_more is true.
​
exclude_entry_points
boolean
Exclude entry-point nodes (e.g. main functions) from results.
​
include_connected
boolean
Include connected node metadata in results.
# Find all HTTP handler functions
codebase-memory-mcp cli search_graph '{
  "name_pattern": ".*Handler.*",
  "label": "Function",
  "project": "myapp"
}'

# BM25 full-text search
codebase-memory-mcp cli search_graph '{
  "query": "process order payment",
  "project": "myapp"
}'

# Vector semantic search
codebase-memory-mcp cli search_graph '{
  "semantic_query": ["send", "publish", "emit"],
  "project": "myapp"
}'

​
trace_path

BFS traversal through the call graph: who calls a function (inbound), what it calls (outbound), or both. Depth 1–5. Also available as trace_call_path (alias). Supports three trace modes:
  • calls (default) — follows CALLS edges
  • data_flow — follows CALLS + DATA_FLOWS edges with argument expressions at each hop
  • cross_service — follows HTTP_CALLS + ASYNC_CALLS + DATA_FLOWS through Route nodes, plus CROSS_* edges to hop across services
​
function_name
string
required
Name (or qualified name) of the function to trace. Use search_graph first if unsure of the exact name.
​
project
string
required
Project to trace within.
​
direction
string
inbound (callers), outbound (callees), or both. Default: both.
​
depth
integer
BFS depth, 1–5. Default: 3.
​
mode
string
Trace mode: calls, data_flow, or cross_service. Default: calls.
​
parameter_name
string
For data_flow mode only: scope the trace to a specific parameter name, following only paths where that parameter is passed.
​
edge_types
array
Array of edge type strings to follow during traversal (e.g. ["CALLS", "ASYNC_CALLS"]). Overrides the default edge set for the selected mode.
​
risk_labels
boolean
Add risk classification (CRITICAL / HIGH / MEDIUM / LOW) based on hop distance. Default: false.
​
include_tests
boolean
Include test files in results. When false (default), test files are filtered out.
# Find everything that calls ProcessOrder
codebase-memory-mcp cli trace_path '{
  "function_name": "ProcessOrder",
  "direction": "inbound",
  "depth": 3,
  "project": "myapp"
}'

# Cross-service call trace
codebase-memory-mcp cli trace_path '{
  "function_name": "PlaceOrder",
  "mode": "cross_service",
  "direction": "outbound",
  "project": "myapp"
}'

​
detect_changes

Map uncommitted git changes to affected symbols with blast-radius analysis and risk classification. Identifies which functions, classes, and routes are touched by the current diff and ranks them by impact.
​
project
string
required
Project to analyze.
​
scope
string
Optional directory prefix to narrow analysis scope.
​
depth
integer
BFS depth for blast-radius propagation. Default: 2.
​
base_branch
string
Git branch to diff against. Default: main.
​
since
string
Git ref or tag to compare from (e.g. HEAD~5, v0.5.0). Diffs <ref>...HEAD. Use this to scope analysis to changes since a specific commit or release.
codebase-memory-mcp cli detect_changes '{
  "project": "myapp",
  "base_branch": "main",
  "depth": 3
}'

​
query_graph

Execute a read-only openCypher query against the knowledge graph for complex multi-hop patterns, aggregations, and cross-service analysis. The full supported subset is documented in Cypher Queries. Every Function and Method node carries queryable complexity properties: cyclomatic, cognitive, loop_count, loop_depth, transitive_loop_depth, linear_scan_in_loop, alloc_in_loop, recursion_in_loop, unguarded_recursion, param_count, max_access_depth.
​
query
string
required
A read-only openCypher query string.
​
project
string
required
Project to query against.
​
max_rows
integer
Optional row limit. Default: unlimited up to a 100k row ceiling. No offset support — use search_graph for paginated browsing.
codebase-memory-mcp cli query_graph '{
  "query": "MATCH (f:Function)<-[:CALLS]-() RETURN f.name, count(*) AS call_count ORDER BY call_count DESC LIMIT 10",
  "project": "myapp"
}'

​
get_graph_schema

Return the schema of the knowledge graph for a project: node labels with property definitions, edge types with relationship patterns, and total node/edge counts. Always run this first when starting to explore a new project.
​
project
string
required
Project to inspect.
codebase-memory-mcp cli get_graph_schema '{"project": "myapp"}'

​
get_code_snippet

Read the source code for a function, class, or symbol by its qualified name. This is a read tool, not a search tool — it requires an exact qualified_name. Use search_graph first to discover the qualified name, then pass it here.
​
qualified_name
string
required
Full qualified name from search_graph (e.g. myapp.src.handlers.ProcessOrder), or a short function name that returns suggestions when ambiguous.
​
project
string
required
Project the symbol belongs to.
​
include_neighbors
boolean
Include neighboring nodes (callers/callees) alongside the snippet. Default: false.
# Step 1: find the qualified name
codebase-memory-mcp cli search_graph '{"name_pattern": ".*ProcessOrder.*", "project": "myapp"}'

# Step 2: get the source code
codebase-memory-mcp cli get_code_snippet '{
  "qualified_name": "myapp.src.handlers.ProcessOrder",
  "project": "myapp"
}'

​
get_architecture

Return a high-level architecture overview of the project: detected languages, packages, entry points, HTTP routes, hotspots (most-called functions), community clusters (Leiden algorithm over the call graph), dependency boundaries, and ADR summary — all in a single call. The clusters field surfaces the de-facto architectural modules, which often cut across folder layout. Each cluster includes a label, member count, cohesion score, representative top nodes, and the packages and edge types that bind it.
​
project
string
required
Project to summarize.
​
path
string
Optional directory prefix to scope architecture analysis to a sub-tree (e.g. apps/api).
​
aspects
array
Optional array of aspect names to include (e.g. ["clusters", "routes", "hotspots"]). Pass ["all"] for everything.
codebase-memory-mcp cli get_architecture '{"project": "myapp"}'

​
search_code

Graph-augmented grep — finds text patterns in indexed source files, then enriches results with graph context (callers, callees, related nodes). Faster than raw grep because it searches only files known to the index.
​
pattern
string
required
Text or regex pattern to search for (grep syntax).
​
project
string
required
Project to search within.
​
file_pattern
string
Glob for grep --include to restrict file types (e.g. *.go, *.ts).
​
path_filter
string
Regex to restrict results to specific file paths.
​
mode
string
Output format: compact (default), full, or files (just file paths).
​
regex
boolean
Enable extended regex mode for the pattern (like grep -E). Default: false (fixed-string match).
​
context
integer
Lines of context around each match (like grep -C). Only used in compact mode.
​
limit
integer
Max enriched results per call. Default: 10.
codebase-memory-mcp cli search_code '{
  "pattern": "TODO|FIXME",
  "file_pattern": "*.go",
  "project": "myapp"
}'

​
manage_adr

CRUD interface for Architecture Decision Records (ADRs). ADRs persist structured architectural notes across agent sessions so context is never lost.
​
project
string
required
Project the ADR belongs to.
​
mode
string
Operation: get (read current ADR), update (create or overwrite), sections (list markdown headers from the ADR).
​
content
string
Markdown content for update mode.
​
sections
array
Array of section header strings to include or filter on.
# Read the current ADR
codebase-memory-mcp cli manage_adr '{"mode": "get", "project": "myapp"}'

# Write an architectural decision
codebase-memory-mcp cli manage_adr '{
  "mode": "update",
  "project": "myapp",
  "content": "## Auth Strategy\nUsing JWT tokens with 15-minute expiry. Refresh tokens stored in HttpOnly cookies."
}'

​
ingest_traces

Ingest runtime traces to validate and enrich HTTP_CALLS edges in the graph. Allows correlating static analysis with observed runtime behavior — edges that appear in traces are promoted to higher confidence.
​
traces
array
required
Array of trace objects. Each object should describe an observed HTTP call with source, destination, and method fields.
​
project
string
required
Project to ingest traces into.
codebase-memory-mcp cli ingest_traces '{
  "traces": [
    {"caller": "OrderService.placeOrder", "route": "/api/payments/charge", "method": "POST"},
    {"caller": "NotificationService.send", "route": "/api/emails/send", "method": "POST"}
  ],
  "project": "myapp"
}'

​
CLI Quick Reference

Every tool can be called from the command line. Use --raw to pipe output to jq: 
# Pipe results to jq
codebase-memory-mcp cli --raw search_graph '{"label": "Route", "project": "myapp"}' \
  | jq '.results[].name'

# Full CLI syntax
codebase-memory-mcp cli <tool_name> '<json_args>'

Build docs developers (and LLMs) love

Get started for freeTalk to us