LightRAG Code Brain

LightRAG Code Brain MCP turns a local LightRAG server into a persistent project brain for coding agents such as Claude Code and Codex.

It provides:

• whole-codebase indexing with conservative default excludes and secret redaction
• multi-repo source names with repo_id:relative/path
• RAG query/context/data tools
• durable memory across sessions
• senior-developer project profile sections
• a task gate that encourages agents to load/update memory for non-trivial work

What This Solves

Coding agents often reread the same files, forget prior fixes, and lose setup history between sessions. This MCP gives them a durable memory layer:

• architecture and module boundaries
• conventions, workflows, and hazards
• debugging playbooks and failed attempts
• setup outcomes and provider quirks
• current project profile and handoff notes

It does not replace reading source files for exact edits. It reduces discovery tokens and gives the agent a senior-engineer orientation before it opens files.

Requirements

• Docker with Compose
• Python 3.10+
• A chat/LLM provider compatible with OpenAI chat completions
• An embeddings provider compatible with OpenAI /v1/embeddings
• Claude Code and/or Codex if you want agent integration

Quick Start

git clone https://github.com/YOUR_ORG/lightrag-code-brain-mcp.git
cd lightrag-code-brain-mcp
cp .env.example .env

Edit .env:

LIGHTRAG_AUTH_ACCOUNTS="admin:your-password"
LIGHTRAG_USERNAME="admin"
LIGHTRAG_PASSWORD="your-password"
LIGHTRAG_TOKEN_SECRET="a-long-random-string"

LIGHTRAG_LLM_BINDING_HOST="https://api.openai.com/v1"
LIGHTRAG_LLM_API_KEY="..."
LIGHTRAG_LLM_MODEL="gpt-4o-mini"

LIGHTRAG_EMBEDDING_BINDING_HOST="https://api.openai.com/v1"
LIGHTRAG_EMBEDDING_API_KEY="..."
LIGHTRAG_EMBEDDING_MODEL="text-embedding-3-large"
LIGHTRAG_EMBEDDING_DIM="3072"

Start LightRAG:

docker compose up -d
curl http://127.0.0.1:9621/health

NVIDIA NIM Embeddings

If you use NVIDIA NIM, this model worked with LightRAG's OpenAI-compatible embedding call because it does not require input_type:

LIGHTRAG_EMBEDDING_BINDING_HOST="https://integrate.api.nvidia.com/v1"
LIGHTRAG_EMBEDDING_API_KEY="nvapi-..."
LIGHTRAG_EMBEDDING_MODEL="nvidia/nv-embed-v1"
LIGHTRAG_EMBEDDING_DIM="4096"

Some NVIDIA embedding models require input_type; those may fail through LightRAG's default OpenAI embedding request.

Install In Codex

export LIGHTRAG_URL="http://127.0.0.1:9621"
export LIGHTRAG_USERNAME="admin"
export LIGHTRAG_PASSWORD="your-password"
export LIGHTRAG_DEFAULT_REPO_ROOT="/path/to/your/project"
export LIGHTRAG_DEFAULT_REPO_ID="my-project"
./install-codex.sh
codex mcp list

This runs:

codex mcp add lightrag-code-brain \
  --env LIGHTRAG_URL=http://127.0.0.1:9621 \
  --env LIGHTRAG_USERNAME=admin \
  --env LIGHTRAG_PASSWORD=your-password \
  --env LIGHTRAG_DEFAULT_REPO_ROOT=/path/to/your/project \
  --env LIGHTRAG_DEFAULT_REPO_ID=my-project \
  -- python /absolute/path/lightrag_mcp_server.py

Install In Claude Code

export LIGHTRAG_URL="http://127.0.0.1:9621"
export LIGHTRAG_USERNAME="admin"
export LIGHTRAG_PASSWORD="your-password"
export LIGHTRAG_DEFAULT_REPO_ROOT="/path/to/your/project"
export LIGHTRAG_DEFAULT_REPO_ID="my-project"
./install-claude.sh

Copy the generated .mcp.json into your Claude Code project root, or merge the mcpServers entry into an existing .mcp.json.

Examples are also provided in examples/:

• examples/claude-mcp.json
• examples/codex-install.sh
• examples/AGENTS-snippet.md

Recommended Agent Instructions

Add this to your project CLAUDE.md, AGENTS.md, or equivalent:

Use the LightRAG MCP server as persistent project memory.

For non-trivial implementation/debugging/setup work:
- call `brain_begin` first
- use `senior_brief` for architecture/conventions/hazards
- use `brain_search` for prior fixes/failures when something is broken
- use `rag_index_repo` for whole-codebase indexing when needed
- after meaningful work, call `brain_remember`
- call `profile_upsert` when architecture/conventions/workflows/hazards change
- call `brain_finish` before final response

Tool Overview

RAG tools:

• rag_ask
• rag_get_context
• rag_query_data
• rag_status
• rag_clear
• rag_index_repo
• rag_list_documents
• rag_track_status
• rag_reprocess_failed
• rag_cancel_pipeline
• rag_webui

Memory tools:

• brain_remember
• brain_search
• brain_recent
• brain_reindex
• brain_begin
• brain_finish
• brain_gate_status

Senior project profile tools:

• profile_bootstrap
• profile_get
• profile_upsert
• profile_search
• senior_brief

Whole-Codebase Indexing

Use rag_index_repo:

{
  "root": "/path/to/project",
  "repo_id": "my-project",
  "dry_run": true,
  "limit": 1000
}

Then run without dry_run.

Defaults intentionally skip:

• .env, MCP config, local memory files
• .git, .venv, caches, logs, lockfiles
• node_modules, build/dist output
• LightRAG storage and generated data
• backup/temp/database/log files
• files larger than 256 KiB

Secret-looking values are redacted before indexing.

Multi-Repo Support

Pass a stable repo_id for each repository:

{
  "root": "/work/project-a",
  "repo_id": "project-a"
}

Documents are indexed as:

project-a:relative/path.py

This keeps references distinguishable across repositories.

Publish Your Own Copy

git init
git add .
git commit -m "Initial LightRAG Code Brain MCP"
gh repo create lightrag-code-brain-mcp --public --source=. --remote=origin --push

Before publishing, confirm .env is not staged:

git status --short

Troubleshooting

Check LightRAG:

docker compose ps
docker compose logs --tail=100 lightrag
curl http://127.0.0.1:9621/health

Common issues:

• 401: wrong LIGHTRAG_USERNAME / LIGHTRAG_PASSWORD
• embedding 404: provider does not expose /v1/embeddings
• NVIDIA input_type required: use nvidia/nv-embed-v1 or another compatible model
• no context after indexing: wait for pipeline completion, then check rag_status

Security Notes

• Do not commit .env.
• Keep LightRAG bound to 127.0.0.1 unless you know what you are doing.
• Rotate credentials if you accidentally indexed secrets before redaction.
• Review rag_index_repo dry-run output before first full indexing.