How to Configure Custom File Extensions in Codebase-Memory

You configure custom file extensions in codebase-memory by creating a .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 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 File

File Location Requirements

Place the configuration file at the root of your repository. The 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, .mjs)
• Values are language identifiers (case-insensitive)
• Unknown language names are silently ignored

{
  "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, 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 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 for the complete list of supported language mappings and additional configuration options.

Summary

• Create .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 override global configuration entries
• The system gracefully ignores unknown languages and malformed files

Frequently Asked Questions

Where do I place the .codebase-memory.json file?

Place it at the root of your repository. The discovery mechanism in 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, the per-project .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 take effect the next time the MCP session starts, as the configuration is loaded at startup by the user-config loader.

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