PR #70596: perf(memory): prewarm explicit local embeddings on gateway startup

• Repository: openclaw/openclaw
• Author: taosiyuan163
• State: open | merged: False
• Link: https://github.com/openclaw/openclaw/pull/70596

Description (problem / solution / changelog)

Summary

• Problem: builtin memory_search with explicit memorySearch.provider = "local" still pays model/context initialization on the first post-startup search because gateway startup only warmed QMD.
• Why it matters: the first memory-backed reply after a gateway restart absorbs the local embedding cold start instead of the post-attach startup path.
• What changed: extend startGatewayMemoryBackend to prewarm builtin local managers by calling probeEmbeddingAvailability() after manager creation, and add gateway startup tests for explicit-local, skip, and failure logging paths.
• What did NOT change (scope boundary): this does not prewarm provider = "auto" or remote embedding providers, so startup avoids new remote network calls or auth/cost side effects.

Change Type (select all)

• Bug fix
• Feature
• Refactor required for the fix
• Docs
• Security hardening
• Chore/infra

Scope (select all touched areas)

• Gateway / orchestration
• Skills / tool execution
• Auth / tokens
• Memory / storage
• Integrations
• API / contracts
• UI / DX
• CI/CD / infra

Linked Issue/PR

• Closes #
• Related #70460
• This PR fixes a bug or regression

Root Cause (if applicable)

• Root cause: post-attach startup only initialized QMD memory, so builtin local memory waited until the first real search to create the manager and load the local embedding context.
• Missing detection / guardrail: gateway startup coverage did not assert builtin explicit-local prewarm behavior or failure logging.
• Contributing context (if known): purpose: "status" managers bypass the builtin cache, so a status-only probe would not have helped the first real search.

Regression Test Plan (if applicable)

• Coverage level that should have caught this:
  • Unit test
  • Seam / integration test
  • End-to-end test
  • Existing coverage already sufficient
• Target test or file: src/gateway/server-startup-memory.test.ts
• Scenario the test should lock in: explicit local builtin memory runs probeEmbeddingAvailability() at startup, non-local builtin configs skip startup work, and probe failures degrade to warnings.
• Why this is the smallest reliable guardrail: it exercises the gateway startup decision point without requiring real local model assets.
• Existing test that already covers this (if any): existing QMD startup tests in the same file.
• If no new test is added, why not: N/A

User-visible / Behavior Changes

• Gateways using builtin memory with agents.*.memorySearch.provider = "local" now shift local embedding cold-start work into post-attach startup, so the first real memory_search request avoids paying that initialization cost.
• No behavior change for QMD, provider = "auto", or remote memory embedding providers.

Diagram (if applicable)

Before:
gateway boot -> first builtin local memory_search -> init local embedding context -> delayed first result

After:
gateway boot -> post-attach startup prewarm -> first builtin local memory_search -> reuse warmed context

Security Impact (required)

• New permissions/capabilities? (Yes/No) No
• Secrets/tokens handling changed? (Yes/No) No
• New/changed network calls? (Yes/No) No
• Command/tool execution surface changed? (Yes/No) No
• Data access scope changed? (Yes/No) No
• If any Yes, explain risk + mitigation:

Repro + Verification

Environment

• OS: macOS
• Runtime/container: Node.js via pnpm
• Model/provider: builtin memory with explicit local embedding provider
• Integration/channel (if any): N/A
• Relevant config (redacted): memory.backend=builtin, agents.defaults.memorySearch.provider=local

Steps

1. Start the gateway with builtin memory and an explicit local memory provider.
2. Let post-attach startup run.
3. Trigger the first memory_search request after startup.

Expected

• The first real search reuses a manager whose local embedding provider has already been prewarmed.
• Non-local builtin configs still skip startup warmup.
• Failed prewarm attempts only log warnings.

Actual

• Before this change, only QMD was warmed at startup, so builtin local memory paid the cold-start cost on the first real search.

Evidence

• Failing test/log before + passing after
• Trace/log snippets
• Screenshot/recording
• Perf numbers (if relevant)

Human Verification (required)

• Verified scenarios: pnpm test src/gateway/server-startup-memory.test.ts; pnpm build
• Edge cases checked: builtin non-local skip path, builtin local probe failure logging, existing QMD startup path
• What you did not verify: end-to-end timing against a real local model cache/download on a fresh gateway boot

Review Conversations

• I replied to or resolved every bot review conversation I addressed in this PR.
• I left unresolved only the conversations that still need reviewer or maintainer judgment.

Compatibility / Migration

• Backward compatible? (Yes/No) Yes
• Config/env changes? (Yes/No) No
• Migration needed? (Yes/No) No
• If yes, exact upgrade steps:

Risks and Mitigations

• Risk: explicit local memory configs now do extra startup work and could log a warning earlier in the boot cycle.
• Mitigation: the prewarm runs only for memory.backend=builtin plus explicit provider=local, after post-attach startup, and failures degrade to warnings without blocking startup.

Changed files

• src/gateway/server-startup-memory.test.ts (modified, +63/-5)
• src/gateway/server-startup-memory.ts (modified, +31/-4)