Skip to content

docs: Document oMLX (Apple Silicon MLX) as memorySearch embedding provider#74761

Open
mppyes-ai wants to merge 5 commits into
openclaw:mainfrom
mppyes-ai:main
Open

docs: Document oMLX (Apple Silicon MLX) as memorySearch embedding provider#74761
mppyes-ai wants to merge 5 commits into
openclaw:mainfrom
mppyes-ai:main

Conversation

@mppyes-ai

@mppyes-ai mppyes-ai commented Apr 30, 2026

Copy link
Copy Markdown

Summary

Resolves the documentation gap identified in #74732. Adds focused recipes
for using oMLX (Apple Silicon MLX inference server) as a memorySearch
embedding provider via the existing OpenAI-compatible adapter.

Changes

  • docs/concepts/memory-search.md: New "Using oMLX" subsection under
    Quick start, plus an oMLX row in the Supported providers table.
  • docs/reference/memory-config.md: New oMLX example under Remote
    endpoint config, with a warning against the common provider: "ollama"
    mistake.
  • docs/providers/openai.md: New "Local OpenAI-compatible servers"
    subsection under Memory embeddings, surfacing oMLX as a notable
    Apple Silicon use case.

What this addresses

Per the Codex review on #74732, this is the narrow docs-only fix:

Add a focused docs recipe for oMLX that uses the existing OpenAI-compatible
embedding path, warns users not to configure oMLX as Ollama, includes the
local /v1 base URL and model example from the report, and tells users to
reindex after changing embedding models or vector spaces.

All three points are covered. No core behavior change; no new provider
adapter introduced. The first-class omlx adapter discussion (Option B in
#74732) remains separate and is not part of this PR.

Verification

The configuration shipped in this PR was verified end-to-end on:

Component Version
OpenClaw 2026.4.26
oMLX v1.3.6
Embedding model jina-embeddings-v5-text-small-retrieval-mlx (1024 dims)
OS macOS, Apple Silicon

openclaw memory status --deep after migration:

  • Provider: openai (requested: openai)
  • Model: jina-embeddings-v5-text-small-retrieval-mlx
  • Vector dims: 1024
  • Indexed: 150/150 files · 946 chunks
  • Batch failures: 0/2

Related

Closes #74732 (docs portion).

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

@openclaw-barnacle openclaw-barnacle Bot added docs Improvements or additions to documentation size: XS labels Apr 30, 2026
@clawsweeper

clawsweeper Bot commented Apr 30, 2026 •
edited
Loading

Copy link
Copy Markdown
Contributor

Codex review: needs changes before merge. Reviewed June 7, 2026, 1:15 AM ET / 05:15 UTC.

Summary
The branch adds oMLX memorySearch documentation across the memory-search concept page, memory config reference, and OpenAI provider docs using remote OpenAI-shaped embedding examples.

PR surface: Docs +103. Total +103 across 3 files.

Reproducibility: yes. for the review finding: current source and docs show openai-compatible is the provider for generic /v1/embeddings, while the PR head shows oMLX snippets using openai. No runtime reproduction was needed for this docs-only mismatch.

Review metrics: 1 noteworthy metric.

  • User-copyable provider examples: 3 added config snippets plus 1 provider-table row. These examples define auth/provider routing, so an outdated provider id can mislead every reader who copies the oMLX recipe.

Merge readiness
Overall: 🧂 unranked krab
Proof: 🌊 off-meta tidepool
Patch quality: 🧂 unranked krab
Result: blocked by patch quality or review findings.

Overall follows the weaker of proof and patch quality, so missing proof can cap an otherwise strong patch.

Rank-up moves:

  • Change all oMLX memorySearch examples and prose to provider: "openai-compatible" with the oMLX remote.baseUrl.
  • Refresh the branch against current main and run the focused docs checks.

Risk before merge

  • [P1] Merging as-is would publish copy-pasteable oMLX config that uses memorySearch.provider: "openai" even though current main directs generic local /v1/embeddings servers to openai-compatible, which can send users down the wrong auth/provider path.
  • [P1] The PR head predates current main's generic OpenAI-compatible docs, so the branch should be refreshed while preserving the current provider-boundary wording.

Maintainer options:

  1. Repair provider id before merge (recommended)
    Update every new oMLX memorySearch example and provider note to use openai-compatible, then refresh against current main's remote endpoint section.
  2. Accept legacy OpenAI route explicitly
    If maintainers intentionally want to keep documenting openai, add a clear note explaining global OpenAI credential inheritance and why it is preferred over the current dedicated provider.
Copy recommended automerge instruction 
@clawsweeper automerge

Special instructions:
Update the oMLX docs in docs/concepts/memory-search.md, docs/reference/memory-config.md, and docs/providers/openai.md to use memorySearch.provider: "openai-compatible" for local /v1/embeddings servers, preserve current-main generic OpenAI-compatible guidance, avoid suggesting the OpenAI auth-owned provider for oMLX, and run docs:list, docs markdown/link checks, and git diff --check.

Next step before merge

  • [P2] A narrow automated docs repair can preserve the oMLX contribution while replacing the outdated provider id and refreshing against current main.

Security
Needs attention: The docs-only diff has no supply-chain change, but it does introduce auth-provider guidance that could misroute local embedding traffic through the OpenAI provider boundary.

Review findings

  • [P1] Use the generic embedding provider in oMLX docs — docs/concepts/memory-search.md:60
Review details

Best possible solution:

Keep the oMLX-specific docs, but rewrite the snippets, table row, and prose to use provider: "openai-compatible" with remote.baseUrl and preserve current main's generic endpoint guidance.

Do we have a high-confidence way to reproduce the issue?

Yes for the review finding: current source and docs show openai-compatible is the provider for generic /v1/embeddings, while the PR head shows oMLX snippets using openai. No runtime reproduction was needed for this docs-only mismatch.

Is this the best way to solve the issue?

No. The docs-only direction is useful, but the current patch is not the best solution until it aligns oMLX with the dedicated openai-compatible provider rather than the OpenAI auth-owned route.

Full review comments:

  • [P1] Use the generic embedding provider in oMLX docs — docs/concepts/memory-search.md:60
    Current main documents provider: "openai-compatible" for generic local /v1/embeddings servers so they do not inherit global OpenAI credentials, and the source registers that provider as the core generic embedding route. This PR repeats provider: "openai" in the new oMLX examples and prose, which would publish the old auth-owned route for a local server. Please change the oMLX examples and table/prose to provider: "openai-compatible" while keeping the oMLX remote.baseUrl.
    Confidence: 0.93

Overall correctness: patch is incorrect
Overall confidence: 0.91

AGENTS.md: found and applied where relevant.

Codex review notes: model gpt-5.5, reasoning high; reviewed against 7e7ea0fed17c.

Label changes

Label justifications:

  • P3: This is a docs-only PR with a narrow repair path, not a shipped runtime regression.
  • merge-risk: 🚨 auth-provider: The added docs route local oMLX embeddings through the OpenAI auth-owned provider instead of current main's openai-compatible provider.
  • rating: 🧂 unranked krab: Overall readiness is 🧂 unranked krab; proof is 🌊 off-meta tidepool and patch quality is 🧂 unranked krab.
  • status: ⏳ waiting on author: ClawSweeper has contributor-facing work open and is waiting for author action. Not applicable: Real behavior proof is not required because this PR only changes files under docs/.
Evidence reviewed

PR surface:

Docs +103. Total +103 across 3 files.

View PR surface stats
Area Files Added Removed Net
Source 0 0 0 0
Tests 0 0 0 0
Docs 3 113 10 +103
Config 0 0 0 0
Generated 0 0 0 0
Other 0 0 0 0
Total 3 113 10 +103

Security concerns:

  • [medium] Local embedding docs use the OpenAI auth-owned provider — docs/concepts/memory-search.md:60
    The new oMLX snippets use provider: "openai" even though current main provides openai-compatible specifically for generic local /v1/embeddings servers that should not inherit OpenAI credentials or defaults.
    Confidence: 0.86

Acceptance criteria:

  • [P1] pnpm docs:list.
  • [P1] pnpm docs:check-mdx.
  • [P1] pnpm docs:check-links.
  • [P1] git diff --check.

What I checked:

Likely related people:

  • vincentkoc: Blame on the current openai-compatible provider source and remote endpoint docs points to their recent commit that defines the provider contract this PR must follow. (role: recent area contributor; confidence: high; commits: 61bb7d5523b8, 7e7ea0fed17c; files: src/plugins/openai-compatible-embedding-provider.ts, docs/reference/memory-config.md, docs/concepts/memory-search.md)
  • yaanfpv: Related discussion and closed PR context centered the openai-compatible local embedding provider design that now affects this docs repair. (role: adjacent proposal author; confidence: medium; files: src/plugins/openai-compatible-embedding-provider.ts, docs/reference/memory-config.md)
What the crustacean ranks mean
  • 🦀 challenger crab: rare, exceptional readiness with strong proof, clean implementation, and convincing validation.
  • 🦞 diamond lobster: very strong readiness with only minor maintainer review expected.
  • 🐚 platinum hermit: good normal PR, likely mergeable with ordinary maintainer review.
  • 🦐 gold shrimp: useful signal, but proof or patch confidence is still limited.
  • 🦪 silver shellfish: thin signal; proof, validation, or implementation needs work.
  • 🧂 unranked krab: not merge-ready because proof is missing/unusable or there are serious correctness or safety concerns.
  • 🌊 off-meta tidepool: rating does not apply to this item.

Shiny media proof means a screenshot, video, or linked artifact directly shows the changed behavior. Runtime, network, CSP, and security claims still need visible diagnostics.

How this review workflow works
  • ClawSweeper keeps one durable marker-backed review comment per issue or PR.
  • Re-runs edit this comment so the latest verdict, findings, and automation markers stay together instead of adding duplicate bot comments.
  • A fresh review can be triggered by eligible @clawsweeper re-review comments, exact-item GitHub events, scheduled/background review runs, or manual workflow dispatch.
  • PR/issue authors and users with repository write access can comment @clawsweeper re-review or @clawsweeper re-run on an open PR or issue to request a fresh review only.
  • Maintainers can also comment @clawsweeper review to request a fresh review only.
  • Fresh-review commands do not start repair, autofix, rebase, CI repair, or automerge.
  • Maintainer-only repair and merge flows require explicit commands such as @clawsweeper autofix, @clawsweeper automerge, @clawsweeper fix ci, or @clawsweeper address review.
  • Maintainers can comment @clawsweeper explain to ask for more context, or @clawsweeper stop to stop active automation.

mppyes-ai and others added 2 commits April 30, 2026 10:57
@mppyes-ai
docs(memory-search): fix table alignment in providers list
08f61b4 
Resolves check-docs failure on PR openclaw#74761 — aligns column widths in the Supported providers table to satisfy cxfmt.
@steipete
docs: fix memory search table spacing
38877ca
@mppyes-ai mppyes-ai mentioned this pull request Apr 30, 2026
Open
This was referenced May 11, 2026
Closed
Closed
@clawsweeper clawsweeper Bot added the proof: sufficient ClawSweeper judged the real behavior proof convincing. label May 13, 2026
@openclaw-barnacle openclaw-barnacle Bot added triage: needs-real-behavior-proof Candidate: external PR needs after-fix proof from a real setup. and removed proof: sufficient ClawSweeper judged the real behavior proof convincing. labels May 13, 2026
@clawsweeper clawsweeper Bot added the proof: sufficient ClawSweeper judged the real behavior proof convincing. label May 14, 2026
@openclaw-barnacle openclaw-barnacle Bot removed the proof: sufficient ClawSweeper judged the real behavior proof convincing. label May 14, 2026
@clawsweeper clawsweeper Bot added the proof: sufficient ClawSweeper judged the real behavior proof convincing. label May 14, 2026
@openclaw-barnacle openclaw-barnacle Bot removed the proof: sufficient ClawSweeper judged the real behavior proof convincing. label May 14, 2026
@clawsweeper clawsweeper Bot added the proof: sufficient ClawSweeper judged the real behavior proof convincing. label May 14, 2026
@openclaw-barnacle openclaw-barnacle Bot removed the proof: sufficient ClawSweeper judged the real behavior proof convincing. label May 14, 2026
@clawsweeper clawsweeper Bot added the proof: sufficient ClawSweeper judged the real behavior proof convincing. label May 14, 2026
@openclaw-barnacle openclaw-barnacle Bot removed the proof: sufficient ClawSweeper judged the real behavior proof convincing. label May 14, 2026
@openclaw-barnacle

openclaw-barnacle Bot commented May 30, 2026

Copy link
Copy Markdown

This pull request has been automatically marked as stale due to inactivity.
Please add updates or it will be closed.

@openclaw-barnacle openclaw-barnacle Bot added the stale Marked as stale due to inactivity label May 30, 2026
@clawsweeper clawsweeper Bot added the rating: 🌊 off-meta tidepool PR readiness rating does not apply to this item. label May 30, 2026
@barnacle-openclaw barnacle-openclaw Bot removed the stale Marked as stale due to inactivity label May 30, 2026
@osolmaz osolmaz self-assigned this Jun 3, 2026
@openclaw-barnacle

openclaw-barnacle Bot commented Jun 4, 2026

Copy link
Copy Markdown

This assigned pull request has been automatically marked as stale after being open for 27 days.
Please add updates or it will be closed.

@openclaw-barnacle openclaw-barnacle Bot added the stale Marked as stale due to inactivity label Jun 4, 2026
@clawsweeper clawsweeper Bot removed the rating: 🌊 off-meta tidepool PR readiness rating does not apply to this item. label Jun 4, 2026
@clawsweeper clawsweeper Bot added rating: 🦐 gold shrimp Decent PR readiness signal, but merge confidence is limited. status: ⏳ waiting on author ClawSweeper has contributor-facing work open and is waiting for author action. P3 Low-priority cleanup, docs, polish, ergonomics, or speculative work. merge-risk: 🚨 auth-provider 🚨 May break OAuth, tokens, provider routing, model choice, or credentials. labels Jun 4, 2026
@openclaw-barnacle openclaw-barnacle Bot removed the stale Marked as stale due to inactivity label Jun 5, 2026
@openclaw-barnacle

openclaw-barnacle Bot commented Jun 5, 2026

Copy link
Copy Markdown

This assigned pull request has been automatically marked as stale after being open for 27 days.
Please add updates or it will be closed.

@openclaw-barnacle openclaw-barnacle Bot added the stale Marked as stale due to inactivity label Jun 5, 2026
@clawsweeper clawsweeper Bot added rating: 🌊 off-meta tidepool PR readiness rating does not apply to this item. and removed rating: 🦐 gold shrimp Decent PR readiness signal, but merge confidence is limited. status: ⏳ waiting on author ClawSweeper has contributor-facing work open and is waiting for author action. labels Jun 5, 2026
@openclaw-barnacle openclaw-barnacle Bot removed the stale Marked as stale due to inactivity label Jun 6, 2026
@openclaw-barnacle

openclaw-barnacle Bot commented Jun 6, 2026

Copy link
Copy Markdown

This assigned pull request has been automatically marked as stale after being open for 27 days.
Please add updates or it will be closed.

@openclaw-barnacle openclaw-barnacle Bot added the stale Marked as stale due to inactivity label Jun 6, 2026
@clawsweeper clawsweeper Bot added rating: 🧂 unranked krab Not merge-ready due to missing proof or serious correctness/safety concerns. status: ⏳ waiting on author ClawSweeper has contributor-facing work open and is waiting for author action. and removed rating: 🌊 off-meta tidepool PR readiness rating does not apply to this item. labels Jun 6, 2026
@openclaw-barnacle openclaw-barnacle Bot removed the stale Marked as stale due to inactivity label Jun 7, 2026
@openclaw-barnacle

openclaw-barnacle Bot commented Jun 7, 2026

Copy link
Copy Markdown

This assigned pull request has been automatically marked as stale after being open for 27 days.
Please add updates or it will be closed.

@openclaw-barnacle openclaw-barnacle Bot added the stale Marked as stale due to inactivity label Jun 7, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

@osolmaz osolmaz

Labels

docs Improvements or additions to documentation merge-risk: 🚨 auth-provider 🚨 May break OAuth, tokens, provider routing, model choice, or credentials. P3 Low-priority cleanup, docs, polish, ergonomics, or speculative work. rating: 🧂 unranked krab Not merge-ready due to missing proof or serious correctness/safety concerns. size: XS stale Marked as stale due to inactivity status: ⏳ waiting on author ClawSweeper has contributor-facing work open and is waiting for author action. triage: needs-real-behavior-proof Candidate: external PR needs after-fix proof from a real setup.

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

docs+feat: Document oMLX (Apple Silicon MLX) as memorySearch embedding provider

3 participants

@mppyes-ai @osolmaz @steipete