Summary

Document (and ideally natively support) oMLX — an Apple Silicon-native MLX inference server with an OpenAI-compatible API — as an embedding provider for memorySearch. Currently undocumented; users migrating from Ollama have no clear path.

Problem to solve

oMLX (https://github.com/jundot/omlx) is an MLX-native inference server for Apple Silicon, gaining traction as an Ollama alternative on Mac. It serves embedding models like jina-embeddings-v5-text-small-retrieval-mlx via an OpenAI-compatible API on http://localhost:8000/v1.

Mac users migrating memorySearch from Ollama to oMLX hit several dead-ends:

1. They assume there should be an omlx provider type (there isn't).
2. They try provider: ollama + new baseUrl — fails because oMLX speaks the OpenAI protocol, not Ollama's /api/embeddings.
3. They try writing a FastAPI wrapper around the MLX model directly — unnecessary, oMLX already IS the HTTP server.
4. The docs (/concepts/memory-search, /reference/memory-config) don't mention oMLX or hint that provider: openai works for any OpenAI-compatible local endpoint.

I personally went through all three dead-ends before figuring out the working configuration. This is a real, repeatable friction point for Mac users.

Proposed solution

Option A — Documentation only (low effort, high impact): Add an "oMLX" subsection under embedding providers in the docs, alongside Ollama and OpenAI, including the verified configuration recipe below. Optionally add a short tutorial: "Migrating memorySearch from Ollama to oMLX on Apple Silicon."

Option B — First-class omlx provider adapter (more effort, cleaner UX): Add a native omlx provider that defaults baseUrl to http://127.0.0.1:8000/v1. Internally it can wrap the OpenAI adapter, but with friendlier defaults and oMLX-specific error messages (e.g. "oMLX not running — check menubar app").

Verified working configuration today (Option A baseline):

{
  "agents": {
    "defaults": {
      "memorySearch": {
        "enabled": true,
        "provider": "openai",
        "model": "jina-embeddings-v5-text-small-retrieval-mlx",
        "remote": {
          "baseUrl": "http://127.0.0.1:8000/v1",
          "apiKey": "<your-omlx-api-key>"
        }
      }
    }
  }
}

After switching, run openclaw memory index --force to re-embed in the new vector space.

I'm happy to start with Option A and send a docs PR.

Alternatives considered

• Keep using Ollama: not a real option for Mac users moving to MLX-native runtimes for better Apple Silicon performance.
• Self-host an OpenAI-compatible wrapper (FastAPI etc.): unnecessary overhead — oMLX already provides exactly this server out of the box.
• Wait for community to figure it out organically: that's what's been happening, with the result of users getting stuck on the three dead-ends listed above.

Impact

• Affected surface(s): memorySearch / embeddings provider configuration, docs (/concepts/memory-search, /reference/memory-config).
• Severity: Medium — memorySearch is broken (or perceived broken) until users discover the workaround.
• Frequency: Affects every Mac user migrating from Ollama to oMLX. As MLX-native runtimes gain adoption on Apple Silicon, this group is growing.
• Consequence: Hours of troubleshooting per user; some give up and downgrade to weaker embeddings or disable memorySearch entirely.

Evidence/examples

openclaw memory status --deep output after migrating to oMLX in my environment:

Provider: openai (requested: openai)
Model: jina-embeddings-v5-text-small-retrieval-mlx
Vector dims: 1024
Indexed: 150/150 files · 735 chunks
Dirty: no
Embeddings: ready
Vector: ready
FTS: ready
Batch: disabled (failures 0/2)

Tested environment:

Real semantic recall verified end-to-end. Screenshot attached below.

Additional information

References:

• oMLX project: https://github.com/jundot/omlx
• oMLX exposes OpenAI-compatible API on http://localhost:8000/v1 (per its README).

cc @jundot — oMLX maintainer, in case the oMLX side wants to cross-link.

I'm happy to send a documentation PR. If maintainers want to pursue Option B (native omlx adapter), I can also help scope out that work.