Docs
Contents

Memory Model Routing Configuration

Feature overview and core scenarios

Memory model routing (Memory Model Routing, Console tab Models) is the hub connecting Agentbase Memory (v2.10.0) to underlying large models and vector computation capabilities, corresponding to the provider namespace (/v1/projects/{projectId}/memory/config/provider) of the project Memory configuration center. Memory is not a single model call but a composite intelligence engine driven collaboratively by five heterogeneous model classes: dense vectors (Dense Embedding), sparse vectors (Sparse Embedding), chat generation (Chat LLM), semantic reranking (Rerank), and multimodal vision (Vision LLM).

In the example project 企业智能客服与知识中台 (enterprise-ai-hub-210) of Agentbase 企业智能中台 (69c6d1aa00062e6bb60), Memory model routing is uniformly mounted on the project's DashScope production provider dashscope-prod (compatible endpoint https://dashscope.aliyuncs.com/compatible-mode/v1):


Core Concepts and Architecture

The Memory service itself never stores any upstream model's API Key in plaintext in business tables or asynchronous Job snapshots. All model requests are initiated as logical references (providerRef: "project:dashscope-prod" + model), and Agentbase's internal Models (LLM Gateway) resolves credentials in real time, performing protocol conversion and observable metering.

Memory Model Routing Configuration: workflow diagram, not a runtime screenshot

Flow diagram, not a runtime screenshot; read the relationships between steps or states along the arrows.

View the flow diagram in full size

Capability and Responsibility Comparison Table for the Five Model Classes

Model capability classprovider Configuration fieldBenchmark project configuration value (dashscope-prod)Business stage affected and degradation/failure behavior
Dense vector (Dense Embedding)embeddingProviderRef
embeddingModel
embeddingDims
project:dashscope-prod
text-embedding-v3
1024
Responsible for vectorizing regular memory, L2/L3 context, Experience, and Skill, and for vector/hybrid retrieval. These three fields are permanently locked after project initialization.
Sparse vector (Sparse Embedding)sparseEmbeddingEnabled
sparseEmbeddingProviderRef
sparseEmbeddingModel
true
project:dashscope-prod
text-embedding-v3 (Sparse routing)
Responsible for generating sparse term-weight vectors, supporting the sparse and hybrid retrieval routes. Enabled by default in newly launched wizards; can be explicitly disabled if the provider does not support sparse vectors.
Chat and reasoning (Chat LLM)llmProviderRef
chatModel
structuredOutputMode
project:dashscope-prod
qwen-plus
tool_call
Responsible for infer=true fact extraction, ADD/UPDATE/DELETE/NONE conflict resolution, Graph entity-edge extraction, query rewriting, user profiling, and experience distillation. Supports tool_call (recommended) and legacy_json.
Semantic reranking (Rerank)rerankProviderRef
rerankModel
project:dashscope-prod
qwen3.7-text-rerank
Responsible for reranking multi-route fused candidates during retrieval (policy.rerankEnabled must also be enabled), and for reranking similar memory candidates during conflict detection for new memories. On rerank failure, degradation is flagged in the response's degraded.rerank.
Multimodal vision (Vision LLM)visionProviderRef
visionModel
project:dashscope-prod
qwen-vl-max
Independent of the text Chat model, dedicated to parsing Storage images (PNG/JPEG/WebP) and PDF documents, or converting images into text descriptions during image search. Must be configured as a pair; media input is rejected when unconfigured.

Feature Entrypoints and Permission Matrix

Console Entry and Administrative Permissions

The Console entry is located at: Project enterprise-ai-hub-210 → Memory → Models tab (internally reusing the configuration center's provider namespace view).

Operation actionEntry locationUnderlying REST APIRequired permissionRelated relationships
Register an upstream model ProviderLeft navigation bar Models (Model Gateway)/v1/llm-gateway/providersprojects.writeProvides Memory with the selectable project:<providerId> catalog
View the current Memory model routingMemory → Models tabGET /v1/projects/{projectId}/memory/config/providerprojects.readReturns the current version, etag, and full provider routing configuration
Update the default model routingMemory → Models → Save ConfigurationPUT /v1/projects/{projectId}/memory/config/providerprojects.writeMust carry the expectedConfigVersion optimistic-lock version number
Override per-Pipeline model routingMemory → Configuration → Per-scenario PipelinesPATCH /v1/memory/pipelines/{pipelineId}projects.writeWhen the override checkbox is unchecked, the provider default routing on this page is inherited automatically

Inheritance Between Default Routing and Custom Pipeline Routing

  1. Inheritance and override rules: In the four Pipeline classes under Memory → Configuration (new memories, profile, experience and skills, forgetting), each node (e.g., fact extraction, conflict resolution, profile generation) can specify its own model routing; if node-level routing override is unchecked, then the default routing configured on this page (provider namespace) is inherited automatically (unchecking means “inherit the default”, not “disable this capability”).

  2. Shared model routing snapshot: The shared embedding, rerank, and vision routes configured in the current project's default new-memory pipeline also apply to online memory retrieval (search), unified retrieval (recall), image query parsing, and background re-indexing tasks. Async tasks freeze the model routing snapshot at the moment they are enqueued (excluding plaintext keys) to ensure consistent behavior during retries.


Feature Details and Operation Guide

1. View and adjust Memory model routes in the Console

  1. Log in to the Agentbase Console and go to project 企业智能客服与知识中台 (enterprise-ai-hub-210).

  2. First confirm in the left-side Models (Model Gateway) that provider dashscope-prod has been added, and that the model catalog includes text-embedding-v3, qwen-plus, qwen3.7-text-rerank, and qwen-vl-max (vision models registered with the vlm category are shown first; multimodal models under the chat category are also compatible).

  3. Open the left-side Memory and switch to the Models tab.

Memory model route view (reusing an existing screenshot)

Interface reference: reuses previously registered historical screenshots; demo data may differ from the current project; no new screenshots were taken this time.

  1. Configure or adjust the editable model route fields according to business needs:

    • Embedding route (read-only, locked): the page shows embeddingProviderRef (project:dashscope-prod), embeddingModel (text-embedding-v3), and embeddingDims (1024) as locked, preventing damage to the existing OceanBase vector table spaces.

    • Sparse embedding: check to enable and bind a sparse embedding model from project:dashscope-prod.

    • Chat model route: select provider project:dashscope-prod and model qwen-plus, and set structured output mode (structuredOutputMode) to tool_call (the LLM Gateway enforces validation of tool names and the JSON Schema, significantly reducing the incidence of LLM_INVALID_JSON).

    • Rerank model route: select provider project:dashscope-prod and model qwen3.7-text-rerank.

    • Vision model route (Vision LLM): select visionProviderRef (project:dashscope-prod) and visionModel (qwen-vl-max) as a pair. Note: filling in only one of them is invalid; the project only accepts Storage image/PDF memory writes after the pair is configured and saved.

  2. Enter the change reason (reason) and click Save.

2. Complete parameter specification for the provider configuration namespace

When reading or writing /v1/projects/{projectId}/memory/config/provider via the control plane API, the complete field definitions are as follows:

Field nameTypeModifiable after initializationExample configuration exampleValidation rules and detailed description
allowedProvidersstring[]Modifiable["openai", "dashscope", "anthropic", "theta"]Whitelist of upstream provider types that project Memory may use.
credentialModestringModifiable"project_gateway"Credentials are always resolved through the project LLM Gateway; inlining plaintext keys in requests is prohibited.
embeddingProviderRefstringImmutable"project:dashscope-prod"Dense embedding provider reference. Modifying it after Memory initialization triggers the 400/409 immutability guard.
embeddingModelstringImmutable"text-embedding-v3"Dense embedding model identifier, permanently locked after initialization.
embeddingDimsintegerImmutable1024Physical vector column dimension; must match the model's actual output dimension and is permanently locked after initialization.
sparseEmbeddingEnabledbooleanModifiabletrueWhether to enable the sparse embedding index and the sparse retrieval branch.
sparseEmbeddingProviderRefstringModifiable"project:dashscope-prod"Sparse embedding provider reference (required when sparse embedding is enabled).
sparseEmbeddingModelstringModifiable"text-embedding-v3"Sparse embedding model identifier.
llmProviderRefstringModifiable"project:dashscope-prod"Default chat and inference model provider reference.
chatModelstringModifiable"qwen-plus"Default chat and inference model name.
structuredOutputModestringModifiable"tool_call"Structured output protocol; supports "tool_call" (recommended, schema enforced) and "legacy_json".
rerankProviderRefstringModifiable"project:dashscope-prod"Default rerank model provider reference.
rerankModelstringModifiable"qwen3.7-text-rerank"Default rerank model name.
visionProviderRefstringModifiable"project:dashscope-prod"Multimodal vision model provider reference; must be set as a pair with visionModel.
visionModelstringModifiable"qwen-vl-max"Multimodal vision model name, used for parsing Storage images and PDFs.

3. Examples of querying and updating model routes via the control plane API

Updating project configuration is a control plane operation that requires a Console administrator session (or an administrator JWT + X-Appwrite-Mode: admin), and must pass in the expectedConfigVersion returned by the most recent GET:

export APPBASE_ENDPOINT="https://appbuild.oceanbase.com/v1"
export APPBASE_PROJECT_ID="enterprise-ai-hub-210"

# 1. Read the current provider namespace configuration and version number (version)
PROVIDER_RESP="$(curl -fsS "${APPBASE_ENDPOINT}/projects/${APPBASE_PROJECT_ID}/memory/config/provider" \
  -H "Cookie: ${APPBASE_CONSOLE_SESSION}" \
  -H "X-Appwrite-Project: ${APPBASE_PROJECT_ID}" \
  -H "X-Appwrite-Mode: admin")"

echo "${PROVIDER_RESP}" | jq .
CURRENT_VERSION="$(echo "${PROVIDER_RESP}" | jq -er '.version')"

# 2. Update the provider configuration (keep the locked embedding triple unchanged; enable qwen-vl-max visual routing and tool_call mode)
curl -fsS -X PUT "${APPBASE_ENDPOINT}/projects/${APPBASE_PROJECT_ID}/memory/config/provider" \
  -H "Cookie: ${APPBASE_CONSOLE_SESSION}" \
  -H "X-Appwrite-Project: ${APPBASE_PROJECT_ID}" \
  -H "X-Appwrite-Mode: admin" \
  -H "Content-Type: application/json" \
  --data "{
    \"expectedConfigVersion\": ${CURRENT_VERSION},
    \"reason\": \"开启 qwen-vl-max 多模态视觉路由并切换 tool_call 结构化输出模式\",
    \"value\": {
      \"allowedProviders\": [\"openai\", \"dashscope\", \"anthropic\", \"theta\"],
      \"credentialMode\": \"project_gateway\",
      \"embeddingProviderRef\": \"project:dashscope-prod\",
      \"embeddingModel\": \"text-embedding-v3\",
      \"embeddingDims\": 1024,
      \"sparseEmbeddingEnabled\": true,
      \"sparseEmbeddingProviderRef\": \"project:dashscope-prod\",
      \"sparseEmbeddingModel\": \"text-embedding-v3\",
      \"llmProviderRef\": \"project:dashscope-prod\",
      \"chatModel\": \"qwen-plus\",
      \"structuredOutputMode\": \"tool_call\",
      \"rerankProviderRef\": \"project:dashscope-prod\",
      \"rerankModel\": \"qwen3.7-text-rerank\",
      \"visionProviderRef\": \"project:dashscope-prod\",
      \"visionModel\": \"qwen-vl-max\"
    }
  }" | jq .

FAQ (Frequently Asked Questions and Troubleshooting)

1. Why can't the embedding model or vector dimension be modified directly on the Models tab after Memory is enabled for a project?

2. A qwen3.7-text-rerank rerank model is configured on the Models tab—why is Rerank still not triggered in search response results?

3. How to handle async write or distillation task errors LLM_RATE_LIMITED, LLM_INVALID_JSON, or LLM_REQUEST_REJECTED?