openclaw-workspace/skills/ollama-memory-embeddings/SKILL.md

slug, display_name, displayName, name, description

slug	display_name	displayName	name	description
ollama-memory-embeddings	Ollama Memory Embeddings	Ollama Memory Embeddings	ollama-memory-embeddings	Configure OpenClaw memory search to use Ollama as the embeddings server (OpenAI-compatible /v1/embeddings) instead of the built-in node-llama-cpp local GGUF loading. Includes interactive model selection and optional import of an existing local embedding GGUF into Ollama.

Ollama Memory Embeddings

This skill configures OpenClaw memory search to use Ollama as the embeddings server via its OpenAI-compatible /v1/embeddings endpoint.

Embeddings only. This skill does not affect chat/completions routing — it only changes how memory-search embedding vectors are generated.

What it does

• Installs this skill under ~/.openclaw/skills/ollama-memory-embeddings
• Verifies Ollama is installed and reachable
• Lets the user choose an embedding model:
  • embeddinggemma (default — closest to OpenClaw built-in)
  • nomic-embed-text (strong quality, efficient)
  • all-minilm (smallest/fastest)
  • mxbai-embed-large (highest quality, larger)
• Optionally imports an existing local embedding GGUF into Ollama via ollama create (currently detects embeddinggemma, nomic-embed, all-minilm, and mxbai-embed GGUFs in known cache directories)
• Normalizes model names (handles :latest tag automatically)
• Updates agents.defaults.memorySearch in OpenClaw config (surgical — only touches keys this skill owns):
  • provider = "openai"
  • model = <selected model>:latest
  • remote.baseUrl = "http://127.0.0.1:11434/v1/"
  • remote.apiKey = "ollama" (required by client, ignored by Ollama)
• Performs a post-write config sanity check (reads back and validates JSON)
• Optionally restarts the OpenClaw gateway (with detection of available restart methods: openclaw gateway restart, systemd, launchd)
• Optional memory reindex during install (openclaw memory index --force --verbose)
• Runs a two-step verification:
  1. Checks model exists in ollama list
  2. Calls the embeddings endpoint and validates the response
• Adds an idempotent drift-enforcement command (enforce.sh)
• Adds optional config drift auto-healing watchdog (watchdog.sh)

Install

bash ~/.openclaw/skills/ollama-memory-embeddings/install.sh

From this repository:

bash skills/ollama-memory-embeddings/install.sh

Non-interactive usage

bash ~/.openclaw/skills/ollama-memory-embeddings/install.sh \
  --non-interactive \
  --model embeddinggemma \
  --reindex-memory auto

Bulletproof setup (install watchdog):

bash ~/.openclaw/skills/ollama-memory-embeddings/install.sh \
  --non-interactive \
  --model embeddinggemma \
  --reindex-memory auto \
  --install-watchdog \
  --watchdog-interval 60

Note: In non-interactive mode, --import-local-gguf auto is treated as no (safe default). Use --import-local-gguf yes to explicitly opt in.

Options:

• --model <id>: one of embeddinggemma, nomic-embed-text, all-minilm, mxbai-embed-large
• --import-local-gguf <auto|yes|no>: default auto (interactive: prompts; non-interactive: no)
• --import-model-name <name>: default embeddinggemma-local
• --skip-restart: do not restart gateway
• --openclaw-config <path>: config file path override
• --install-watchdog: install launchd drift auto-heal watchdog (macOS)
• --watchdog-interval <sec>: watchdog interval (default 60)
• --reindex-memory <auto|yes|no>: memory rebuild mode (default auto)

Verify

~/.openclaw/skills/ollama-memory-embeddings/verify.sh

Use --verbose to dump raw API response on failure:

~/.openclaw/skills/ollama-memory-embeddings/verify.sh --verbose

Drift enforcement and auto-heal

Manually enforce desired state (safe to run repeatedly):

~/.openclaw/skills/ollama-memory-embeddings/enforce.sh \
  --model embeddinggemma \
  --openclaw-config ~/.openclaw/openclaw.json

Check for drift only:

~/.openclaw/skills/ollama-memory-embeddings/enforce.sh \
  --check-only \
  --model embeddinggemma

Run watchdog once (check + heal):

~/.openclaw/skills/ollama-memory-embeddings/watchdog.sh \
  --once \
  --model embeddinggemma

Install watchdog via launchd (macOS):

~/.openclaw/skills/ollama-memory-embeddings/watchdog.sh \
  --install-launchd \
  --model embeddinggemma \
  --interval-sec 60

GGUF detection scope

The installer searches for embedding GGUFs matching these patterns in known cache directories (~/.node-llama-cpp/models, ~/.cache/node-llama-cpp/models, ~/.cache/openclaw/models):

• *embeddinggemma*.gguf
• *nomic-embed*.gguf
• *all-minilm*.gguf
• *mxbai-embed*.gguf

Other embedding GGUFs are not auto-detected. You can always import manually:

ollama create my-model -f /path/to/Modelfile

Notes

• This does not modify OpenClaw package code. It only updates user config.
• A timestamped backup of config is written before changes.
• If no local GGUF exists, install proceeds by pulling the selected model from Ollama.
• Model names are normalized with :latest tag for consistent Ollama interaction.
• If embedding model changes, rebuild/re-embed existing memory vectors to avoid retrieval mismatch across incompatible vector spaces.
• With --reindex-memory auto, installer reindexes only when the effective embedding fingerprint changed (provider, model, baseUrl, apiKey presence).
• Drift checks require a non-empty apiKey but do not require a literal "ollama" value.
• Config backups are created only when a write is needed.
• Legacy schema fallback is supported: if agents.defaults.memorySearch is absent, the enforcer reads known legacy paths and mirrors writes to preserve compatibility.