How CLI Mode Differs from MCP Server Mode in Codebase Memory MCP

CLI mode executes single commands and exits without starting a daemon, while MCP server mode launches a persistent coordination daemon that handles JSON-RPC requests and optional UI services.

The codebase-memory-mcp repository provides a memory-backed code graph system that operates in two distinct modes depending on your workflow needs. Understanding how CLI mode differs from MCP server mode is essential for choosing between one-shot command execution and persistent agent coordination. According to the DeusData/codebase-memory-mcp source code, these modes diverge in process lifecycle, state persistence, and resource locking mechanisms.

Execution Model: Ephemeral Commands vs. Persistent Daemon

CLI mode processes a single command and terminates immediately. When you invoke codebase-memory-mcp cli <tool>, the entry point in src/main.c parses arguments, dispatches to the appropriate handler, and exits without initializing the daemon subsystem. Even index_repository, which internally spawns a short-lived supervised worker, completes without leaving a background process.

MCP server mode starts a persistent coordination daemon implemented in src/daemon.c. This process stays alive indefinitely, managing multiple client sessions through JSON-RPC communication over stdio. The daemon maintains long-lived state, handles background file watchers, and enforces a crash-safe admission lease for all connected operations.

State Persistence and Storage

State management represents a fundamental architectural difference between the two modes.

CLI mode maintains only transient state for the duration of command execution. Graph mutations write directly to the SQLite store using OS-backed per-project locks, ensuring consistency even when commands overlap with active server sessions. Once the process exits, no runtime state remains in memory.

MCP server mode establishes persistent state in ${CBM_CACHE_DIR}, including lifecycle logs (cbm-daemon.log) and cached graph indexes. According to the README documentation (lines 70-80), the daemon can auto-update indexes through background watchers, maintaining optimized search data between client invocations.

UI and Visualization Capabilities

The graph visualization UI is available exclusively in server mode. When built with --ui (as configured in scripts/build.sh), the daemon launches an HTTP server on localhost:9749 that serves the visualization interface. Multiple concurrent agents can share this single UI instance owned by the daemon process.

CLI mode never initializes the UI. The visualization binary is a separate variant that remains inaccessible from CLI commands, making CLI mode unsuitable for interactive graph exploration.

Progress Reporting and Output Streams

Output handling differs significantly to accommodate each mode's communication protocol:

• CLI mode writes progress messages to stderr only when detecting an interactive terminal or when passed the --progress flag. Stdout contains the pure command result (JSON or text), safe for piping to other tools.
• MCP server mode reserves the daemon's stdout exclusively for JSON-RPC messages. While client commands still emit progress on stderr, the daemon's primary output channel remains dedicated to protocol communication.

Resource Coordination and Locking

Both modes implement concurrency controls, but through different mechanisms.

CLI mode uses per-project file locks to serialize access to the SQLite database. These locks prevent write conflicts when CLI commands execute while the daemon maintains open connections, as noted in the README (lines 122-127).

The daemon enforces an exact-build admission barrier through centralized coordination in src/daemon.c. This architecture safely allows multiple JSON-RPC clients—such as Claude Code or Codex—to simultaneously access the graph without manual lock management.

Practical Usage Examples

Execute a one-shot search without daemon overhead:

codebase-memory-mcp cli search_graph \
  --project my-project \
  --name-pattern '.*Handler.*' \
  --label Function \
  --json

Launch the daemon with UI capabilities for persistent agent integration:

codebase-memory-mcp --ui=true --port=9749

Run a headless daemon for JSON-RPC-only operation:

codebase-memory-mcp

Summary

• CLI mode (src/main.c) executes single commands and exits immediately, using direct SQLite access with file-based locks for isolation.
• MCP server mode (src/daemon.c) maintains a persistent daemon supporting multiple JSON-RPC clients, background indexing, and optional UI services on localhost:9749.
• State persistence differs: CLI uses transient connections while the server maintains long-lived caches and logs in ${CBM_CACHE_DIR}.
• UI availability is exclusive to server mode; CLI never initializes the HTTP visualization server.
• Both modes coordinate through per-project locks, but the daemon provides centralized admission control for concurrent access.

Frequently Asked Questions

Can I run CLI commands while the MCP server is active?

Yes. The system implements OS-backed per-project locks that serialize access to the SQLite store. When executing codebase-memory-mcp cli commands while the daemon runs, the CLI acquires transient locks that prevent write conflicts without requiring server shutdown.

Does CLI mode support the graph visualization UI?

No. The UI is only available in MCP server mode when built with the --ui flag. According to the source code organization, the visualization interface runs as an HTTP server owned by the daemon process on localhost:9749. CLI commands execute independently and never spawn the UI service.

Why would I choose MCP server mode over CLI mode?

Choose MCP server mode when you need persistent agent coordination, such as when using Claude Code or other MCP clients that communicate via JSON-RPC. The daemon provides background file watching, automatic index updates, and shared state across multiple tool invocations. CLI mode suits one-off queries, CI pipelines, or scripts where daemon overhead is unnecessary.

How does the admission lease work in server mode?

The daemon maintains a crash-safe admission lease that acts as an exact-build barrier for all operations. When clients connect via JSON-RPC, they register sessions that share this lease, ensuring that only compatible graph versions are accessed and that partial writes from crashed processes are detected before new operations begin.

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