Ollama Memory Embeddings

配置 OpenClaw 内存搜索以使用 Ollama 作为嵌入服务器 （OpenAI兼容/v1/embeddings）而不是内置的node-llama-cpp 本地 GGUF 加载。包括交互式模型选择和可选导入 将现有的 GGUF 本地嵌入到 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
bash ~/.openclaw/skills/ollama-memory-embeddings/install.sh
```

From this repository:

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

## Non-interactive usage

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

Bulletproof setup (install watchdog):

```bash
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

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

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

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

## Drift enforcement and auto-heal

Manually enforce desired state (safe to run repeatedly):

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

Check for drift only:

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

Run watchdog once (check + heal):

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

Install watchdog via launchd (macOS):

```bash
~/.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:

```bash
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.

---

## 中文说明

# Ollama Memory Embeddings

此技能将 OpenClaw 的内存搜索配置为使用 Ollama 作为**嵌入服务器**，通过其与 OpenAI 兼容的 `/v1/embeddings` 端点实现。

> **仅限嵌入。** 此技能不影响 chat/completions 路由——它只改变内存搜索嵌入向量的生成方式。

## 它做什么

- 将此技能安装到 `~/.openclaw/skills/ollama-memory-embeddings` 下
- 验证 Ollama 已安装且可访问
- 让用户选择一个嵌入模型：
  - `embeddinggemma`（默认——最接近 OpenClaw 内置模型）
  - `nomic-embed-text`（质量优秀，高效）
  - `all-minilm`（最小/最快）
  - `mxbai-embed-large`（质量最高，体积更大）
- 可选地通过 `ollama create` 将现有的本地嵌入 GGUF 导入 Ollama
  （当前可在已知缓存目录中检测 embeddinggemma、nomic-embed、all-minilm
  和 mxbai-embed GGUF）
- 规范化模型名称（自动处理 `:latest` 标签）
- 更新 OpenClaw 配置中的 `agents.defaults.memorySearch`（精准操作——只
  触碰此技能拥有的键）：
  - `provider = "openai"`
  - `model = <selected model>:latest`
  - `remote.baseUrl = "http://127.0.0.1:11434/v1/"`
  - `remote.apiKey = "ollama"`（客户端要求，Ollama 会忽略）
- 执行写入后的配置健全性检查（回读并校验 JSON）
- 可选地重启 OpenClaw 网关（会检测可用的
  重启方式：`openclaw gateway restart`、systemd、launchd）
- 安装期间可选的内存重新索引（`openclaw memory index --force --verbose`）
- 运行两步验证：
  1. 检查模型是否存在于 `ollama list` 中
  2. 调用 embeddings 端点并校验响应
- 添加一个幂等的漂移强制命令（`enforce.sh`）
- 添加可选的配置漂移自动修复看门狗（`watchdog.sh`）

## 安装

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

从本仓库安装：

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

## 非交互式用法

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

万无一失的安装（安装看门狗）：

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

> **注意：** 在非交互模式下，`--import-local-gguf auto` 被视为
> `no`（安全默认值）。使用 `--import-local-gguf yes` 显式选择启用。

选项：

- `--model <id>`：`embeddinggemma`、`nomic-embed-text`、`all-minilm`、`mxbai-embed-large` 之一
- `--import-local-gguf <auto|yes|no>`：默认 `no`（更安全的默认值；用 `yes` 选择启用）
- `--import-model-name <name>`：默认 `embeddinggemma-local`
- `--restart-gateway <yes|no>`：默认 `no`（仅在显式请求时重启）
- `--skip-restart`：`--restart-gateway no` 的已弃用别名
- `--openclaw-config <path>`：配置文件路径覆盖
- `--install-watchdog`：安装 launchd 漂移自动修复看门狗（macOS）
- `--watchdog-interval <sec>`：看门狗间隔（默认 60）
- `--reindex-memory <auto|yes|no>`：内存重建模式（默认 `auto`）
- `--dry-run`：打印计划的更改和命令；不做任何修改

## 验证

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

使用 `--verbose` 在失败时转储原始 API 响应：

```bash
~/.openclaw/skills/ollama-memory-embedd