# How to Enable the 3D Graph Visualization UI in codebase-memory-mcp

> Enable the 3D graph visualization UI in codebase-memory-mcp by using a UI-enabled binary and the --ui flag. Access the interactive graph at localhost:9749 and explore your codebase like never before.

- Repository: [Martin Vogel/codebase-memory-mcp](https://github.com/DeusData/codebase-memory-mcp)
- Tags: how-to-guide
- Published: 2026-07-12

---

**To enable the 3D graph visualization UI in codebase-memory-mcp, you must use a UI-enabled binary variant and start the server with the `--ui` flag, then access `http://localhost:9749` in your browser.**

The 3D graph visualization UI is an optional front-end component for the `DeusData/codebase-memory-mcp` repository that provides an interactive Three.js-based interface for exploring knowledge graphs. Unlike the default headless binary, this feature requires a specific UI-enabled build and explicit activation via command-line flags. The UI assets live in the `graph-ui/` directory and are served by an embedded HTTP server when properly configured.

## Obtaining the UI-Enabled Binary

The visualization interface is not included in the standard headless binary distribution. You must either download a pre-built UI variant or compile the project with UI support enabled.

### Download a Pre-built Release

The maintainers distribute UI-enabled binaries as separate release artifacts with the `-ui` suffix (e.g., `codebase-memory-mcp-ui-linux-amd64.tar.gz`). These builds are available in the "Pre-built Binaries" section of the repository README. Download and extract the appropriate archive for your platform to obtain a binary with embedded UI assets.

### Build from Source with the `--with-ui` Flag

To compile the UI yourself, clone the repository and execute the build script with the `--with-ui` flag. This process compiles the React/Three.js assets in `graph-ui/` and embeds the `graph-ui/dist/` directory into the final binary:

```bash
git clone https://github.com/DeusData/codebase-memory-mcp.git
cd codebase-memory-mcp
scripts/build.sh --with-ui

```

The build system, as defined in `Makefile.cbm` (line 716), handles the npm dependency installation (`npm ci`) and production build (`npm run build`) before embedding the assets into the C binary.

## Starting the Server with UI Support

Once you have the UI-enabled binary, you must explicitly activate the embedded HTTP server using the `--ui` command-line flag. The server reads this flag (or corresponding configuration key) to determine whether to serve the React front-end.

Use the official installer with the `--ui` shortcut:

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

```

Or run the binary directly with explicit flags:

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

```

The embedded HTTP server implementation in [`src/ui/http_server.c`](https://github.com/DeusData/codebase-memory-mcp/blob/main/src/ui/http_server.c) initializes an Express-style server that listens on the specified port (default 9749) and serves the compiled UI assets from memory when `--ui` is set to `true`.

## Exploring the 3D Interface

Once the server is running, open `http://localhost:9749` in a modern web browser. The interface renders the knowledge graph as an interactive 3-D scene using **React** and **Three.js**.

The main rendering logic resides in [`graph-ui/src/components/GraphScene.tsx`](https://github.com/DeusData/codebase-memory-mcp/blob/main/graph-ui/src/components/GraphScene.tsx), which initializes a Three.js `PerspectiveCamera`, `OrbitControls`, and WebGL renderer to display the graph nodes and edges. For performance optimization with large datasets, the [`NodeCloud.tsx`](https://github.com/DeusData/codebase-memory-mcp/blob/main/NodeCloud.tsx) component implements instanced mesh handling to efficiently render thousands of nodes simultaneously.

The UI includes a settings menu ([`DisplaySettingsMenu.tsx`](https://github.com/DeusData/codebase-memory-mcp/blob/main/DisplaySettingsMenu.tsx)) that allows real-time adjustment of contrast and brightness parameters, manipulating the Three.js scene properties directly.

## Summary

- The 3D graph visualization UI requires a **UI-enabled binary variant** (either downloaded pre-built or compiled with `--with-ui`).
- Start the server with the **`--ui=true`** flag to activate the embedded HTTP server defined in [`src/ui/http_server.c`](https://github.com/DeusData/codebase-memory-mcp/blob/main/src/ui/http_server.c).
- Access the interface at **`http://localhost:9749`** (default port).
- The front-end is built with **React and Three.js**, with key components located in `graph-ui/src/components/`.
- The build process embeds `graph-ui/dist/` assets into the binary, making the UI available without external dependencies at runtime.

## Frequently Asked Questions

### Is the 3D graph visualization UI included in the default binary?

No. The default headless binary does not contain UI assets. You must use a release artifact with the `-ui` suffix or build from source using `scripts/build.sh --with-ui` to embed the `graph-ui/` assets into the binary.

### What port does the visualization UI use?

By default, the HTTP server listens on **port 9749**. You can specify a custom port using the `--port` flag (e.g., `codebase-memory-mcp --ui=true --port=8080`).

### Can I modify the UI without rebuilding the entire binary?

While the UI assets are embedded at compile time for distribution, you can run the UI in development mode separately. Navigate to `graph-ui/`, run `npm install` and `npm start` to launch the React development server, which will proxy API requests to the backend MCP server running independently.

### Which technologies power the 3D graph visualization?

The UI is built with **React** for the interface layer and **Three.js** for 3-D rendering. The [`GraphScene.tsx`](https://github.com/DeusData/codebase-memory-mcp/blob/main/GraphScene.tsx) component manages the Three.js scene graph, while [`NodeCloud.tsx`](https://github.com/DeusData/codebase-memory-mcp/blob/main/NodeCloud.tsx) uses instanced meshes for high-performance node rendering. The embedded server in [`src/ui/http_server.c`](https://github.com/DeusData/codebase-memory-mcp/blob/main/src/ui/http_server.c) serves these static assets when the `--ui` flag is enabled.