Deployment

Deployment

Memory-Spark is an OpenClaw plugin that requires a Spark backend for inference.

Prerequisites

Hardware

• GPU: NVIDIA GPU with 40GB+ VRAM (for Nemotron-120B)
• RAM: 64GB+ system memory
• Storage: 100GB+ SSD for LanceDB

Software

• Node.js 22+
• Docker (for Spark services)
• NVIDIA Container Toolkit
• CUDA 12.1+

Quick Start

1. Install OpenClaw

npm install -g openclaw
openclaw init

2. Install Memory-Spark Plugin

openclaw plugins install memory-spark

3. Configure Spark Backend

// ~/.openclaw/openclaw.json
{
  "plugins": {
    "memory-spark": {
      "spark": {
        "host": "10.99.1.1"
      }
    }
  }
}

4. Restart OpenClaw

openclaw restart

Spark Deployment

Docker Compose

# spark-compose.yml
version: '3.8'
services:
  embedding:
    image: nvcr.io/nvidia/nemotron:embed-8b
    ports:
      - "18091:18091"
    deploy:
      resources:
        reservations:
          devices:
            - capabilities: [gpu]
              device_ids: ['0']
  
  reranker:
    image: nvcr.io/nvidia/nemotron:rerank-1b
    ports:
      - "18096:18096"
    deploy:
      resources:
        reservations:
          devices:
            - capabilities: [gpu]
              device_ids: ['1']
  
  llm:
    image: nvcr.io/nvidia/nemotron:super-120b
    ports:
      - "18080:18080"
    deploy:
      resources:
        reservations:
          devices:
            - capabilities: [gpu]
              device_ids: ['2,3']

docker-compose -f spark-compose.yml up -d

Manual Deployment

Embedding Service

docker run -d \
  --gpus '"device=0"' \
  -p 18091:18091 \
  nvcr.io/nvidia/nemotron:embed-8b \
  --model llama-embed-nemotron-8b \
  --port 18091

Reranker Service

docker run -d \
  --gpus '"device=1"' \
  -p 18096:18096 \
  nvcr.io/nvidia/nemotron:rerank-1b \
  --model llama-nemotron-rerank-1b-v2 \
  --port 18096

LLM Service

docker run -d \
  --gpus '"device=2,3"' \
  -p 18080:18080 \
  nvcr.io/nvidia/nemotron:super-120b \
  --model Nemotron-Super-120B \
  --port 18080

Configuration

Agent Configuration

// ~/.openclaw/agents/main/AGENTS.md
# Agent Configuration

## Memory Pools
- `memory`: Conversation history (1.0x weight)
- `mistakes`: Error learnings (1.6x weight)
- `rules`: Shared rules (1.2x weight)

## Retrieval Defaults
- Top-k: 10
- Min score: 0.3
- MMR λ: 0.9

Pool Management

# Create pool
openclaw memory create-pool agent_mistakes --weight 1.6

# List pools
openclaw memory list-pools

# Ingest documents
openclaw memory ingest ./docs --pool shared_knowledge

Testing

Unit Tests

pnpm test
# 685 tests passing

Integration Tests

# Requires Spark backend
SKIP_INTEGRATION=0 pnpm run test:integration

E2E Validation

./scripts/validate-plugin.sh
# 7-phase validation

Monitoring

Health Check

curl http://localhost:18091/health  # Embedding
curl http://localhost:18096/health  # Reranker
curl http://localhost:18080/health  # LLM

Metrics

openclaw memory stats
# Pool sizes, latency, cache hit rate

Logs

openclaw logs --plugin memory-spark

Troubleshooting

Spark Connection Failed

Error: ECONNREFUSED 10.99.1.1:18091

Solution: Check Spark services are running, verify host IP in config.

Reranker Timeout

Error: Timeout awaiting reranker response (60000ms)

Solution: Increase rerank.timeoutMs or check GPU memory.

Vector Dimension Mismatch

Error: Embedding dimension mismatch (expected 4096, got 1024)

Solution: Ensure embed.model matches your embedder's output dimension.

Pool Not Found

Error: Pool 'agent_memory' not found

Solution: Create pool with openclaw memory create-pool agent_memory.

Performance Tuning

Latency Optimization

• Enable reranker gate (default: hard gate)
• Tune gate thresholds for your query distribution
• Increase embedding cache size
• Use smaller search.topK (20 → 10)

Recall Optimization

• Enable HyDE for ambiguous queries
• Increase search.topK (20 → 40)
• Tune MMR λ toward diversity (0.9 → 0.7)
• Enable multi-query expansion

GPU Memory Optimization

• Use 4-bit quantization for LLM
• Share GPUs between services
• Reduce rerank.batchSize (8 → 4)