How to Use Codebase-Memory-MCP CLI Commands: A Complete Guide

Codebase-Memory-MCP exposes 14 graph-based code analysis tools through a JSON-RPC-style CLI interface activated by the cli sub-command, enabling repository indexing and semantic code search without running a persistent server.

The DeusData/codebase-memory-mcp repository ships as a single static binary that dual-functions as both an MCP server and a standalone command-line utility. When you invoke the binary with the cli sub-command, it switches into a JSON-RPC interface that accepts tool-specific JSON payloads, validates them against schemas, and executes operations against an in-memory SQLite graph stored in ~/.cache/codebase-memory-mcp.

CLI Architecture and Entry Points

The Python-based entry point for the CLI mode lives in pkg/pypi/src/codebase_memory_mcp/_cli.py. The main() function in this module handles platform detection, binary downloads, and argument forwarding.

When you execute a command, the helper function performs the following actions:

1. Parses the current version and determines the platform-specific native binary location.
2. Downloads the native binary if it does not exist locally.
3. Executes the binary directly on Unix systems via os.execv, or spawns a subprocess on Windows using subprocess.run.
4. Forwards all arguments verbatim using args = [str(bin_path)] + sys.argv[1:], ensuring that any flags or JSON payloads you provide pass unchanged to the native binary.

This architecture ensures the CLI operates with zero external dependencies once the initial binary is cached.

Command Syntax and Execution Flow

The native binary implements a strict command dispatcher that expects the following format:

codebase-memory-mcp cli <tool> <json-payload>

The <tool> parameter specifies one of 14 available MCP tools (such as index_repository, search_graph, or trace_path), while <json-payload> supplies the tool-specific parameters as a JSON object.

The execution flow follows this sequence:

• Deserialization of the JSON payload into the tool's request schema.
• Validation against the tool's parameter schema.
• Execution against the in-memory SQLite graph or the persisted database under ~/.cache/codebase-memory-mcp.
• Output of the JSON-RPC result to stdout, while diagnostic logs route to stderr according to the logging policy defined in the repository.

Essential Codebase-Memory-MCP CLI Commands

Index a Repository

Create a graph representation of your codebase and enable file watching for automatic updates:

codebase-memory-mcp cli index_repository '{"repo_path": "/path/to/my/project"}'

This command parses the repository structure, extracts symbols and relationships, and populates the graph database.

Search the Code Graph

Find functions matching a specific regex pattern:

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

This returns all Function nodes whose names match the provided regular expression, including metadata about file locations and relationships.

Trace Call Relationships

Analyze inbound and outbound call relationships for a specific function:

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

The direction parameter accepts in, out, or both to filter caller and callee relationships.

Execute Cypher Queries

Run arbitrary read-only openCypher queries against the graph:

codebase-memory-mcp cli query_graph '{"query": "MATCH (f:Function) RETURN f.name LIMIT 5"}'

This provides direct access to the underlying graph database for complex analytical queries.

List Indexed Projects

View all currently indexed projects and their statistics:

codebase-memory-mcp cli list_projects

The output displays each project's name along with node and edge counts.

Process Raw JSON Output

For integration with Unix pipelines, use the --raw flag to omit the JSON-RPC envelope:

codebase-memory-mcp cli --raw search_graph '{"label": "Function"}' | jq '.results[].name'

This extracts just the result array, making it compatible with tools like jq, grep, or awk.

Configuration and Automation

Enable automatic indexing when connecting new projects:

codebase-memory-mcp config set auto_index true

Once configured, the system automatically indexes any newly connected repository without requiring explicit index_repository calls. All configuration and cached graph data persists in ~/.cache/codebase-memory-mcp, ensuring fast subsequent startups even for large codebases.

Summary

• Codebase-Memory-MCP ships as a single static binary that doubles as an MCP server and CLI tool.
• The entry point at pkg/pypi/src/codebase_memory_mcp/_cli.py forwards arguments to a native binary using os.execv (Unix) or subprocess.run (Windows).
• Use the cli sub-command followed by a tool name and JSON payload to execute graph operations.
• Standard output contains JSON-RPC responses suitable for parsing, while stderr receives diagnostic logs.
• The --raw flag strips the JSON-RPC envelope for seamless shell pipeline integration.
• Configuration commands like config set auto_index true enable automation for continuous indexing workflows.

Frequently Asked Questions

What is the difference between the MCP server mode and CLI mode?

The same binary operates in both modes. When invoked without the cli sub-command, it starts as a persistent MCP server communicating via standard input/output streams. When invoked with codebase-memory-mcp cli <tool> <payload>, it executes a single tool operation and exits immediately, making it suitable for shell scripts and CI/CD pipelines that do not require a long-running process.

Where does Codebase-Memory-MCP store the graph database?

The system stores the SQLite graph database and related cache files in ~/.cache/codebase-memory-mcp. This location persists across CLI invocations, allowing you to index a repository once and query it repeatedly without re-indexing. The database operates in-memory during active sessions but persists to this cache directory for fast subsequent loading.

How does the CLI handle binary dependencies on different platforms?

The main() function in pkg/pypi/src/codebase_memory_mcp/_cli.py automatically detects your platform and downloads the appropriate native binary on first use. On Unix systems, it uses os.execv to replace the Python process with the native binary, while on Windows it uses subprocess.run to spawn the binary as a child process. This ensures zero manual dependency management regardless of operating system.

Can I pipe CLI output to other Unix tools?

Yes. The CLI writes JSON-RPC responses to stdout and logs to stderr, following standard Unix conventions. Use the --raw flag to remove the JSON-RPC envelope and output only the result payload, which simplifies parsing with tools like jq. For example: codebase-memory-mcp cli --raw search_graph '{"label": "Function"}' | jq '.[].name'.

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