Configuration System for codebase-memory-mcp: Understanding .cbmignore and Custom File Extensions

The codebase-memory-mcp configuration system uses a three-layer deterministic ignore architecture combining hard-coded safety rules, hierarchical .gitignore files, and a root-level .cbmignore file, alongside a JSON-based extension mapping in scripts/new-languages.json to control which files are indexed into the code graph.

The codebase-memory-mcp (CBM) repository implements a sophisticated configuration system for codebase-memory-mcp that determines exactly which files get indexed into its semantic code graph. This system balances safety and flexibility through layered ignore rules and extensible language support, ensuring deterministic discovery across diverse project structures.

Layered Ignore Architecture

CBM's discovery engine processes three distinct layers of ignore rules in strict order, with each layer building upon the previous to create a deterministic file set.

Hard-Coded Safety Rules

The foundation layer consists of built-in skip lists that protect critical directories and file types. According to the source code in src/discover/discover.c (lines 514-525), these hard-coded rules automatically exclude .git directories, node_modules, common build artefacts, and symbolic links. These safety rules are non-negotiable and cannot be overridden by subsequent configuration layers.

Gitignore Hierarchy

The second layer walks the repository tree to discover and apply standard .gitignore files using standard gitignore semantics. This includes project-specific .gitignore files, global git configuration, and system-wide ignore patterns. CBM respects the full gitignore specification including wildcards, directory-only matches, and pattern negation.

The .cbmignore Layer

The final layer introduces .cbmignore, a CBM-specific configuration file located at the repository root (<repo>/.cbmignore). Unlike .gitignore, CBM does not support nested .cbmignore files; only the root file controls additional ignore rules. Patterns follow standard gitignore syntax, but with specific precedence rules that interact uniquely with the previous layers.

How .cbmignore Works

The .cbmignore file provides project-specific fine-tuning of the discovery process, allowing you to exclude generated files or re-include paths ignored by .gitignore.

File Location and Syntax

Place .cbmignore at the repository root. The file uses standard gitignore pattern syntax: wildcards (*), directory anchors (/), and recursive globs (**) function identically to git. For example, to exclude generated protobuf files:

# .cbmignore (placed at repo root)

generated/
*.pb.go

Negation and Precedence Rules

Negated patterns using ! can re-include paths previously excluded by earlier rules within the same file or by the .gitignore hierarchy. However, as implemented in src/discover/discover.c, negation cannot override hard-coded safety rules—you cannot use !node_modules/ to index directories explicitly protected by the built-in skip list. Changes to .cbmignore take effect immediately on the next cbm discover run without requiring a rebuild.

Custom File Extensions and Language Support

CBM determines how to parse source files through extension-to-language mapping defined in scripts/new-languages.json.

This JSON file maps file extensions to language identifiers used by the internal language-server infrastructure. When the discovery engine encounters a file, it looks up the extension in this table; unrecognized extensions are ignored by default.

To add support for a new language, insert a key-value pair into scripts/new-languages.json:

{
  "rs": "rust",
  "tsx": "typescriptreact"
}

After modifying the file, rebuild the binary or execute the provided build script. CBM will then parse .rs and .tsx files during subsequent discovery runs.

Core Implementation Details

The configuration system implementation spans several key files in the repository.

Discovery Engine: The heart of the ignore logic resides in src/discover/discover.c, which orchestrates the three-layer processing and enforces the "non-negatable safety core" for built-in directories.

CLI Options: The mcp structure in src/mcp/mcp.c exposes the ignore_file field, which points to the .cbmignore path or NULL if none exists. You can override the default location via command line:

cbm discover --ignore-file=/path/to/custom.cbmignore /path/to/repo

Documentation: Comprehensive specifications live in docs/cbmignore.md (format details) and docs/CONFIGURATION.md (pipeline overview).

Practical Configuration Examples

Re-including a Gitignored Directory

If .gitignore contains obj/ but you need to index obj/special/, add to .cbmignore:

!obj/special/
obj/

This re-includes obj/special/ while keeping other obj/ directories ignored.

Excluding Build Artifacts

To prevent generated files from polluting the code graph:

# .cbmignore

dist/
coverage/
*.min.js

Summary

• The codebase-memory-mcp configuration system employs a three-layer deterministic ignore architecture: hard-coded safety rules, hierarchical .gitignore files, and root-level .cbmignore.
• Hard-coded skips in src/discover/discover.c protect sensitive directories like .git and node_modules and cannot be overridden.
• .cbmignore supports standard gitignore syntax with negation (!), but only the root file is processed—nested files are ignored.
• Custom file extensions are managed via scripts/new-languages.json, requiring a rebuild after modification to enable new language parsers.
• Configuration changes are immediate for the discovery process, with no rebuild required for .cbmignore updates.

Frequently Asked Questions

Can I use multiple .cbmignore files in nested directories?

No. Unlike .gitignore, codebase-memory-mcp only recognizes a single .cbmignore file located at the repository root. Nested .cbmignore files are ignored during the discovery process. Place all your CBM-specific ignore rules in the root file.

Why can't I re-include node_modules using negation patterns?

The hard-coded safety rules in src/discover/discover.c (lines 514-525) explicitly protect directories like node_modules, .git, and symbolic links. These built-in protections form a "non-negatable safety core" that persists regardless of any ! negation patterns in .cbmignore or .gitignore files.

How do I add support for a programming language not currently recognized?

Add the file extension and language identifier to scripts/new-languages.json following the existing JSON structure. After saving the file, you must rebuild the CBM binary or run the provided build script to compile the new extension mappings into the discovery engine.

Does codebase-memory-mcp pick up .cbmignore changes automatically?

Yes. Changes to .cbmignore take effect immediately for the discovery process. The next execution of cbm discover automatically applies the updated rules without requiring a project rebuild or recompilation of the binary itself.

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