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 no (safer default; opt in with yes)
• --import-model-name <name>: default embeddinggemma-local
• --restart-gateway <yes|no>: default no (restart only when explicitly requested)
• --skip-restart: deprecated alias for --restart-gateway no
• --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)
• --dry-run: print planned changes and commands; make no modifications

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.