# How to Configure Custom File Extensions in Codebase-Memory

> Learn to configure custom file extensions in codebase-memory by creating a .codebase-memory.json file. Map file suffixes to language identifiers for enhanced code analysis.

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

---

**You configure custom file extensions in codebase-memory by creating a [`.codebase-memory.json`](https://github.com/DeusData/codebase-memory-mcp/blob/main/.codebase-memory.json) file in your repository root and adding an `extra_extensions` object that maps file suffixes to language identifiers.**

The `DeusData/codebase-memory-mcp` repository provides a flexible configuration system that allows you to index non-standard file types by mapping them to known languages. To configure custom file extensions in codebase-memory, you create a per-project JSON file that overrides the default language detection. This setup ensures that files like `*.blade.php` or `*.mjs` are correctly parsed and indexed by the MCP engine.

## Understanding the Configuration File

The [`.codebase-memory.json`](https://github.com/DeusData/codebase-memory-mcp/blob/main/.codebase-memory.json) file serves as the per-project configuration mechanism. When present in your repository root, it instructs the indexer how to treat file extensions that are not recognized by default. The configuration follows a strict JSON schema that the parser validates at runtime.

## Creating the [`.codebase-memory.json`](https://github.com/DeusData/codebase-memory-mcp/blob/main/.codebase-memory.json) File

### File Location Requirements

Place the configuration file at the root of your repository. The [`src/discover/userconfig.c`](https://github.com/DeusData/codebase-memory-mcp/blob/main/src/discover/userconfig.c) source file contains the logic that searches for this file at startup. If the file exists, the parser extracts the `extra_extensions` object and merges it into the internal language table.

### JSON Structure for Custom Extensions

The `extra_extensions` object requires specific formatting:

- Keys must include the leading dot (e.g., [`.blade.php`](https://github.com/DeusData/codebase-memory-mcp/blob/main/.blade.php), `.mjs`)
- Values are language identifiers (case-insensitive)
- Unknown language names are silently ignored

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

```

## Configuration Precedence and Loading

According to the `codebase-memory-mcp` source code in [`src/discover/userconfig.c`](https://github.com/DeusData/codebase-memory-mcp/blob/main/src/discover/userconfig.c), the per-project configuration takes precedence over global settings. If you have conflicting entries in `$XDG_CONFIG_HOME/codebase-memory-mcp/config.json`, the local [`.codebase-memory.json`](https://github.com/DeusData/codebase-memory-mcp/blob/main/.codebase-memory.json) values override them. The loader silently ignores malformed or missing files, allowing the indexer to continue without interruption.

## Supported Language Identifiers

When you configure custom file extensions, use standard language identifiers. The system accepts common names like `php`, `javascript`, `html`, and `python`. Refer to [`docs/CONFIGURATION.md`](https://github.com/DeusData/codebase-memory-mcp/blob/main/docs/CONFIGURATION.md) for the complete list of supported language mappings and additional configuration options.

## Summary

- Create [`.codebase-memory.json`](https://github.com/DeusData/codebase-memory-mcp/blob/main/.codebase-memory.json) in your repository root to configure custom file extensions in codebase-memory
- Use the `extra_extensions` object to map extensions (with leading dots) to language identifiers
- Per-project settings in [`src/discover/userconfig.c`](https://github.com/DeusData/codebase-memory-mcp/blob/main/src/discover/userconfig.c) override global configuration entries
- The system gracefully ignores unknown languages and malformed files

## Frequently Asked Questions

### Where do I place the [`.codebase-memory.json`](https://github.com/DeusData/codebase-memory-mcp/blob/main/.codebase-memory.json) file?

Place it at the root of your repository. The discovery mechanism in [`src/discover/userconfig.c`](https://github.com/DeusData/codebase-memory-mcp/blob/main/src/discover/userconfig.c) searches for this file when the MCP session initializes.

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

Unknown language names are silently ignored, as documented in the configuration reference. The indexer continues processing other entries without throwing errors.

### Does the local configuration override global settings?

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) takes precedence over the global configuration located at `$XDG_CONFIG_HOME/codebase-memory-mcp/config.json`.

### Do I need to restart the MCP session after updating the file?

Yes. Changes to [`.codebase-memory.json`](https://github.com/DeusData/codebase-memory-mcp/blob/main/.codebase-memory.json) take effect the next time the MCP session starts, as the configuration is loaded at startup by the user-config loader.