feat: OpenRouter provider routing and reasoning control

[chiefmojo]

Problem

When using OpenRouter as the LLM provider, operators have no way to:

1. Exclude specific upstream providers from serving requests (provider.ignore)
2. Set a preferred provider order (provider.order)
3. Control reasoning effort per model slot (reasoning)

All three are standard OpenRouter-specific request fields that MemOS currently passes through to the HTTP body without any config surface.

Changes

Config schema — adds providerIgnore, providerOrder, and reasoning to LlmSchema and SkillEvolverSchema:

llm:
  provider: openai_compatible
  endpoint: https://openrouter.ai/api/v1
  apiKey: sk-...
  providerIgnore:
    - together
    - deepinfra
  providerOrder:
    - anthropic
    - google
  reasoning:
    enabled: true
    max_tokens: 8000

SkillEvolverSchema:
  provider: openai_compatible
  endpoint: https://openrouter.ai/api/v1
  providerIgnore:
    - novita

Provider layer — openai.ts detects OpenRouter endpoints and injects the provider routing object; reasoning is forwarded unconditionally when set. Non-OpenRouter endpoints are unaffected.

Embedding — providerIgnore/providerOrder added to the embedding config schema; openai.ts embedding provider applies the same routing logic.

Pipeline — bootstrapMemoryCore forwards the new fields to createLlmClient for the skillEvolver slot.

Tests

• providers.test.ts — reasoning forwarding, routing injection for non/streaming calls, non-OpenRouter passthrough
• bootstrap-llm-config.test.ts — verifies routing fields propagate to dedicated LLM clients
• load.test.ts — defaults to empty arrays, accepts explicit values

[Memtensor-AI]

Automated Test Results: PASSED

Cloud test-engine rerun against dev-v2.0.22 completed successfully.

• Run: tr-013a21fe-6ec on cloud test-engine 10011
• memos_local_openclaw/unit: 10 passed, 0 failed, 0 skipped
• memos_local_plugin/unit: 90 passed, 0 failed, 0 skipped

Manual code review is still required before merge.

[Memtensor-AI]

Conflict status update: I verified locally that refs/pull/1958/head cleanly merges with dev-v2.0.22, and the previous cloud test-engine run passed (tr-013a21fe-6ec, 100/100). However, pushing the merge commit back to the PR head failed because the head fork repository is not accessible (Repository not found).

Current conclusion: automated tests passed, but the PR cannot be merged while GitHub still reports it as conflicting. The branch needs to be updated by the author/maintainer, or a replacement branch/PR needs to be created from the locally clean merge commit and then retested.

[shinetata]

Thanks for this PR, Erick — OpenRouter provider routing is a useful gap to close, and the test coverage (streaming / non-streaming / embedding, non-OpenRouter passthrough, config defaults, bootstrap forwarding) is solid. The Cloud test-engine rerun also passed (100/100) on dev-v2.0.22.

Before we can merge, a few items need attention. Marking as changes_requested to track them.

Blocking — merge conflict

GitHub currently reports this PR as CONFLICTING / DIRTY against main. The head last merged main on 2026-07-04; main has since advanced to 13fbd437 (2026-07-09). The earlier bot note referenced dev-v2.0.22, but that branch no longer exists, so a fresh rebase onto the current main is needed.

Could you rebase feat/openrouter-routing onto main and force-push? If you'd prefer a maintainer to take it over, just say so and we'll open a replacement PR (we've done this for a couple of other stale external PRs).

Code — three improvements

1. DRY: the routing helper is duplicated 4×

applyOpenRouterProviderRouting is implemented nearly verbatim in:

• apps/memos-local-plugin/core/llm/providers/openai.ts
• apps/memos-local-plugin/core/embedding/providers/openai.ts
• apps/memos-local-openclaw/src/shared/llm-call.ts
• apps/memos-local-openclaw/src/ingest/providers/openai.ts (here it's still inlined in buildRequestBody, not even extracted)

Please factor it into a single shared helper per app (the two apps/ don't share code, so one helper under each app's shared layer is fine) and have all call sites use it. The inlined version in ingest/providers/openai.ts should call the helper for consistency.

2. OpenRouter detection is brittle

endpoint.includes("openrouter.ai") is case-sensitive and substring-based:

• OpenRouter.AI / OPENROUTER.ai won't match.
• A self-hosted proxy whose URL happens to contain openrouter.ai as a substring (path / query / hostname fragment) would be misclassified.
• Conversely, users fronting OpenRouter via their own domain (reverse proxy / CNAME) get no routing even though the upstream is OpenRouter.

Suggest normalizing with new URL(endpoint).hostname lowercased and comparing against a known host list, and/or adding an explicit openrouter: true opt-in flag on the LLM / embedding config so routing isn't inferred from the URL at all.

3. reasoning is forwarded unconditionally

In core/llm/providers/openai.ts:

if (config.reasoning) body.reasoning = config.reasoning;

This sends reasoning to every endpoint, not just OpenRouter. Non-OpenRouter providers may reject the unknown field or silently ignore it. Either gate it behind the OpenRouter check, or document explicitly that it's a passthrough intended for OpenAI-compatible reasoning models and accept that behavior.

Deadline

Could you push an update by 2026-07-23? If there's no activity by then, to keep main moving we'll close this PR and open a maintainer-side replacement with the above items addressed (credit will be preserved in the replacement PR description). Happy to help with the rebase or the refactor if useful — just ping here.

[Memtensor-AI]

🤖 Open Code Review

Target: PR #1958
Task: e587adf61a6135f5
Base: dev-v2.0.25
Head: feat/openrouter-routing

🔍 OpenCodeReview found 7 issue(s) in this PR.

⚠️ 1 warning(s) occurred during review.

---

1. apps/memos-local-plugin/core/embedding/types.ts (L34-L35)

Type contract mismatch: openRouter is declared as a required boolean in EmbeddingConfig, but in EmbeddingSchema it is defined as Type.Optional(Bool(false)), which TypeBox resolves to boolean | undefined. If any caller constructs or passes an EmbeddingConfig without going through the full config resolution pipeline (e.g., in unit tests or partial config objects), openRouter may be undefined at runtime even though the type says it cannot be. To stay consistent with the schema, mark it optional here too (openRouter?: boolean), or ensure the schema uses a non-optional field. Compare: providerIgnore and providerOrder are correctly marked ? here.

💡 Suggested Change

Before:

  /** Explicitly enable OpenRouter fields for a reverse proxy or CNAME. */
  openRouter: boolean;

After:

  /** Explicitly enable OpenRouter fields for a reverse proxy or CNAME. */
  openRouter?: boolean;

---

2. apps/memos-local-plugin/core/llm/providers/openai.ts (L217-L223)

The effort field allows the literal value "none" (defined in ReasoningSchema), which is not a valid value in the OpenRouter reasoning API. OpenRouter's reasoning object accepts "low", "medium", and "high" for effort, and disabling reasoning is done via { enabled: false } rather than { effort: "none" }. Sending effort: "none" will likely cause a 4xx validation error from OpenRouter.

Suggestion: Remove "none" from the effort union in ReasoningSchema, or add a guard here to skip serializing effort when its value is "none" and map it to enabled: false instead.

💡 Suggested Change

Before:

function serializeOpenRouterReasoning(reasoning: ReasoningConfig): Record<string, unknown> | undefined {
  const result: Record<string, unknown> = {};
  if (reasoning.enabled !== undefined) result.enabled = reasoning.enabled;
  if (reasoning.effort !== undefined) result.effort = reasoning.effort;
  if (reasoning.maxTokens !== undefined) result.max_tokens = reasoning.maxTokens;
  return Object.keys(result).length > 0 ? result : undefined;
}

After:

function serializeOpenRouterReasoning(reasoning: ReasoningConfig): Record<string, unknown> | undefined {
  const result: Record<string, unknown> = {};
  if (reasoning.enabled !== undefined) result.enabled = reasoning.enabled;
  if (reasoning.effort !== undefined && reasoning.effort !== "none") result.effort = reasoning.effort;
  if (reasoning.maxTokens !== undefined) result.max_tokens = reasoning.maxTokens;
  return Object.keys(result).length > 0 ? result : undefined;
}

---

3. apps/memos-local-plugin/core/llm/providers/openai.ts (L78-L81)

Because config.reasoning has a schema default of {} (an empty object), it will always be truthy after config resolution — meaning serializeOpenRouterReasoning is always called when OpenRouter is detected, even when no reasoning fields were configured. The config.reasoning && guard is misleading and provides no actual protection. This is harmless only because serializeOpenRouterReasoning returns undefined for an empty object, but the guard creates false confidence about a potential early-exit. Consider removing the guard or adding a comment clarifying this.

💡 Suggested Change

Before:

    if (applyOpenRouterProviderRouting(config, body)) {
      const reasoning = config.reasoning && serializeOpenRouterReasoning(config.reasoning);
      if (reasoning) body.reasoning = reasoning;
    }

After:

    if (applyOpenRouterProviderRouting(config, body)) {
      const reasoning = serializeOpenRouterReasoning(config.reasoning ?? {});
      if (reasoning) body.reasoning = reasoning;
    }

---

4. apps/memos-local-plugin/core/config/schema.ts (L61-L69)

The effort union includes "minimal", "xhigh", and "max" which are not valid values in the OpenRouter API spec. The OpenRouter reasoning object's effort field only accepts "low", "medium", and "high". Sending an unrecognised value will either be silently ignored or cause a 4xx error from OpenRouter, with no validation feedback to the user.

Consider restricting the union to the documented values, or — if you want to stay forward-compatible with new provider-specific values — replace the closed union with a plain Type.String() and add a comment referencing the API docs.

💡 Suggested Change

Before:

  effort: Type.Optional(Type.Union([
    Type.Literal("minimal"),
    Type.Literal("none"),
    Type.Literal("low"),
    Type.Literal("medium"),
    Type.Literal("high"),
    Type.Literal("xhigh"),
    Type.Literal("max"),
  ])),

After:

  // Valid values per OpenRouter API docs: "low" | "medium" | "high"
  effort: Type.Optional(Type.Union([
    Type.Literal("low"),
    Type.Literal("medium"),
    Type.Literal("high"),
  ])),

---

5. apps/memos-local-plugin/core/config/schema.ts (L52)

ReasoningSchema is declared with { default: {} } at the object level, but it is only ever used inside Type.Optional(ReasoningSchema). When TypeBox resolves the config it will materialise the default {} for any omitted reasoning block, meaning config.reasoning will be {} rather than undefined. The jsdoc comment says "Omit the whole block to keep the provider/model default", which contradicts this behaviour.

Drop the object-level default so that an absent reasoning key correctly resolves to undefined, consistent with the documented intent.

💡 Suggested Change

Before:

}, { default: {} });

After:

});

---

6. apps/memos-local-plugin/core/llm/types.ts (L39-L40)

Type inconsistency: openRouter is required in LlmConfig but optional in OpenRouterRoutingConfig.

In openrouter.ts, OpenRouterRoutingConfig declares openRouter?: boolean (optional). The config schema also defines it as Type.Optional(Bool(false)). However, LlmConfig.openRouter is a required non-optional boolean, creating a structural mismatch between the two interfaces that represent the same concept.

This means any code path that builds a partial LlmConfig (e.g., before defaults are applied) or passes a value satisfying OpenRouterRoutingConfig will either fail type-checking or require explicit assertion. The field should be made optional (openRouter?: boolean) to be consistent with its schema definition and with OpenRouterRoutingConfig, especially since applyOpenRouterProviderRouting accepts OpenRouterRoutingConfig and the runtime already guards with the isOpenRouter check that handles undefined.

💡 Suggested Change

Before:

  /** Explicitly enable OpenRouter fields for a reverse proxy or CNAME. */
  openRouter: boolean;

After:

  /** Explicitly enable OpenRouter fields for a reverse proxy or CNAME. */
  openRouter?: boolean;

---

7. apps/memos-local-plugin/core/pipeline/memory-core.ts (L124-L135)

DedicatedLlmConfig is a private type re-declaration that closely mirrors the static type derived from SkillEvolverSchema (which config.skillEvolver and config.l3Llm already conform to). The type-cast (config as { skillEvolver?: DedicatedLlmConfig }) is therefore redundant. Since config is a ResolvedConfig, its skillEvolver and l3Llm fields are already fully typed. Accessing them directly (e.g., config.skillEvolver) avoids the risk of this local type silently drifting out of sync with the schema.

Suggestion: Remove DedicatedLlmConfig and access the config fields directly as config.skillEvolver and config.l3Llm.

---

🧹 Filtered 13 low-confidence OCR finding(s) before posting/fix-loop (existing_code_mismatch: 5, duplicate: 8).

Generated by cloud-assistant via Open Code Review.

[chiefmojo]

Rebased onto current main and force-pushed 2c8178d. Consolidated OpenRouter routing into one helper per app, replaced all four call sites, added robust hostname detection plus explicit openRouter proxy opt-in, and gated/normalized reasoning fields. Also fixed dedicated L3 config propagation. Validation: 66 focused plugin tests, 3 OpenClaw call tests, plugin type-check, and make format.

[Memtensor-AI]

✅ Automated Test Results: PASSED

All tests passed (134/134 executed). memos_local_openclaw/unit: 33/33, memos_local_plugin/unit: 101/101. Duration: 17s [advisory, non-gating] AI-generated tests on branch test/auto-gen-650698fd619b8f1a-20260717122622: 110/112 passed, 2 failed — these do NOT affect the PR verdict; review the branch manually.

Branch: feat/openrouter-routing

[whipser030]

Thanks for the update — the earlier concerns around OpenRouter routing detection, reasoning passthrough for non-OpenRouter requests, and helper reuse appear to be addressed well, and the test coverage looks solid.

Before merging, could we please clarify two small edge cases?

1. reasoning: {} may currently enable reasoning through the default value of enabled. This seems slightly at odds with the documentation stating that omitted configuration should preserve the provider/model default. Would it make sense to avoid enabling it by default here?

2. In a few dedicated LLM configuration paths, openRouter may be passed as undefined while its type is declared as a required boolean. It may be worth adding ?? false at the handoff point, or making the field optional consistently, to keep the runtime behavior and type contract aligned.

Also, when convenient, could you please confirm that the latest branch now merges cleanly with current main? Once that is confirmed, I’d be happy to take another look.

[chiefmojo]

@whipser030 Addressed in aa75c36:

• Empty reasoning blocks no longer default enabled to true and are omitted from OpenRouter request bodies, preserving provider/model defaults.
• Dedicated skillEvolver and l3Llm clients now normalize an absent openRouter flag to false.

Added focused regressions for both paths. The branch contains current main and GitHub reports the PR mergeable.

[Memtensor-AI]

✅ Automated Test Results: PASSED

All tests passed (137/137 executed). memos_local_openclaw/unit: 33/33, memos_local_plugin/unit: 104/104. Duration: 17s [advisory, non-gating] AI-generated tests on branch test/auto-gen-b5be9075636df774-20260717203542: 126/126 passed — these do NOT affect the PR verdict; review the branch manually.

Branch: feat/openrouter-routing

[shinetata]

@chiefmojo Thanks for the fast turnaround. I re-reviewed the current state (through aa75c369) and all the points from both review rounds are addressed:

• ✅ Routing helper consolidated into one shared module per app; all four call sites use it
• ✅ OpenRouter detection now uses new URL(...).hostname against a host allowlist + explicit openRouter opt-in
• ✅ reasoning is only forwarded on OpenRouter endpoints, and empty reasoning blocks are omitted (no implicit enabled: true)
• ✅ skillEvolver / l3Llm normalize a missing openRouter flag to false
• ✅ CI green across the board (build matrix + AutoTest); the OCR findings are non-blocking

Approving now. The only remaining step before merge is that the branch is 2 commits behind main — it's a clean update (no conflicts, MERGEABLE); branch protection just needs the head to be up to date. Since this is a fork PR we can't reach with maintainer edits, could you sync it on your side?

git checkout feat/openrouter-routing
git fetch upstream                 # upstream = MemTensor/MemOS
git rebase upstream/main           # only 2 commits, no conflicts expected
git push --force-with-lease origin feat/openrouter-routing

(A plain git merge upstream/main + push is fine too if you'd rather not rewrite history.)

Once it's up to date it's good to squash-merge — well before the 07-23 date, so no need to worry about the replacement-PR route. The 13 OpenCodeReview nits (doc comments, optional-type alignment) are non-blocking and can be a follow-up. Thanks again for the thorough work!

[shinetata]

Quick correction to my earlier note — no branch sync is needed on your side. Retargeting external PRs onto our weekly release branch (dev-v2.0.25) is a maintainer-side step; since that branch does not require the head to be up to date and there are no conflicts, I have switched the base and am merging from here. Nothing further needed from you — thanks again for the thorough OpenRouter work.

[Memtensor-AI]

✅ Automated Test Results: PASSED

All tests passed (137/137 executed). memos_local_openclaw/unit: 33/33, memos_local_plugin/unit: 104/104. Duration: 17s [advisory, non-gating] AI-generated tests on branch test/auto-gen-e587adf61a6135f5-20260721223302: 74/78 passed, 4 failed — these do NOT affect the PR verdict; review the branch manually.

Branch: feat/openrouter-routing