# What Is the Expected Output When Running DeusData codebase-memory-mcp?

> Understand the expected output of DeusData codebase-memory-mcp. Learn about JSON results, diagnostic logs, and three distinct output modes for installation, indexing, and querying.

- Repository: [Martin Vogel/codebase-memory-mcp](https://github.com/DeusData/codebase-memory-mcp)
- Tags: getting-started
- Published: 2026-07-25

---

**When you run the DeusData codebase-memory-mcp binary, it produces machine-readable JSON results on stdout and diagnostic logs on stderr, with three distinct output modes depending on whether you're installing, indexing a repository, or querying the knowledge graph.**

DeusData codebase-memory-mcp is a static, single-binary code-intelligence engine that operates entirely locally. When invoked, the binary routes your command to one of three operational modes, each producing specific output formats designed for both human readability and automated parsing. Understanding these output patterns is essential for integrating the tool into CI/CD workflows and coding agent environments.

## Three Primary Output Modes

The DeusData codebase-memory-mcp binary behavior changes based on the command context, producing different output signatures for installation, indexing, and query operations.

### Installation and Setup Output

When using the [`install.sh`](https://github.com/DeusData/codebase-memory-mcp/blob/main/install.sh) helper script or running the install command directly, the binary downloads pre-built artifacts and configures the local environment. The output consists of progress banners confirming download completion, extraction status, and final installation paths.

Typical installation output includes:

- Download progress indicators sent to stderr
- Confirmation messages like "Installed codebase-memory-mcp to ~/.local/bin"
- Reminders to restart your coding agent

This process is handled by the [`install.sh`](https://github.com/DeusData/codebase-memory-mcp/blob/main/install.sh) script located in the repository root, which orchestrates the binary placement and environment setup.

### Repository Indexing Output

Running `codebase-memory-mcp index_repository --repo-path <path>` triggers a RAM-first pipeline that constructs a knowledge graph of your entire codebase. According to the implementation, this process keeps all indexing operations in memory before persisting to a single SQLite dump via [`internal/cbm/zstd_store.c`](https://github.com/DeusData/codebase-memory-mcp/blob/main/internal/cbm/zstd_store.c), ensuring the final JSON output reflects the complete graph state.

The command prints a concise JSON object to stdout upon completion:

```json
{
  "status": "indexed",
  "project": "my-repo",
  "nodes": 123456,
  "edges": 987654
}

```

Progress messages such as "Indexing 75K files…" and "Finished in 3 min" are written to stderr, keeping stdout clean for programmatic parsing. The persisted graph is compressed into `.codebase-memory/graph.db.zst` format.

### Query Tool Output

The binary exposes fifteen MCP tools (including `search_graph`, `trace_path`, `get_architecture`, and `query_graph`) through the CLI interface. When running `codebase-memory-mcp cli <tool> …`, the binary writes **only the query result to stdout** while directing all diagnostics to stderr.

For example, `search_graph` returns structured matches:

```json
{
  "results": [
    {
      "name": "processOrder",
      "path": "src/order.c"
    }
  ]
}

```

The `get_architecture` tool produces high-level summaries including language statistics, package counts, entry points, routes, and hotspots. The graph-aware search leverages AST-level information compiled from 158 vendored tree-sitter grammars (such as those defined in [`tools/tree-sitter-magma/grammar.js`](https://github.com/DeusData/codebase-memory-mcp/blob/main/tools/tree-sitter-magma/grammar.js)), ensuring results include qualified names and edge statistics.

## Output Format and Structure

All DeusData codebase-memory-mcp output follows a strict separation between data and diagnostics. This design ensures reliable piping to tools like `jq` without parsing interference from log messages.

### Stdout vs Stderr Contract

- **Stdout**: Contains only machine-readable results (JSON or plain text)
- **Stderr**: Receives progress indicators, timing information, and error details

This contract is maintained across all fifteen MCP tools and the indexing pipeline. The implementation in [`src/watcher/watcher.c`](https://github.com/DeusData/codebase-memory-mcp/blob/main/src/watcher/watcher.c) extends this pattern to automatic re-indexing operations, ensuring background updates don't corrupt primary output streams.

### JSON Envelope Options

Add the `--json` flag to any CLI command to receive a fully-wrapped envelope containing metadata about the execution. Without this flag, the binary returns the raw result object, optimizing for Unix pipeline compatibility.

## Common CLI Commands and Their Outputs

Below are practical examples demonstrating the expected output for common operations:

```bash

# Install (one-liner) – prints download and install messages to stderr

curl -fsSL https://raw.githubusercontent.com/DeusData/codebase-memory-mcp/main/install.sh | bash

# Output: "Downloading …", "Extracted …", "Installation complete. Restart your coding agent."

```

```bash

# Index a local repository

codebase-memory-mcp cli index_repository --repo-path /path/to/my-project

# Output: {"status":"indexed","project":"my-project","nodes":456789,"edges":1234567}

```

```bash

# Get architecture summary

codebase-memory-mcp cli get_architecture --project my-project

# Output: {"languages":["C","Python","JavaScript"],"packages":124,"entry_points":7,"routes":15,"hotspots":3}

```

```bash

# Search for functions matching a pattern

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

# Output: {"results":[{"name":"httpRequestHandler","path":"src/http.c"},{"name":"eventHandler","path":"src/events.ts"}]}

```

```bash

# Trace call-graph relationships

codebase-memory-mcp cli trace_path \
    --project my-project \
    --function-name ProcessOrder \
    --direction both

# Output: {"incoming":[...],"outgoing":[...]}

```

All examples respect the CLI mode contract and can be piped to `jq` for formatted display without filtering stderr.

## Key Implementation Details

The output characteristics of DeusData codebase-memory-mcp derive from specific architectural decisions in the source code:

- **Zero-dependency static binary**: Built as a Pure C static binary using [`scripts/build.sh`](https://github.com/DeusData/codebase-memory-mcp/blob/main/scripts/build.sh), eliminating runtime library interference with stdout/stderr handling
- **RAM-first pipeline**: Indexing occurs entirely in memory before the final SQLite dump, implemented in the core indexing logic
- **Graph persistence**: The [`internal/cbm/zstd_store.c`](https://github.com/DeusData/codebase-memory-mcp/blob/main/internal/cbm/zstd_store.c) module compresses knowledge graphs into `.codebase-memory/graph.db.zst` files, with the indexing JSON output reflecting the final persisted node and edge counts
- **Background watching**: The [`src/watcher/watcher.c`](https://github.com/DeusData/codebase-memory-mcp/blob/main/src/watcher/watcher.c) implementation monitors file systems for changes, triggering automatic re-indexing while maintaining the same output contracts

## Summary

- **DeusData codebase-memory-mcp** produces three categories of output: installation confirmations, indexing status JSON, and query result JSON
- All machine-readable data writes to **stdout**, while diagnostics and progress logs stream to **stderr**
- The **index_repository** command returns node and edge counts for the constructed knowledge graph
- **Query tools** return structured JSON containing code locations, architecture summaries, or call-graph traces
- Output is **local-only**; the static binary never contacts external services unless explicitly updating
- Results can be piped directly to `jq` or other Unix tools due to the clean stdout/stderr separation

## Frequently Asked Questions

### Does codebase-memory-mcp send output data to external services?

No. According to the source code analysis, all output remains local-only. The binary is a static, zero-dependency engine that processes code entirely on your machine. It only contacts external servers during explicit update or installation operations via [`install.sh`](https://github.com/DeusData/codebase-memory-mcp/blob/main/install.sh).

### Where does codebase-memory-mcp store its output files?

Indexed knowledge graphs are stored under `~/.cache/codebase-memory-mcp/` as compressed SQLite databases (`.codebase-memory/graph.db.zst`). The compression and storage logic is implemented in [`internal/cbm/zstd_store.c`](https://github.com/DeusData/codebase-memory-mcp/blob/main/internal/cbm/zstd_store.c), while the `index_repository` command confirms the final node and edge counts via stdout JSON.

### How can I pretty-print the JSON output from codebase-memory-mcp?

Pipe the stdout stream to `jq` or similar tools. Because the binary maintains a strict separation between stdout (data) and stderr (logs), you can safely run `codebase-memory-mcp cli search_graph --project my-project | jq` without filtering diagnostic messages. Alternatively, use the `--json` flag for a wrapped envelope format.

### What information is included in the architecture summary output?

The `get_architecture` tool returns a JSON object containing detected programming languages, package counts, entry points, route definitions, and code hotspots. This aggregates AST-level data from the knowledge graph built during indexing, providing a high-level view of project structure without requiring manual file traversal.