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

To configure custom file extensions in codebase-memory-mcp, create a .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 or .mjs, you must configure custom file extensions in .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, the program searches for .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)
• 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, the extension matching supports multi-part suffixes such as .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 in your repository root:

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

After saving this configuration, the MCP engine will index .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 only during initialization.

Precedence and Error Handling

The configuration system implements a clear hierarchy. Settings in .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 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 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 as single keys in the configuration object.
• Restart the MCP server after changes, as configuration loads once at startup via 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, the per-project .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 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 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.

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