# Project Structure of the src Directory in DeusData/codebase-memory-mcp: Modular C Architecture Explained

> Explore the DeusData/codebase-memory-mcp src directory structure. Discover its modular C architecture, domain-driven layout, and dependency-free modules for core indexing, persistence, and UI.

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

---

**The `src` directory follows a domain-driven, modular layout with twelve specialized subdirectories that separate low-level foundation utilities, file discovery, the core MCP indexing engine, SQLite persistence, web UI, and query language components into dependency-free C modules.**

The `src` folder serves as the heart of **codebase-memory-mcp**, a C-language library designed to index, search, and track changes across codebases. Understanding the project structure of the `src` directory in DeusData/codebase-memory-mcp is essential for developers extending the indexing engine or integrating the library into their own tooling. Each subdirectory groups related concerns into clean abstractions that progress from raw filesystem detection to interactive visualization.

## Overview of the src Layout

The repository organizes code into twelve top-level subdirectories under `src/`, each addressing a specific architectural concern. This separation ensures that core indexing logic remains isolated from platform-specific UI code or persistent storage implementations.

- **foundation/**: Low-level utilities for memory management, logging, and platform abstraction
- **discover/**: File detection, `.gitignore` parsing, and language identification
- **cli/**: Command-line interface and configuration editors
- **mcp/**: Core Memory-Code-Probe engine for indexing and supervision
- **git/**: Thin wrapper around libgit2 for repository introspection
- **store/**: SQLite-based persistent storage of the index
- **ui/**: Optional embedded HTTP server and 3D visualization
- **watcher/**: Cross-platform filesystem monitoring
- **simhash/**: MinHash algorithms for fuzzy similarity detection
- **cypher/**: Query language interpreter for structural searches
- **traces/**: Lightweight history tracking for file-level changes
- **graph_buffer/**: In-memory graph representation during index construction

The entry point [`src/main.c`](https://github.com/DeusData/codebase-memory-mcp/blob/main/src/main.c) orchestrates these modules, binding together CLI arguments, configuration loading, and the live filesystem watcher.

## Foundation: Portable Core Utilities

The `src/foundation/` directory provides dependency-free building blocks used throughout the project. These modules deliberately avoid external libraries to maximize portability across platforms.

**Memory and Logging Infrastructure**

The logging system centers on [[`src/foundation/log.h`](https://github.com/DeusData/codebase-memory-mcp/blob/main/src/foundation/log.h)](https://github.com/DeusData/codebase-memory-mcp/blob/main/src/foundation/log.h) and [`log.c`](https://github.com/DeusData/codebase-memory-mcp/blob/main/log.c), offering unified log levels accessible via `log_init()` and `log_error()`. Memory management relies on [[`src/foundation/arena.h`](https://github.com/DeusData/codebase-memory-mcp/blob/main/src/foundation/arena.h)](https://github.com/DeusData/codebase-memory-mcp/blob/main/src/foundation/arena.h), which implements an arena allocator used heavily by the indexer to batch-allocate objects efficiently.

**Data Structures and Cryptography**

Hash tables and SHA-256 implementations reside here, with [[`src/foundation/sha256.h`](https://github.com/DeusData/codebase-memory-mcp/blob/main/src/foundation/sha256.h)](https://github.com/DeusData/codebase-memory-mcp/blob/main/src/foundation/sha256.h) providing content hashing for deduplication. Platform abstractions in [`platform.h`](https://github.com/DeusData/codebase-memory-mcp/blob/main/platform.h) wrap OS-specific threading and file operations, ensuring the engine runs consistently on Linux, macOS, and Windows.

## Discovery and Configuration

The `src/discover/` module determines what files require indexing. It respects project boundaries defined by `.gitignore` and identifies language-specific parsers based on file extensions and content heuristics.

Key files include [[`src/discover/discover.h`](https://github.com/DeusData/codebase-memory-mcp/blob/main/src/discover/discover.h)](https://github.com/DeusData/codebase-memory-mcp/blob/main/src/discover/discover.h), which exposes the `discover_project()` API, and [[`src/discover/language.c`](https://github.com/DeusData/codebase-memory-mcp/blob/main/src/discover/language.c)](https://github.com/DeusData/codebase-memory-mcp/blob/main/src/discover/language.c), containing detection logic for parsing strategies. The configuration subsystem in [`userconfig.h`](https://github.com/DeusData/codebase-memory-mcp/blob/main/userconfig.h) loads YAML/TOML preferences that control indexing depth and exclusion patterns.

## The MCP Core Engine

At the center of the architecture sits `src/mcp/`, the Memory-Code-Probe engine responsible for parsing source files, building the semantic graph, and supervising multi-threaded indexing operations.

**Indexing and Supervision**

The public API in [[`src/mcp/mcp.h`](https://github.com/DeusData/codebase-memory-mcp/blob/main/src/mcp/mcp.h)](https://github.com/DeusData/codebase-memory-mcp/blob/main/src/mcp/mcp.h) declares `mcp_init()` for engine initialization and `mcp_index()` to trigger full repository walks. Internally, [[`src/mcp/index_supervisor.c`](https://github.com/DeusData/codebase-memory-mcp/blob/main/src/mcp/index_supervisor.c)](https://github.com/DeusData/codebase-memory-mcp/blob/main/src/mcp/index_supervisor.c) coordinates worker threads and manages the in-memory graph buffer. Output compaction occurs in [`compact_out.c`](https://github.com/DeusData/codebase-memory-mcp/blob/main/compact_out.c), which serializes the index to a binary format for efficient storage.

## Persistence and Version Control Integration

The `src/store/` and `src/git/` directories handle data durability and incremental updates.

**SQLite Storage Layer**

[[`src/store/store.h`](https://github.com/DeusData/codebase-memory-mcp/blob/main/src/store/store.h)](https://github.com/DeusData/codebase-memory-mcp/blob/main/src/store/store.h) defines `store_open()` and `store_write()`, wrapping SQLite operations to persist the index between runs. This allows the engine to reload previous states instantly rather than re-parsing unchanged files.

**Git Integration**

[[`src/git/git_context.c`](https://github.com/DeusData/codebase-memory-mcp/blob/main/src/git/git_context.c)](https://github.com/DeusData/codebase-memory-mcp/blob/main/src/git/git_context.c) creates a `git_repository` object via libgit2, enabling the engine to fetch commit metadata and compute incremental diffs. This integration supports the "traces" feature that tracks file evolution across commits.

## User Interfaces: CLI and Web

The project exposes functionality through two interface layers in `src/cli/` and `src/ui/`.

**Command-Line Interface**

[[`src/cli/cli.h`](https://github.com/DeusData/codebase-memory-mcp/blob/main/src/cli/cli.h)](https://github.com/DeusData/codebase-memory-mcp/blob/main/src/cli/cli.h) provides `cli_run()`, the entry point for the `mcp-cli` binary. Configuration editing is handled by [[`src/cli/config_yaml_edit.c`](https://github.com/DeusData/codebase-memory-mcp/blob/main/src/cli/config_yaml_edit.c)](https://github.com/DeusData/codebase-memory-mcp/blob/main/src/cli/config_yaml_edit.c), which supports interactive YAML modification for agent profiles and indexing rules.

**Optional HTTP UI**

The `src/ui/` directory contains an embedded HTTP server and 3D visualization components. [[`src/ui/http_server.c`](https://github.com/DeusData/codebase-memory-mcp/blob/main/src/ui/http_server.c)](https://github.com/DeusData/codebase-memory-mcp/blob/main/src/ui/http_server.c) handles incoming requests, while [[`src/ui/layout3d.c`](https://github.com/DeusData/codebase-memory-mcp/blob/main/src/ui/layout3d.c)](https://github.com/DeusData/codebase-memory-mcp/blob/main/src/ui/layout3d.c) generates JSON representations of the code graph for frontend rendering. The [`embedded_assets.h`](https://github.com/DeusData/codebase-memory-mcp/blob/main/embedded_assets.h) file bundles static web resources directly into the binary.

## Real-Time Processing and Analysis

**Filesystem Watching**

The `src/watcher/` module implements cross-platform file monitoring using `inotify` on Linux and `ReadDirectoryChangesW` on Windows. [[`src/watcher/watcher.c`](https://github.com/DeusData/codebase-memory-mcp/blob/main/src/watcher/watcher.c)](https://github.com/DeusData/codebase-memory-mcp/blob/main/src/watcher/watcher.c) exposes `watcher_start()`, which pushes change events to the MCP engine for incremental reindexing.

**Similarity Detection and Querying**

Fuzzy matching capabilities reside in `src/simhash/`, where [[`src/simhash/minhash.h`](https://github.com/DeusData/codebase-memory-mcp/blob/main/src/simhash/minhash.h)](https://github.com/DeusData/codebase-memory-mcp/blob/main/src/simhash/minhash.h) implements locality-sensitive hashing for finding similar code fragments. The `src/cypher/` directory provides a small query language interpreter in [[`src/cypher/cypher.c`](https://github.com/DeusData/codebase-memory-mcp/blob/main/src/cypher/cypher.c)](https://github.com/DeusData/codebase-memory-mcp/blob/main/src/cypher/cypher.c), allowing structural searches like "find all functions calling X" against the indexed graph.

## Working with the Source Code

Below are practical examples demonstrating typical interactions with the library.

### Initializing the MCP Engine

```c
#include "mcp/mcp.h"
#include "foundation/log.h"

int main(void) {
    log_init();                     // set up foundation logging
    struct mcp *engine = mcp_init("config.yaml");
    if (!engine) {
        log_error("Failed to create MCP engine");
        return 1;
    }

    // Index the whole repository (discover + walk)
    if (mcp_index(engine, "./my-repo") != 0) {
        log_error("Indexing failed");
        mcp_free(engine);
        return 1;
    }

    log_info("Indexing completed");
    mcp_free(engine);
    return 0;
}

```

*Key files*: [`src/mcp/mcp.h`](https://github.com/DeusData/codebase-memory-mcp/blob/main/src/mcp/mcp.h), [`src/mcp/mcp.c`](https://github.com/DeusData/codebase-memory-mcp/blob/main/src/mcp/mcp.c), [`src/foundation/log.h`](https://github.com/DeusData/codebase-memory-mcp/blob/main/src/foundation/log.h).

### Launching the Config Editor

```bash

# Interactive YAML editing via CLI

$ ./mcp-cli config edit --file config.yaml

```

This invokes [`src/cli/config_yaml_edit.c`](https://github.com/DeusData/codebase-memory-mcp/blob/main/src/cli/config_yaml_edit.c) to parse and modify configuration files.

### Starting the Web Interface

```bash
$ ./mcp-cli ui --port 8080

```

The command spawns the server defined in [`src/ui/http_server.c`](https://github.com/DeusData/codebase-memory-mcp/blob/main/src/ui/http_server.c), serving the 3D visualization at `http://localhost:8080`.

### Real-Time File Watching

```c
#include "watcher/watcher.h"
#include "mcp/mcp.h"

void on_change(const char *path, void *user) {
    struct mcp *engine = user;
    mcp_reindex_file(engine, path);
}

int main(void) {
    struct mcp *engine = mcp_init("config.yaml");
    watcher_start(".", on_change, engine);
    // Event loop processes filesystem changes
}

```

*Key files*: [`src/watcher/watcher.h`](https://github.com/DeusData/codebase-memory-mcp/blob/main/src/watcher/watcher.h), [`src/mcp/mcp.h`](https://github.com/DeusData/codebase-memory-mcp/blob/main/src/mcp/mcp.h).

## Summary

- The `src` directory contains twelve specialized modules following a pipeline from filesystem detection to visualization.
- **foundation/** provides portable, dependency-free utilities for memory, logging, and cryptography.
- **discover/** handles project detection and `.gitignore` compliance.
- **mcp/** houses the core indexing engine with multi-threaded supervision.
- **store/** and **git/** manage SQLite persistence and libgit2 integration.
- **cli/** and **ui/** offer dual interfaces: a command-line tool and an optional embedded HTTP server.
- **watcher/**, **simhash/**, and **cypher/** enable real-time updates, fuzzy matching, and structural query capabilities.
- The entry point [`src/main.c`](https://github.com/DeusData/codebase-memory-mcp/blob/main/src/main.c) initializes all subsystems and routes between CLI and UI modes.

## Frequently Asked Questions

### What is the primary entry point for the codebase-memory-mcp application?

The primary entry point is [[`src/main.c`](https://github.com/DeusData/codebase-memory-mcp/blob/main/src/main.c)](https://github.com/DeusData/codebase-memory-mcp/blob/main/src/main.c), which initializes the foundation logging system, parses command-line arguments, loads configuration files, and decides whether to launch in CLI mode or spawn the HTTP UI and filesystem watcher.

### How does the discovery module respect .gitignore patterns?

The `src/discover/` module implements git-ignore parsing logic in [`gitignore.c`](https://github.com/DeusData/codebase-memory-mcp/blob/main/gitignore.c), which filters the file tree during the discovery phase. This ensures that build artifacts, dependency directories, and other ignored paths are excluded from the index before language detection and parsing occur.

### Which directory contains the core indexing logic?

The core indexing logic resides in `src/mcp/`, specifically in [[`src/mcp/mcp.c`](https://github.com/DeusData/codebase-memory-mcp/blob/main/src/mcp/mcp.c)](https://github.com/DeusData/codebase-memory-mcp/blob/main/src/mcp/mcp.c) and [[`src/mcp/index_supervisor.c`](https://github.com/DeusData/codebase-memory-mcp/blob/main/src/mcp/index_supervisor.c)](https://github.com/DeusData/codebase-memory-mcp/blob/main/src/mcp/index_supervisor.c). These files implement `mcp_index()` and coordinate the multi-threaded parsing pipeline that converts source files into the in-memory graph representation.

### Can the web UI be excluded when building the project?

Yes, the `src/ui/` components are optional dependencies. The build system can exclude [`http_server.c`](https://github.com/DeusData/codebase-memory-mcp/blob/main/http_server.c) and [`layout3d.c`](https://github.com/DeusData/codebase-memory-mcp/blob/main/layout3d.c) if you only need the CLI tooling and indexing engine. The [`src/main.c`](https://github.com/DeusData/codebase-memory-mcp/blob/main/src/main.c) entry point checks for UI availability at compile time, allowing minimal binaries that exclude the HTTP server and embedded web assets.