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

> Understand how CLI mode differs from MCP server mode in Codebase Memory MCP. CLI runs single commands, while MCP server mode provides a persistent daemon for JSON-RPC and UI services.

- Repository: [Martin Vogel/codebase-memory-mcp](https://github.com/DeusData/codebase-memory-mcp)
- Tags: deep-dive
- Published: 2026-07-30

---

**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`](https://github.com/DeusData/codebase-memory-mcp/blob/main/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`](https://github.com/DeusData/codebase-memory-mcp/blob/main/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`](https://github.com/DeusData/codebase-memory-mcp/blob/main/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`](https://github.com/DeusData/codebase-memory-mcp/blob/main/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:

```bash
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:

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

```

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

```bash
codebase-memory-mcp

```

## Summary

- **CLI mode** ([`src/main.c`](https://github.com/DeusData/codebase-memory-mcp/blob/main/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`](https://github.com/DeusData/codebase-memory-mcp/blob/main/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.