# How to Configure Custom File Extensions in .codebase-memory.json for codebase-memory-mcp

> Learn to configure custom file extensions in .codebase-memory.json for codebase-memory-mcp. Easily add new file types to your codebase analysis with clear instructions.

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

---

**To configure custom file extensions in codebase-memory-mcp, create a [`.codebase-memory.json`](https://github.com/DeusData/codebase-memory-mcp/blob/main/.codebase-memory.json) file in your repository root and populate the `extra_extensions` object with mappings between file suffixes (including the leading dot) and language identifiers.**

The `codebase-memory-mcp` indexing engine processes repositories to build contextual memory for AI coding assistants, but it relies on file extensions to determine language types. When your project uses non-standard extensions like [`.blade.php`](https://github.com/DeusData/codebase-memory-mcp/blob/main/.blade.php) or `.mjs`, you must configure custom file extensions in [`.codebase-memory.json`](https://github.com/DeusData/codebase-memory-mcp/blob/main/.codebase-memory.json) to ensure proper syntax highlighting and semantic analysis.

## Where the Configuration Lives

The tool expects the per-project configuration file at the repository root. According to the source code in [`src/discover/userconfig.c`](https://github.com/DeusData/codebase-memory-mcp/blob/main/src/discover/userconfig.c), the program searches for [`.codebase-memory.json`](https://github.com/DeusData/codebase-memory-mcp/blob/main/.codebase-memory.json) during initialization and parses it immediately after the global configuration loads. This file takes precedence over settings in `$XDG_CONFIG_HOME/codebase-memory-mcp/config.json`, allowing repository-specific overrides without affecting your system-wide setup.

## The extra_extensions Object Structure

The core of custom file extension configuration relies on the `extra_extensions` key. This JSON object accepts key-value pairs where:

- **Keys** must include the leading dot (e.g., `.mjs`, [`.blade.php`](https://github.com/DeusData/codebase-memory-mcp/blob/main/.blade.php))
- **Values** are language identifiers (e.g., `javascript`, `php`, `python`) and are case-insensitive
- Unknown language names are silently ignored to prevent indexing failures
- Missing or malformed files are skipped gracefully, allowing the indexer to continue with defaults

As documented in [`docs/CONFIGURATION.md`](https://github.com/DeusData/codebase-memory-mcp/blob/main/docs/CONFIGURATION.md), the extension matching supports multi-part suffixes such as [`.blade.php`](https://github.com/DeusData/codebase-memory-mcp/blob/main/.blade.php), which the indexer treats as a single extension key rather than nested extensions.

## Practical Configuration Example

Create a file named [`.codebase-memory.json`](https://github.com/DeusData/codebase-memory-mcp/blob/main/.codebase-memory.json) in your repository root:

```json
{
  "extra_extensions": {
    ".blade.php": "php",
    ".mjs": "javascript",
    ".twig": "html",
    ".xyz": "python"
  }
}

```

After saving this configuration, the MCP engine will index [`.blade.php`](https://github.com/DeusData/codebase-memory-mcp/blob/main/.blade.php) files as PHP, `.mjs` files as JavaScript, and `.xyz` files as Python the next time the session starts. Changes require a restart of the MCP server to take effect, as the indexer loads [`src/discover/userconfig.c`](https://github.com/DeusData/codebase-memory-mcp/blob/main/src/discover/userconfig.c) only during initialization.

## Precedence and Error Handling

The configuration system implements a clear hierarchy. Settings in [`.codebase-memory.json`](https://github.com/DeusData/codebase-memory-mcp/blob/main/.codebase-memory.json) override conflicting entries in the global configuration file located at `$XDG_CONFIG_HOME/codebase-memory-mcp/config.json`. If the JSON syntax is invalid or the file is missing entirely, the [`userconfig.c`](https://github.com/DeusData/codebase-memory-mcp/blob/main/userconfig.c) loader silently ignores the error and continues execution, ensuring that temporary configuration issues do not crash the indexing process.

## Summary

- **Create** a [`.codebase-memory.json`](https://github.com/DeusData/codebase-memory-mcp/blob/main/.codebase-memory.json) file in your repository root to define project-specific language mappings.
- **Use** the `extra_extensions` object to map non-standard file extensions to recognized language identifiers.
- **Include** the leading dot in extension keys (e.g., `.mjs` not `mjs`) for proper matching.
- **Place** multi-part extensions like [`.blade.php`](https://github.com/DeusData/codebase-memory-mcp/blob/main/.blade.php) as single keys in the configuration object.
- **Restart** the MCP server after changes, as configuration loads once at startup via [`src/discover/userconfig.c`](https://github.com/DeusData/codebase-memory-mcp/blob/main/src/discover/userconfig.c).

## Frequently Asked Questions

### What happens if I specify an unknown language identifier?

The codebase-memory-mcp indexer silently ignores unknown language values in the `extra_extensions` object. Files with those extensions will not be indexed for language-specific features, but the system continues processing other files without error.

### Can I override global configuration settings with my project file?

Yes. According to the implementation in [`src/discover/userconfig.c`](https://github.com/DeusData/codebase-memory-mcp/blob/main/src/discover/userconfig.c), the per-project [`.codebase-memory.json`](https://github.com/DeusData/codebase-memory-mcp/blob/main/.codebase-memory.json) file takes precedence over the global configuration at `$XDG_CONFIG_HOME/codebase-memory-mcp/config.json`. Any conflicting `extra_extensions` entries in your project file will replace the global definitions.

### Does the configuration support compound file extensions like .tar.gz?

Yes. The `extra_extensions` object treats the entire suffix as a single key, allowing you to map compound extensions such as [`.blade.php`](https://github.com/DeusData/codebase-memory-mcp/blob/main/.blade.php) or `.tar.gz` to appropriate language identifiers. Simply include the full extension string with its leading dot as the object key.

### What happens if my .codebase-memory.json contains syntax errors?

The parser in [`src/discover/userconfig.c`](https://github.com/DeusData/codebase-memory-mcp/blob/main/src/discover/userconfig.c) handles malformed JSON gracefully by ignoring the file and continuing with default settings or global configuration values. The MCP server will not crash, but your custom extensions will not be recognized until you fix the syntax errors and restart.