LightBrain - ArcGrid Internal

Overview

LightBrain is the standard per-project cognitive infrastructure for any project running on the GRID zone. It provides an isolated graph database on ArcHelm and a local memory layer accessible from Claude Code via MCP.

LiteLLM and mcp-local-models are shared GRID infrastructure reachable at 127.0.0.1:4000 and 127.0.0.1:8020 without any per-project setup. LightBrain adds the project-specific layer on top.

01 / NEO4J

Graph Database

Isolated Neo4j 5 instance per project on ArcHelm K8s. Persists on a 5Gi PVC. Only reachable from the GRID zone (10.20.10.x).

02 / NEO4J-MCP

MCP Graph Interface

Docker container on your project machine. Exposes raw Neo4j CRUD via MCP over HTTP. Bridges your Claude session to ArcHelm.

03 / ATLAS-MEMORY

Cognitive Memory

Three-tier memory: episodic, semantic, procedural. Hybrid fulltext and vector retrieval with time-decay scoring and LLM consolidation.

ArcHelm

K8s control-plane at 10.20.10.29 (Arch Linux, GRID zone). All kubectl commands must be run by Charles - agents cannot SSH directly. Provide the exact command.

Step 1 - Neo4j on ArcHelm

1.1 - Namespace

Create namespace

kubectl create namespace <project-name>

1.2 - Secret

Create K8s Secret

kubectl create secret generic neo4j-secret   --from-literal=NEO4J_AUTH=neo4j/<your-password>   --namespace=<project-name>

Never commit this password. Store in project .env (gitignored) and 1Password.

1.3 - Manifest

Apply the manifest

Save as neo4j-archelm.yaml, fill in the four placeholders, then apply. Bolt NodePort pattern: 307NN. Browser NodePort: 308NN. See port registry for your slot.

kubectl apply -f neo4j-archelm.yaml

1.4 - Verify

Check pods and connectivity

kubectl get pods -n <project-name>
kubectl logs -l app=neo4j -n <project-name> --tail=30
nc -zv 10.20.10.29 <bolt-nodeport>

Step 2 - neo4j-mcp

MCP interface for raw graph CRUD. Runs as a Docker container on your project machine using the public mcp/neo4j-memory image.

Critical: .env placement

Name the file exactly .env and place it in the same directory as the docker-compose.yml, not the project root. A misplaced file causes ${NEO4J_PASSWORD} to expand empty and the Bolt handshake fails silently.

2.1 - Compose

docker-compose.yml

services:
  neo4j-mcp:
    image: mcp/neo4j-memory
    restart: unless-stopped
    ports:
      - "<neo4j-mcp-port>:8000"
    environment:
      NEO4J_URL: "bolt://10.20.10.29:<bolt-nodeport>"
      NEO4J_USERNAME: neo4j
      NEO4J_PASSWORD: ${NEO4J_PASSWORD}
      NEO4J_MCP_SERVER_HOST: "0.0.0.0"
      NEO4J_MCP_SERVER_PORT: "8000"
      NEO4J_MCP_SERVER_PATH: "/mcp/"
      NEO4J_TRANSPORT: http
    env_file:
      - .env

2.2 - Verify

Start and verify

docker compose up -d
curl -s http://localhost:<neo4j-mcp-port>/mcp/

Expected: HTTP 200 with MCP server metadata.

Step 3 - atlas-memory

Three-tier cognitive memory (episodic / semantic / procedural) with hybrid fulltext and vector retrieval, time-decay scoring, and LLM-driven consolidation. Exposes five MCP tools: recall_memory, write_memory, forget_memory, consolidate_memory, update_outcome.

Image source

The atlas-memory:latest image is pre-built by the ArcGrid team. Confirm availability: docker images atlas-memory. If not present, Charles will provide it via docker save / docker load.

3.1 - Compose

docker-compose.yml

services:
  atlas-memory:
    image: atlas-memory:latest
    restart: unless-stopped
    ports:
      - "<atlas-memory-port>:<atlas-memory-port>"
    env_file:
      - .env
    environment:
      NEO4J_URI: "bolt://10.20.10.29:<bolt-nodeport>"
      LITELLM_BASE: "http://172.17.0.1:4000"
      LITELLM_API_KEY: ${LITELLM_API_KEY:-sk-local-master}
      CONSOLIDATION_MODEL: "analysis"
      MCP_HOST: "0.0.0.0"
      MCP_PORT: "<atlas-memory-port>"
    extra_hosts:
      - "host-gateway:host-gateway"

3.2 - Verify

Start and verify

docker compose up -d
docker logs atlas-memory-<project-name> --tail=30

On first start the BAAI/bge-small-en-v1.5 ONNX model (~130 MB) downloads and three vector indexes are created. Allow 60-90 seconds. Expected healthy output:

Neo4j connected
Fulltext index ready
Vector indexes ready
MCP server listening on 0.0.0.0:<atlas-memory-port>

Step 4 - brave-mcp

Per-project web search. Wraps mcp/brave-search over SSE via supergateway. Each project runs its own instance.

4.1 - Build

Build the image

FROM mcp/brave-search:latest
USER root
RUN npm install -g supergateway
EXPOSE 8010
ENTRYPOINT ["supergateway", "--stdio", "node /app/dist/index.js", "--port", "8010"]

docker build -t brave-mcp:latest brave-mcp/

4.2 - Verify

Start and verify

docker compose up -d
curl -s --max-time 3 http://127.0.0.1:<brave-mcp-port>/sse

Expected: SSE stream opens (curl hangs or returns a stream header).

.mcp.json registration

Add all four servers to your project's .mcp.json. Restart Claude Code after editing.

{
  "mcpServers": {
    "neo4j-memory": {
      "type": "http",
      "url": "http://127.0.0.1:<neo4j-mcp-port>/mcp/"
    },
    "atlas-memory": {
      "type": "sse",
      "url": "http://127.0.0.1:<atlas-memory-port>/sse"
    },
    "local-models": {
      "type": "sse",
      "url": "http://127.0.0.1:8020/sse"
    },
    "brave-search": {
      "type": "sse",
      "url": "http://127.0.0.1:<brave-mcp-port>/sse"
    }
  }
}

No auth headers

Do not add headers or Authorization fields. Claude Code refuses credentials to non-HTTPS hosts. Use 127.0.0.1 not 172.17.0.1 from WSL2. The entries above are complete as-is.

Port registry

ArcHelm NodePorts are global and must be unique across all projects.

Slot	Project	Machine	Bolt NodePort	Browser NodePort	neo4j-mcp	atlas-memory	brave-mcp
-	the-grid	brubcha-wsl	`7687` local	`7474` local	`8000`	`8030`	`8010`
01	packly	brubcha-wsl	`30701`	`30801`	`8005`	`8031`	`8011`
02	funding-forge	brubcha-wsl	`30702`	`30802`	`8002`	`8032`	`8012`
03	adage1	brubcha-wsl	`30703`	`30803`	`8003`	`8033`	`8013`
04	arc-grid	?	`30704`	`30804`	`8004`	`8034`	`8014`
05	wedgerock	wedgerock-machine	`30705`	`30805`	`8006`	`8035`	`8015`
06	(next)		`30706`	`30806`	`8007`	`8036`	`8016`

Troubleshooting

Refusing to send credentials to untrusted host

Use 127.0.0.1 in all .mcp.json URLs. Remove any headers or Authorization block. Restart Claude Code after fixing.

neo4j-mcp returns empty or connection refused

Check docker ps. Verify .env is in the same directory as docker-compose.yml, not the project root. A misplaced file causes the Bolt handshake to fail silently.

atlas-memory healthcheck fails on first start

Normal - embedding model download takes 60-90 seconds. Watch logs and wait for MCP server listening:

docker logs atlas-memory-<project-name> --follow

Rotating credentials

kubectl rollout restart deployment/neo4j -n <project-name>