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

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 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) and 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), 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) providing content hashing for deduplication. Platform abstractions in 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), which exposes the discover_project() API, and [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 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) 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) coordinates worker threads and manages the in-memory graph buffer. Output compaction occurs in 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) 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) 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) 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), 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) handles incoming requests, while [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 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) 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) 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), 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

#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, src/mcp/mcp.c, src/foundation/log.h.

Launching the Config Editor

# Interactive YAML editing via CLI

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

This invokes src/cli/config_yaml_edit.c to parse and modify configuration files.

Starting the Web Interface

$ ./mcp-cli ui --port 8080

The command spawns the server defined in src/ui/http_server.c, serving the 3D visualization at http://localhost:8080.

Real-Time File Watching

#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, 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 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), 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, 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) and [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 and layout3d.c if you only need the CLI tooling and indexing engine. The src/main.c entry point checks for UI availability at compile time, allowing minimal binaries that exclude the HTTP server and embedded web assets.

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