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 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 configVersion, etag, and editableValue 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. Under Models in the sidebar, confirm that the required providers and an available embedding model are configured for the project. Configure chat, sparse embedding, rerank and vision models only as needed. The model and provider names below are examples.

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

Memory model route view

Figure: The page in a 2.12.0 test project; contents depend on project configuration.

  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 an available provider and chat model as needed, such as project:dashscope-prod and qwen-plus. The structured output mode (structuredOutputMode) must match the model's capabilities.

    • 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.
credentialModestringFixed value"appbase-llm-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 requires a Console administrator session (or administrator JWT + X-Appwrite-Mode: admin). Read the actual editableValue, configVersion, and schemaVersion, preserve the existing embedding settings, and change only the fields needed. The vision model in this example must be available in the project:

(
  set +x
  set -e -o pipefail
  : "${APPBASE_CONSOLE_SESSION:?Set APPBASE_CONSOLE_SESSION}"
: "${APPBASE_ENDPOINT:?Set APPBASE_ENDPOINT to the target API endpoint including /v1}"
APPBASE_ENDPOINT="${APPBASE_ENDPOINT%/}"
: "${APPBASE_PROJECT_ID:?Set APPBASE_PROJECT_ID for the target environment}"
: "${APPBASE_CONSOLE_SESSION:?Set APPBASE_CONSOLE_SESSION for the target environment}"

# 1. Read the current configuration and versions; preserve existing embedding fields
PROVIDER_RESP="$(builtin printf 'Cookie: %s\n' "$APPBASE_CONSOLE_SESSION" | curl --disable --header @- -fsS -w '\n%{http_code}' "${APPBASE_ENDPOINT}/projects/${APPBASE_PROJECT_ID}/memory/config/provider" \
  -H "X-Appwrite-Project: ${APPBASE_PROJECT_ID}" \
  -H "X-Appwrite-Mode: admin")"
case "${PROVIDER_RESP##*$'\n'}" in
  2??) PROVIDER_RESP="${PROVIDER_RESP%$'\n'*}" ;;
  *) builtin printf 'Configuration read returned a non-2xx response\n' >&2; exit 1 ;;
esac
CURRENT_VERSION="$(printf '%s' "${PROVIDER_RESP}" | jq -er '.configVersion')"
SCHEMA_VERSION="$(printf '%s' "${PROVIDER_RESP}" | jq -er '.schemaVersion')"
CURRENT_VALUE="$(printf '%s' "${PROVIDER_RESP}" | jq -ec '.editableValue | objects')"

# 2. Select an available vision model and construct the update
: "${VISION_PROVIDER_REF:?Set a provider available in the project}"
: "${VISION_MODEL:?Set a vision model available in the project}"
UPDATE_BODY="$(jq -n --argjson version "${CURRENT_VERSION}" \
  --argjson schema "${SCHEMA_VERSION}" --argjson value "${CURRENT_VALUE}" \
  --arg provider "${VISION_PROVIDER_REF}" --arg model "${VISION_MODEL}" \
  '{expectedConfigVersion: $version, schemaVersion: $schema,
    reason: "Configure vision route",
    value: ($value | .visionProviderRef = $provider | .visionModel = $model)}')"

# 3. Submit the editable configuration; re-read and inspect on a version conflict
builtin printf 'Cookie: %s\n' "$APPBASE_CONSOLE_SESSION" | curl --disable --header @- -fsS -X PUT "${APPBASE_ENDPOINT}/projects/${APPBASE_PROJECT_ID}/memory/config/provider" \
  -H "X-Appwrite-Project: ${APPBASE_PROJECT_ID}" \
  -H "X-Appwrite-Mode: admin" \
  -H "Content-Type: application/json" \
  --data "${UPDATE_BODY}" | 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?