Embedding Providers

OpenClaw embedding providers convert text into numerical vectors that power semantic search and memory retrieval across your agent workspace. OpenClaw supports four provider categories: local models running via node-llama-cpp in GGUF format for fully offline and private operation, OpenAI's text-embedding-3-small for high-quality general-purpose embeddings, Google Gemini text-embedding-004 for cloud-based vector generation, and Voyage AI's voyage-code-3 for code-specific embeddings that outperform general models on technical content. You configure a provider by setting the provider name, model identifier, and API key in the memory.embeddings section of your OpenClaw configuration file. Setting the provider to auto lets OpenClaw detect available API keys and local models, then select the best option automatically. All computed embeddings are cached locally in a SQLite database holding up to 50,000 entries with least-recently-used eviction, eliminating redundant API calls and reducing latency for repeated content.

Introduction

OpenClaw uses text embeddings to power its semantic search and memory retrieval system. Embeddings convert text into numerical vectors that capture meaning, enabling the agent to find relevant memories and documents even when the exact words differ. OpenClaw supports multiple embedding providers, from local models that run on your machine to remote APIs from major AI companies.

Key Concepts

• Text Embeddings: Numerical vector representations of text that capture semantic meaning
• Local Embeddings: Models that run entirely on your machine using node-llama-cpp with GGUF format models
• Remote Embeddings: Cloud-based embedding APIs from OpenAI, Google Gemini, and Voyage AI
• Auto-Selection: OpenClaw's ability to automatically choose the best available embedding provider
• Embedding Cache: A local SQLite database that stores computed embeddings to avoid redundant API calls, holding up to 50,000 entries

Real World Context

A developer working on an airplane needs embeddings for memory search but has no internet access. Because they configured a local embedding provider using node-llama-cpp, the system works offline. Their colleague who uses OpenAI embeddings would be unable to search memories in the same situation. Choosing the right provider depends on your connectivity, privacy, and performance requirements.

Deep Dive

OpenClaw's embedding system supports four categories of providers:

Local Embeddings

Local embeddings run on your hardware with no network calls:

json
{
  "memory": {
    "embeddings": {
      "provider": "local",
      "model": "nomic-embed-text-v1.5.Q8_0.gguf",
      "dimensions": 768
    }
  }
}

This configuration uses a GGUF format model via node-llama-cpp. The model runs entirely on your CPU or GPU with zero data leaving your machine. Local embeddings are ideal for privacy-sensitive environments and offline use.

Remote Embeddings

Remote providers offer higher quality embeddings via API:

json
{
  "memory": {
    "embeddings": {
      "provider": "openai",
      "model": "text-embedding-3-small",
      "apiKey": "${OPENAI_API_KEY}"
    }
  }
}

This uses OpenAI's embedding API. Other supported remote providers include:

json
{
  "memory": {
    "embeddings": {
      "provider": "gemini",
      "model": "text-embedding-004",
      "apiKey": "${GEMINI_API_KEY}"
    }
  }
}

And Voyage AI for specialized code embeddings:

json
{
  "memory": {
    "embeddings": {
      "provider": "voyage",
      "model": "voyage-code-3",
      "apiKey": "${VOYAGE_API_KEY}"
    }
  }
}

Voyage's code-specific models often perform better for technical content than general-purpose embedding models.

How do OpenClaw embedding providers compare?

Local embeddings trade quality for privacy and zero network dependency. OpenAI provides the best general-purpose balance. Voyage outperforms all others on code-related content but costs more per token. Gemini integrates well with existing Google Cloud infrastructure.

Auto-Selection

If you do not configure a provider explicitly, OpenClaw uses auto-selection:

json
{
  "memory": {
    "embeddings": {
      "provider": "auto"
    }
  }
}

Auto-selection checks for available API keys and local models, then picks the best available option. The priority is: configured remote provider, then local model if available, then falls back to a lightweight built-in embedding.

Embedding Cache

To avoid recomputing embeddings for the same text, OpenClaw maintains a local SQLite cache:

markdown
Embedding Cache Details:
- Storage: SQLite database in the OpenClaw state directory
- Maximum entries: 50,000
- Eviction: Least-recently-used (LRU) when full
- Cache key: Hash of (text + model name + provider)
- Benefit: Eliminates redundant API calls for repeated content

The cache stores up to 50,000 embedding vectors. When the cache is full, the least recently used entries are evicted to make room. This means frequently accessed memories stay cached while rarely used ones are recomputed when needed.

Common Pitfalls

• Switching providers without re-embedding: If you change from OpenAI to Voyage embeddings, existing cached vectors are incompatible with new ones. The cache must be cleared and all content re-embedded.
• Ignoring the cache size limit: If your project has more than 50,000 unique text segments, some will be evicted and recomputed, increasing API costs and latency.
• Using remote providers for highly sensitive data: Remote embedding APIs send your text to third-party servers. Use local providers for confidential content.

Best Practices

• Use local embeddings for privacy: When working with sensitive codebases or in regulated environments, local GGUF models keep all data on your machine.
• Use Voyage for code-heavy workspaces: Voyage's code-specific models produce better search results for technical content than general-purpose models.
• Monitor cache hit rates: A low cache hit rate suggests your content is changing frequently or the cache is too small for your workload.

Summary

• OpenClaw supports local (node-llama-cpp/GGUF), OpenAI, Gemini, and Voyage embedding providers
• Local embeddings run offline with full privacy; remote providers offer higher quality at the cost of network dependency
• Auto-selection picks the best available provider based on configured API keys and local models
• The embedding cache (SQLite, 50,000 entries max) eliminates redundant computations using LRU eviction
• Choose your provider based on privacy requirements, connectivity, and content type (code vs prose)