feat: add OrcaRouter as a named embedding provider

[XiaoHuo888-hue]

Summary

OrcaRouter is an OpenAI-compatible model routing gateway that brings 150+ models from OpenAI, Anthropic, Google, DeepSeek, Qwen, MiniMax and xAI behind a single endpoint and API key. Beyond routing, it runs gateway-level, zero-trust security for AI agents on the same endpoint — screening every prompt/response and governing every tool call on a default-deny basis, with no application code changes. This PR registers it as a named embedding provider so users can opt in directly.

I'm an engineer on the OrcaRouter team.

What this changes

• src/basic_memory/repository/orcarouter_provider.py: new OrcaRouterEmbeddingProvider, mirroring OpenAIEmbeddingProvider but pointed at https://api.orcarouter.ai/v1 and authenticated with ORCAROUTER_API_KEY (keys start with sk-orca-).
• src/basic_memory/repository/embedding_provider_factory.py: registers orcarouter in both the provider factory dispatch and the provider identity resolver, with openai/text-embedding-3-small as the default model (1536 dimensions).
• src/basic_memory/config_models.py: documents the orcarouter value for semantic_embedding_provider.
• docs/semantic-search.md: adds the OrcaRouter provider section and updates the config reference table.
• tests/repository/test_orcarouter_provider.py: covers lazy client construction, explicit key/base-url override, dimension mismatch, missing dependency, missing key, and factory selection/identity.

Why this provider

The repo already treats openai as a named embedding provider wired directly to a single endpoint. OrcaRouter is the same OpenAI-compatible wire, but the endpoint, key, and routing stay gateway-managed, so users get the standard provider/model model ids (e.g. openai/text-embedding-3-small) through one ORCAROUTER_API_KEY.

How to use it

export BASIC_MEMORY_SEMANTIC_SEARCH_ENABLED=true
export BASIC_MEMORY_SEMANTIC_EMBEDDING_PROVIDER=orcarouter
export ORCAROUTER_API_KEY=sk-orca-...
bm reindex --embeddings

How this was tested

• Unit tests: tests/repository/test_orcarouter_provider.py + existing test_openai_provider.py — 40 passed; full tests/repository/ suite — 605 passed, 29 skipped.
• Lint/format/type: ruff check clean, ruff format --check clean, ty check clean on changed files.
• Live API: with a real ORCAROUTER_API_KEY, the PR'd create_embedding_provider(provider="orcarouter") path returned 1536-dim vectors for both embed_query and embed_documents through https://api.orcarouter.ai/v1/embeddings; provider identity resolves to OrcaRouterEmbeddingProvider:openai/text-embedding-3-small:1536.

Related issues

None.

[CLAassistant]

Thank you for your submission! We really appreciate it. Like many open source projects, we ask that you sign our Contributor License Agreement before we can accept your contribution.
_{You have signed the CLA already but the status is still pending? Let us recheck it.}

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 3a48c61f00

ℹ️ About Codex in GitHub

Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".

[chatgpt-codex-connector]

Forward OrcaRouter dimensions before declaring 1536

When semantic_embedding_provider=orcarouter uses the default model, this constructor records dimensions=1536 only as Basic Memory's expected vector size, but the inherited embed_documents() call never sends a dimensions parameter to OrcaRouter. OrcaRouter's current model card for openai/text-embedding-3-small documents a 512-dimensional default unless a dimension is requested, so the normal bm reindex --embeddings path will create/expect 1536-dimensional vector storage and then fail on the first 512-dimensional response with the provider's dimension-mismatch error. Please either request dimensions=self.dimensions for OrcaRouter models that support it or fail fast unless the configured dimensions match the gateway default.

Useful? React with 👍 / 👎.