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

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 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 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, ensuring the final JSON output reflects the complete graph state.

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

{
  "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:

{
  "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), 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 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:

# 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."

# 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}

# 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}

# 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"}]}

# 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, 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 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 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.

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, 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.

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