Skip to content

docs(memory): add QMD CPU-only VPS guidance#100797

Open
lin-hongkuan wants to merge 3 commits into
openclaw:mainfrom
lin-hongkuan:lhk/docs-qmd-cpu-vps-90746
Open

docs(memory): add QMD CPU-only VPS guidance#100797
lin-hongkuan wants to merge 3 commits into
openclaw:mainfrom
lin-hongkuan:lhk/docs-qmd-cpu-vps-90746

Conversation

@lin-hongkuan

@lin-hongkuan lin-hongkuan commented Jul 6, 2026

Copy link
Copy Markdown
Contributor

Summary

  • documents a safe QMD starting configuration for small CPU-only VPS deployments
  • explains why BM25-only searchMode: "search" avoids embedding maintenance and vector readiness probes
  • cross-links the memory config reference to the new CPU-only VPS rollout guidance

Issue/Motivation

Fixes #90746.

The issue asks whether QMD is practical on CPU-only VPS hosts after reports of 4-vCPU machines becoming saturated during local embedding work. Current docs describe QMD setup and tuning knobs, but do not tell operators which mode is safe to start with or how to roll out semantic search without making the gateway unresponsive.

Changes

  • Added docs/concepts/memory-qmd.md guidance for CPU-only VPS deployments.
  • Added a BM25-first sample config with startup: "off", onBoot: false, and a longer embedInterval for semantic rollout.
  • Updated docs/reference/memory-config.md to point searchMode readers to the deployment guidance.

Testing

  • pnpm docs:list
  • pnpm docs:check-mdx — passed, 694 files
  • pnpm docs:check-links — passed, checked_internal_links=5727, broken_links=0
  • git diff --check
  • diff secret scan — no high-confidence patterns in diff

What Problem This Solves

Small VPS users can now see the practical CPU tradeoff before enabling QMD semantic modes. The docs recommend the already-supported BM25-only mode for small CPU-only hosts and describe a cautious path for trying query/vsearch with reduced startup and embedding pressure.

Evidence

  • Confirmed issue Document practical requirements for QMD memory backend on CPU-only VPS deployments #90746 is open and unassigned before publishing.
  • Searched open PRs by 90746 and "CPU-only" QMD VPS; no PR was found that covers this deployment guidance. Existing QMD PRs found by broad search target embed timeout/vector timeout behavior, not CPU-only VPS documentation.
  • pnpm docs:list
  • pnpm docs:check-mdx passed: Docs MDX check passed (694 files, 11965ms).
  • pnpm docs:check-links passed: checked_internal_links=5727, broken_links=0.
  • git diff --check passed.
  • Diff secret scan found no high-confidence secret patterns.

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

clawsweeper Bot commented Jul 6, 2026 •
edited
Loading

Copy link
Copy Markdown
Contributor

Codex review: needs maintainer review before merge. Reviewed July 8, 2026, 1:47 AM ET / 05:47 UTC.

Summary
The branch adds CPU-only VPS rollout guidance to the QMD memory docs, links the memory config reference to it, and refreshes the generated docs map.

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

Reproducibility: not applicable. This PR documents an operational guidance gap rather than a runtime bug. Current main source and the linked upstream QMD issue establish the docs context without needing a local failure reproduction.

Review metrics: none identified.

Stored data model
Persistent data-model change detected: vector/embedding metadata: docs/concepts/memory-qmd.md, vector/embedding metadata: docs/reference/memory-config.md. Confirm migration or upgrade compatibility proof before merge.

Root-cause cluster
Relationship: fixed_by_candidate
Canonical: #90746
Summary: This PR is the candidate docs fix for the linked CPU-only QMD deployment-guidance issue; the open embed-timeout PR is adjacent runtime work, not the canonical docs fix.

Members:

Proposal only: this assessment does not dispatch repair, suppress jobs, mutate sibling items, close, or merge anything.

Merge readiness
Overall: 🐚 platinum hermit
Proof: 🌊 off-meta tidepool
Patch quality: 🐚 platinum hermit
Result: ready for maintainer review.

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

Rank-up moves:

  • none.

Risk before merge

  • [P1] Exact semantic QMD sizing still depends on model choice, corpus size, CPU class, and embed cadence, so maintainers should decide whether this conservative guidance is enough or whether stronger CPU minimums/runtime warnings belong in a separate change.

Maintainer options:

  1. Decide the mitigation before merge
    Merge the conservative docs guidance if the QMD owner accepts it, and keep exact CPU minimums, runtime warnings, or default changes as separate policy/runtime work.
  2. Pause or close
    Do not merge this PR until maintainers decide whether the risk is worth taking.

Next step before merge

  • [P2] A maintainer should decide whether the conservative docs guidance is sufficient for the linked QMD CPU-only VPS issue; there is no concrete automated repair to queue.

Maintainer decision needed

  • Question: Should OpenClaw merge this conservative docs-only QMD CPU-only VPS guidance now, while deferring exact CPU minimums and runtime/default-warning policy to separate work?
  • Rationale: The diff is technically consistent with current code and upstream QMD docs, but the linked issue asks for CPU-sizing and recommendation policy that should be owned by the QMD area before the PR closes the issue.
  • Likely owner: vignesh07 — CONTRIBUTING.md lists vignesh07 for Memory/QMD, and prior QMD default/search-mode commits are directly related to this guidance.
  • Options:
    • Merge conservative guidance (recommended): Accept the BM25-first rollout guidance as the documentation answer and leave exact sizing/runtime warning policy to future QMD work.
    • Request stronger sizing evidence: Ask for maintainer-approved performance numbers or clearer CPU minimum language before this PR closes the linked issue.
    • Keep docs separate from policy: Merge only if the PR explicitly states that CPU minimums and runtime warnings remain unresolved follow-up decisions.

Security
Cleared: The diff only changes docs markdown and the generated docs map, with no dependency, workflow, lockfile, secret, or code-execution surface changes.

Review details

Best possible solution:

Merge the conservative docs guidance if the QMD owner accepts it, and keep exact CPU minimums, runtime warnings, or default changes as separate policy/runtime work.

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

Not applicable: this PR documents an operational guidance gap rather than a runtime bug. Current main source and the linked upstream QMD issue establish the docs context without needing a local failure reproduction.

Is this the best way to solve the issue?

Yes for the docs-only scope: adding conservative guidance to the QMD concept page and cross-linking from the config reference is the narrow maintainable fix. Exact CPU minimums or runtime warnings should remain separate unless the QMD owner chooses that policy here.

AGENTS.md: found and applied where relevant.

Codex review notes: model internal, reasoning high; reviewed against 5a5b4c5b105f.

Label changes

Label justifications:

  • P3: This is a low-risk documentation improvement for an existing memory backend with no runtime or configuration-surface change.
  • rating: 🐚 platinum hermit: Overall readiness is 🐚 platinum hermit; proof is 🌊 off-meta tidepool and patch quality is 🐚 platinum hermit.
  • status: 👀 ready for maintainer look: ClawSweeper has no concrete contributor-facing blocker left for this PR. Not applicable: Real behavior proof is not required because this PR only changes files under docs/.
Evidence reviewed

PR surface:

Docs +40. Total +40 across 3 files.

View PR surface stats
Area Files Added Removed Net
Source 0 0 0 0
Tests 0 0 0 0
Docs 3 41 1 +40
Config 0 0 0 0
Generated 0 0 0 0
Other 0 0 0 0
Total 3 41 1 +40

What I checked:

  • Repository policy read: Root AGENTS.md and docs/AGENTS.md were read fully; their docs, generated-doc, link, and dependency-backed documentation rules shaped this review. (AGENTS.md:8, 5a5b4c5b105f)
  • PR diff scope: The PR changes only docs/concepts/memory-qmd.md, docs/reference/memory-config.md, and generated docs/docs_map.md; no runtime, workflow, lockfile, or dependency surface is changed. Public docs: docs/concepts/memory-qmd.md. (docs/concepts/memory-qmd.md:91, 142c714d054f)
  • Current main docs gap: Current main documents QMD setup, lexical search mode, semantic embedding, and first-query model downloads, but has no CPU-only VPS rollout guidance section. Public docs: docs/concepts/memory-qmd.md. (docs/concepts/memory-qmd.md:51, 5a5b4c5b105f)
  • Config contract supports BM25-first guidance: Current main defaults QMD searchMode to search, defaults startup to off, accepts only search/vsearch/query, and exposes onBoot plus embedInterval as configuration knobs. (packages/memory-host-sdk/src/host/backend-config.ts:124, 5a5b4c5b105f)
  • Runtime contract skips semantic work in lexical mode: Current main treats searchMode search as non-vector mode, skips vector probes, and suppresses embed runs and embed timers when vectors are not used. (extensions/memory-core/src/memory/qmd-manager.ts:152, 5a5b4c5b105f)
  • Upstream QMD behavior checked: QMD upstream docs describe search as BM25, vsearch as semantic search, query as hybrid plus reranking, local GGUF model downloads, and --no-rerank as faster on CPU; upstream issue 709 remains open with the same CPU-only VPS concern.

Likely related people:

  • vignesh07: CONTRIBUTING.md lists Vignesh for Memory (QMD), and earlier commits defaulted QMD search mode to search plus hardened QMD embed scheduling. (role: listed Memory/QMD owner and earlier QMD behavior contributor; confidence: high; commits: 4c79a63eb810, e38ed4f64044, a305dfe62601; files: CONTRIBUTING.md, packages/memory-host-sdk/src/host/backend-config.ts, extensions/memory-core/src/memory/qmd-manager.ts)
  • vincentkoc: Recent commits touched the QMD concept/reference docs and QMD startup maintenance behavior that this guidance documents. (role: recent area contributor; confidence: high; commits: 17be26bc4f8b, f324f7e2813a, 9895ecead3e5; files: docs/concepts/memory-qmd.md, docs/reference/memory-config.md, packages/memory-host-sdk/src/host/backend-config.ts)
  • osolmaz: Authored the QMD rerank toggle behavior and docs-relevant contract that the new CPU-only guidance references. (role: adjacent QMD config contributor; confidence: medium; commits: 0dbf17471b41, 31371101678d; files: docs/concepts/memory-qmd.md, docs/reference/memory-config.md, packages/memory-host-sdk/src/host/backend-config.ts)
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.
Review history (1 earlier review cycle)
  • reviewed 2026-07-06T10:22:55.860Z sha aaa5674 :: needs maintainer review before merge. :: none

@clawsweeper clawsweeper Bot added rating: 🐚 platinum hermit Good normal PR readiness with ordinary maintainer review expected. status: 👀 ready for maintainer look ClawSweeper has no concrete contributor-facing blocker left for this PR. P3 Low-priority cleanup, docs, polish, ergonomics, or speculative work. labels Jul 6, 2026
@openclaw-barnacle

openclaw-barnacle Bot commented Jul 23, 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 Jul 23, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

docs Improvements or additions to documentation P3 Low-priority cleanup, docs, polish, ergonomics, or speculative work. rating: 🐚 platinum hermit Good normal PR readiness with ordinary maintainer review expected. size: XS stale Marked as stale due to inactivity status: 👀 ready for maintainer look ClawSweeper has no concrete contributor-facing blocker left for this PR.

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

Document practical requirements for QMD memory backend on CPU-only VPS deployments

1 participant

@lin-hongkuan