Common Errors When Using DeusData codebase-memory-mcp: Installation, Configuration, and Daemon Issues Explained

Most common errors in DeusData codebase-memory-mcp stem from macOS quarantine restrictions, PowerShell execution policies, daemon version conflicts, and port binding issues, all of which can be resolved with specific permission changes and configuration adjustments.

codebase-memory-mcp is a high-performance, single-binary code-intelligence engine maintained by DeusData. While the tool is designed for seamless integration with coding agents, users frequently encounter roadblocks during the initial installation phase, daemon coordination, or environment configuration. Understanding these failure modes—documented explicitly in the repository's README.md and installer scripts—ensures you can diagnose and resolve issues without debugging the underlying C source directly.

Installation Script Failures

The first interaction most users have with the repository involves the automated installation scripts. These scripts handle binary placement, permission stripping, and agent configuration, but platform-specific security controls often interrupt the process.

macOS Quarantine and Missing Execute Permissions

macOS adds a quarantine attribute to downloaded files, preventing install.sh from running even after download. According to line 100 of the documentation, the script attempts to strip this attribute automatically, but older macOS versions may still block execution. Additionally, the script may lack execute permissions upon download.

Run the following commands to resolve both issues:

chmod +x install.sh
xattr -d com.apple.quarantine ./install.sh
./install.sh

Windows PowerShell Execution Policy Errors

PowerShell's default execution policy blocks unsigned scripts, causing install.ps1 to fail immediately. The README warns about this restriction at lines 70-71.

Temporarily bypass the policy for the current session:

Set-ExecutionPolicy -Scope Process Bypass
.\install.ps1

Alternatively, launch the installer with explicit policy bypass:

PowerShell -ExecutionPolicy Bypass -File .\install.ps1

Daemon Coordination and Runtime Conflicts

Once installed, codebase-memory-mcp relies on a coordination daemon that enforces strict consistency across all running processes. Mismatches in this layer produce immediate failures.

Duplicate Daemon and Version Mismatch

The coordination daemon requires that all running processes share the same binary build and cache root. If a different version is launched, the daemon aborts with a conflict message, as noted at lines 119-120.

Resolve this by updating all sessions to the same version and terminating stray processes:

codebase-memory-mcp update
pkill codebase-memory-mcp
codebase-memory-mcp install

The update command is documented at lines 158-161.

UI Port Already in Use

The UI component binds to port 9749 by default. If another process holds that port, the UI fails to start silently or with a binding error. Lines 138-141 describe the UI launch parameters.

Check for port conflicts:

# Linux/macOS

lsof -i :9749

# Windows

netstat -ano | findstr 9749

Launch the UI on an alternative port:

codebase-memory-mcp --ui=true --port=9750

Configuration and Environment Issues

Beyond installation and runtime conflicts, several environment-specific misconfigurations can prevent the daemon from starting or indexing correctly.

Auto-Index Limits and Watcher Registration

By default, the daemon watches every new project through the file-watcher implemented in src/watcher/watcher.c. In environments with massive repository counts, the watcher hits internal file limits, causing indexing to stop silently. Lines 145-152 document these configurable limits.

Reduce the auto-index limit or disable automatic watching:

codebase-memory-mcp config set auto_index_limit 20000
codebase-memory-mcp config set auto_watch false

The auto_watch configuration is specifically mentioned at line 154.

Missing CBM_CACHE_DIR Environment Variable

The daemon stores logs and index data under ${CBM_CACHE_DIR}. If this variable is unset or points to a non-existent directory, the daemon refuses to start, often without a descriptive error message.

Set the variable and ensure the directory exists:

export CBM_CACHE_DIR=$HOME/.cache/codebase-memory-mcp
mkdir -p $CBM_CACHE_DIR

Binary Variant Mismatch (Headless vs UI)

The repository ships two distinct binaries: a lean headless version and a UI-enabled variant. Running the headless binary with UI-specific flags triggers "unknown flag" errors. Lines 31-33 reference the --ui installer flag.

Verify your installed variant:

codebase-memory-mcp --version

The output should list variant=ui if the UI components are present. If not, reinstall using the --ui flag with the installer script.

Integration Failures with Coding Agents

Even after successful installation, the connection to coding agents can fail if configuration updates are not properly propagated.

Agent Configuration Not Refreshed

The installer writes MCP entries into supported coding-agent configuration files. If the agent process is not restarted after installation, it cannot see the new entries, resulting in "no index found" errors. Line 74 explicitly recommends restarting the agent.

Always restart your coding agent after running the installer. Verify the configuration entry was written correctly:

codebase-memory-mcp config list

Summary

• macOS quarantine errors require removing the extended attribute with xattr -d com.apple.quarantine and setting execute permissions with chmod +x.
• PowerShell execution policy blocks are resolved by running Set-ExecutionPolicy -Scope Process Bypass or using the -ExecutionPolicy Bypass flag.
• Daemon version conflicts require running codebase-memory-mcp update and killing lingering processes with pkill.
• Port binding failures on port 9749 can be avoided by checking for conflicts with lsof or specifying an alternative port with --port.
• Auto-index limits in the file-watcher (src/watcher/watcher.c) can be adjusted via config set auto_index_limit or disabled with auto_watch false.
• Missing cache directories must be resolved by setting CBM_CACHE_DIR and creating the path manually.
• Binary variant mismatches between headless and UI versions require reinstalling with the correct --ui flag.
• Agent integration issues are fixed by restarting the coding agent after installation to load the new MCP configuration.

Frequently Asked Questions

Why does codebase-memory-mcp fail with "duplicate daemon" errors?

This occurs when multiple codebase-memory-mcp processes with different binary builds or cache roots attempt to run simultaneously. The coordination daemon enforces strict version consistency as documented at lines 119-120. Resolve this by running codebase-memory-mcp update to synchronize all sessions, then terminate any stray processes with pkill codebase-memory-mcp before restarting.

How do I fix the UI not starting on port 9749?

Port 9749 is the default binding for the web interface. If another service occupies this port, the UI fails to initialize. Check for conflicts using lsof -i :9749 on Unix systems or netstat -ano | findstr 9749 on Windows. Alternatively, launch the UI on a different port using the command codebase-memory-mcp --ui=true --port=9750 as shown at lines 138-141.

What should I do if the installation script is blocked on macOS?

macOS Gatekeeper adds a quarantine attribute to downloaded scripts, preventing execution. Before running ./install.sh, execute xattr -d com.apple.quarantine ./install.sh to remove the security flag, and ensure the script has execute permissions with chmod +x install.sh. The installation documentation at line 100 references this specific remediation step.

How do I verify which binary variant (headless vs UI) I have installed?

Run codebase-memory-mcp --version and examine the output for the variant field. If it displays variant=ui, the UI-enabled binary is installed. If the field is missing or shows variant=headless, you have the lean version that does not support UI flags. To install the UI variant, rerun the installer with the --ui flag as indicated at lines 31-33.

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