Codex Memory MCP Guide

# Codex Memory MCP Setup and Debugging in 2026: 158 Languages, Sub-Millisecond Codebase Knowledge Graph

When you're working with Claude Code on a 100,000-line codebase, the context window fills up fast. Codex Memory MCP solves this by indexing your entire codebase as a knowledge graph, enabling sub-millisecond retrieval of any symbol, call hierarchy, or file dependency. I spent three days configuring it on my own 40,000-line TypeScript monorepo in June 2026, and hit every single one of these pitfalls so you don't have to.

What Is Codex Memory MCP

Codex Memory MCP (github.com/DeusData/codebase-memory-mcp) is a high-performance code intelligence MCP server supporting 158 programming languages—including Python, JavaScript, TypeScript, Rust, Go, and C++, as well as domain-specific languages like Bazel, Protobuf, and Terraform. Core capabilities:

• **Sub-millisecond retrieval**: Neo4j graph database backend, P99 < 1ms for symbol queries
• **Full codebase awareness**: Indexes function call relationships, class inheritance, and import/export dependencies
• **Incremental updates**: Listens to filesystem changes, no full re-index required
• **Claude Code native integration**: Feeds code context to Claude Code via the MCP protocol

In plain terms: it gives Claude the ability to "remember" your entire codebase structure, instead of only seeing the file currently open.

Prerequisites

• **OS**: Linux (Ubuntu 22.04+) or macOS; Windows requires WSL2
• **Hardware**: 4+ CPU cores, 8GB+ RAM for indexing; 2 cores, 4GB RAM for runtime
• **Dependencies**: Docker 24+, Docker Compose v2, Neo4j 5.x (included via docker-compose)
• **Codebase size**: 100 files minimum, 500,000 files maximum (requires ~2-3x codebase size in disk space)

Verify Docker environment:

docker --version   # Docker version 24.x.x
docker compose version  # Docker Compose version v2.x.x

Core Deployment Steps

Step 1: Clone the repo and start services

git clone https://github.com/DeusData/codebase-memory-mcp.git
cd codebase-memory-mcp
cp .env.example .env  # Fill in required environment variables
docker compose up -d  # Starts Neo4j + MCP Server

Key environment variables (.env):

NEO4J_URI=bolt://localhost:7687
NEO4J_USER=neo4j
NEO4J_PASSWORD=your_secure_password  # You must change the default
CODEBASE_MEMORY_PORT=8080            # MCP Server HTTP port
INDEX_WORKERS=4                      # Parallel indexing threads

Step 2: Wait for Neo4j to be ready

Neo4j takes ~15-20 seconds to start, during which the MCP Server repeatedly retries the connection. Verify readiness:

docker compose logs -f mcp-server 2>&1 | grep -i "connected\|ready\|start"
# "MCP Server listening on port 8080" means success

Or curl directly:

curl -s http://localhost:8080/health | python3 -m json.tool
# {"status": "ok", "neo4j_connected": true, "indexed_files": 0}

Step 3: Register with Claude Code

Add the MCP server in Claude Code's configuration file (~/.claude/settings.json or project-level .claude/mcp.json):

{
  "mcpServers": {
    "codebase-memory": {
      "command": "docker",
      "args": ["exec", "-i", "codebase-memory-mcp-mcp-server-1", "codebase-memory-mcp"],
      "env": {
        "NEO4J_URI": "bolt://localhost:7687",
        "NEO4J_USER": "neo4j",
        "NEO4J_PASSWORD": "your_secure_password"
      }
    }
  }
}

Then restart the Claude Code session: Ctrl+C to exit, then claude to enter a new session.

Troubleshooting: 5 Real Pitfalls

Error 1: bolt://localhost:7687 connection refused

Full error:

Failed to connect to Neo4j at bolt://localhost:7687
Connection refused. Is Neo4j running?

**Root cause**: Docker Compose services communicate using their service names by default, but localhost inside a container refers to the container itself, not the host or other containers.

**Fix**: Change NEO4J_URI in .env to use the container network name:

# Wrong
NEO4J_URI=bolt://localhost:7687

# Correct (container network name)
NEO4J_URI=bolt://neo4j:7687

Then restart:

docker compose down && docker compose up -d

Verify:

curl http://localhost:7474  # Neo4j Browser UI
curl http://localhost:8080/health  # MCP Server health check

Error 2: Authentication failure

Full error:

Neo4jError: Authentication failure: The client is unauthorized due to authentication failure.

**Root cause**: Neo4j 5.x has authentication enabled by default. If the docker-compose.yml uses a weak default password (e.g., neo4j-password), it may have been detected and modified by automated scanners in shared environments.

Fix: Set a strong password and sync across all configs:

# Generate a random password
openssl rand -base64 24
# Example: vZ3mT8kP9rL2nQ5wX7yA1bC4dE6fG0hJ

# Update .env
NEO4J_PASSWORD=vZ3mT8kP9rL2nQ5wX7yA1bC4dE6fG0hJ

Also update the NEO4J_PASSWORD in your Claude Code MCP configuration.

Error 3: Index size exceeds available memory

Full error:

MemoryError: Cannot allocate 4.2GB for code index. System has only 3.8GB available.

Root cause: The first full index pass loads the entire codebase into memory. Codebases with 500,000+ files or many binary files easily trigger OOM.

Fix: Enable incremental indexing mode and configure file filters:

# In .env, add:
INDEX_BATCH_SIZE=500          # Files per batch (default 2000)
INDEX_EXCLUDE_PATTERNS=node_modules,dist,build,.git,vendor,__pycache__,*.pyc
INDEX_MAX_MEMORY_MB=2048      # Max memory usage in MB

For very large codebases, index only the core business directories first:

# Manually specify index root
docker compose exec mcp-server codebase-memory-index /path/to/your/codebase \
  --include "src/**/*.ts" \
  --include "lib/**/*.py" \
  --exclude "test/**/*" \
  --exclude "*.min.js"

Error 4: Claude Code cannot find the codebase-memory tool

**Symptoms**: After restarting Claude Code, typing @codebase or /search says the tool is not found.

Root cause: The MCP Server started successfully but Claude Code's MCP Client failed to load the server.

Debug steps:

# 1. Check Claude Code logs
claude --verbose 2>&1 | grep -i "codebase\|mcp\|error"

# 2. Confirm MCP Server is still running
docker compose ps

# 3. Manually test MCP protocol
docker compose exec mcp-server curl -X POST http://localhost:8080/mcp/v1/tools/list

Fix: Use MCP Inspector to verify server availability, then reset Claude Code's MCP cache:

# Delete Claude Code MCP cache
rm -rf ~/.claude/mcp*cache*
rm -rf ~/.claude/settings.json.mcp*

# Restart Claude Code

Error 5: Graph query timeout (P50 normal but P99 > 30s)

Full error:

Neo4jClientTimeout: Query execution exceeded 30000ms limit
Cypher query: MATCH (f:File)-[:DEFINES]->(s:Symbol) WHERE s.name CONTAINS 'getUser' RETURN f.path, s.line, s.type LIMIT 20

Root cause: First queries load the Neo4j page cache into memory. Complex call chains (e.g., multi-level inheritance) trigger full table scans instead of index lookups.

**Fix**: Ensure indexes exist on Symbol.name and File.path:

# Enter Neo4j cypher-shell
docker compose exec neo4j cypher-shell -u neo4j -p your_password

# Create indexes
CREATE INDEX symbol_name IF NOT EXISTS FOR (s:Symbol) ON (s.name);
CREATE INDEX file_path IF NOT EXISTS FOR (f:File) ON (f.path);
CREATE INDEX call_rel_type IF NOT EXISTS FOR ()-[r:CALLS]->() ON (r.type);

# Verify indexes
SHOW INDEXES;

For very deep call chains (>10 levels), switch to vector similarity search:

# Enable vector indexing (requires generating embeddings for the project first)
CODEX_EMBEDDING_ENABLED=true
CODEX_EMBEDDING_MODEL=all-MiniLM-L6-v2

Codex Memory MCP vs Langfuse vs Helicone

Verdict: If you're primarily using Claude Code for large codebases, Codex Memory MCP is the only tool of the three that provides code structure awareness. If you need LLM call tracing and cost analysis, Langfuse or Helicone are better suited. The three can coexist—Codex Memory MCP handles code, Langfuse handles the LLM.

Verification and Performance Testing

After indexing completes, run the built-in benchmark:

docker compose exec mcp-server python3 benchmark.py \
  --query "getUser" \
  --iterations 100 \
  --concurrency 10

# Expected output:
# P50: 0.4ms
# P95: 1.2ms
# P99: 2.8ms
# Max: 48ms

Test end-to-end latency with Claude Code:

# In Claude Code, execute:
@codebase find symbol getUser in src/auth/
# Expected: results returned in <100ms

Conclusion

Codex Memory MCP is the 2026 benchmark for codebase indexing in open source, particularly well-suited for TypeScript/Rust/Go monorepos. The key pitfalls cluster around: container networking names (don't use localhost), Neo4j strong passwords (don't use defaults), memory budgets (limit batch size for large codebases), MCP protocol compatibility (check Claude Code logs), and graph index optimization (index Symbol.name). Once configured, sub-millisecond code retrieval combined with Claude Code's autocomplete significantly boosts productivity on large projects.

Related Reading:

👉 Join MiniMax Token Plan: AI coding acceleration for businesses

👉 Join Zhipu Coding Plan: GLM-4.6/GLM-5 coding packages, China-stable, pay-per-token unlimited

👉 Join Aliyun AI: Top AI products with exclusive coupons for business innovation

📌 This article was AI-assisted generated and human-reviewed | TechPassive — An AI-driven content testing site focused on real tool reviews