Docs
Contents

Memory Configuration Center and Custom Pipelines

Feature overview and core scenarios

The Memory Configuration Center and custom pipelines (Memory Configuration & Pipelines; the Console tab is Configuration) are the policy and process configuration interface for Agentbase Memory. In real enterprise production environments, different business scenarios have vastly different requirements for the granularity of fact extraction, the structure of user profiles, knowledge distillation thresholds, and the decay/forgetting cycle of historical memories. Coupling all prompts and model parameters into a single global monolithic object not only makes concurrent edits overwrite each other easily, but also makes it impossible to safely validate the effect of new prompts before rollout.

To address this, Agentbase Memory provides a two-layer configuration governance system:

  1. Four scenario-based business Pipelines (add_memory, profile, distillation, forgetting): supports one-click draft creation from system defaults, per-node customization of prompts and model routing, online trial validation via Dry-run samples, and releasing immutable versions and switching the scenario's default pipeline (a single project supports at most 32 custom Pipelines across all four scenario types combined);

  2. Versioned Config Center: organized by responsibility into the provider, policy, prompt, retention, and evolution namespaces (plus the underlying runtime runtime), fully adopting optimistic concurrency control based on expectedConfigVersion and HTTP If-Match / If-None-Match (ETag), with version history viewing, Diff comparison, and one-click rollback.

For example, an administrator can configure a customer support pipeline to extract ticket numbers and cluster versions, then set retention policies for the workload. Project names, models, and parameters below are examples.


Core Concepts and Architecture

The Config Center decouples frequently iterated “business pipeline node parameters (Pipelines)” from globally effective “system-level governance policies (Config Namespaces)”, and guarantees that in-flight production tasks are not disturbed by configuration changes through a version snapshot freeze mechanism applied at task acceptance.

Memory Configuration Center and Custom Pipelines: 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

Comparison Table of Fixed Steps and Tunable Parameters for the Four Business Pipelines

Each Pipeline's scenario type (scenario) is fixed after creation and cannot be modified; its internal nodes execute in a predefined topological order (nodes cannot be reordered or deleted, but optional nodes can be enabled/disabled by rule):

Scenario name (scenario)Fixed node execution topological orderCore tunable node parameters and model routing overridesSample validation (Dry-run) behavior
Add Memory (add_memory)receive (receive) → fact_extraction (fact extraction) → conflict_detection (conflict judgment) → memory_operation (memory operations)- fact_extraction: custom extraction prompt, maximum facts per extraction (maxFacts), Chat model routing (toggleable);
- conflict_detection: conflict judgment prompt, retrieval candidates per fact (candidatesPerFact), maximum total candidates (maxCandidates), Chat model routing (toggleable);
- Shared models: can override embedding, rerank, and vision routing and the conflict re-ranking toggle rerankEnabled.
Calls real models to perform extraction and conflict comparison, directly displaying the planned ADD/UPDATE/DELETE/NONE results, and does not write to the production memory table.
Profile (profile)receive (receive) → profile_generation (profile generation) → profile_operation (profile operations)- All three steps are mandatory;
- profile_generation: allows separately customizing the incremental generation prompt (prompt) and the source-rebuild prompt (rebuildPrompt), and independently specifying the Chat/VLM model routing for the generation node.
Calls the model and returns the generated profile content, does not overwrite the user's existing production profile.
Experiences & Skills (distillation)receive → skill_extraction → skill_merge → experience_extraction → experience_merge → validation → knowledge_operation- At least one of skill_extraction and experience_extraction must be enabled (when one is disabled, its corresponding merge node is automatically skipped, with parameters preserved);
- Merge candidate count maxCandidates (1~20), merge threshold mergeThreshold ((0, 1]);
- Independent prompts and Chat models per node, with shared models.embedding routing override.
Displays the extracted and merged skill/experience titles, summaries, and node technical details, does not persist production knowledge or confirmation records.
Forgetting (forgetting)memory_scan (scan memories) → forgetting_decision (forgetting judgment) → forgetting_operation (execute forgetting)- Uses deterministic mathematical decay rules (no LLM prompt parameters);
- memory_scan: scan batch size batchSize (1~1000);
- forgetting_decision (disableable): initial retention rate, decay rate, tier thresholds, minimum protection period (minimum_protection_hours), review intervals, and permanent-forgetting toggle.
Performs a read-only scan of the specified sample user's visible memories, returning scanned along with planned actions (archive, expire, review, promote) and dryRun: true; never executes any deletion or archive writes.

Feature Entrypoints and Permission Matrix

Console Entry Point and Permission Requirements

The Console entry is located at: Project enterprise-ai-hub-210 → Memory → Configuration tab. This tab contains 5 secondary sub-views: Add Memory Pipeline, Profile Pipeline, Experiences & Skills Pipeline, Forgetting Pipeline, and Base Configuration.

Operation categoryConsole entryREST API endpointRequired permissions
Query and create PipelinesEach scenario's Pipeline list → New PipelineGET /v1/memory/pipelines?scenario=..., POST /v1/memory/pipelinesprojects.read / projects.write
Save draft, run sample, and publishAt the top of the editor: Save Draft / Run Sample / PublishPATCH /v1/memory/pipelines/{pipelineId}, POST .../validate, POST .../publishprojects.write; sample validation also requires memories.read
Switch or restore a scenario's default PipelineSet as Default / Restore System DefaultPUT /v1/memory/pipelines/defaultprojects.write
Read and write 5 major system configuration namespacesBase Configuration sub-viewGET/PUT /v1/projects/{projectId}/memory/config/{namespace}projects.read / projects.write
View configuration history, Diff, and rollbackExpand Configuration Versions areaGET /v1/projects/{projectId}/memory/config/{namespace}/history, GET /v1/projects/{projectId}/memory/config/{namespace}/history/{historyId}/diff?toHistoryId=..., POST .../rollbackprojects.read / projects.write

A normal project API key cannot provide projects.write; use an appropriately authorized Console session for the management writes and sample validation above.


Feature Details and Operation Guide

1. Create, validate, and publish a custom memory Pipeline

  1. Log in to the Agentbase Console, enter the project 企业智能客服与知识中台 (enterprise-ai-hub-210), and open the Memory → Configuration tab.

Memory Configuration Center view

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

  1. Select the business scenario you want to adjust (for example, Create memory), and click Create to create a draft from the system default (corresponding to POST /v1/memory/pipelines with {"scenario": "add_memory", "fromDefaults": true}).

  2. In the pipeline node you want to customize (for example, Fact Extraction fact_extraction), adjust the prompt, maximum facts per extraction (maxFacts), or model route for your use case.

  3. Click Save at the top of the editor to save the current draft.

Memory pipeline draft in the test project

Figure: A newly created draft in a 2.12.0 test project, not yet validated or published.

  1. Run sample validation (Dry-run):

    • After the draft is saved, enter a test message and any required user ID in the sample area, and click Validate (calls POST /v1/memory/pipelines/{pipelineId}/validate);

    • The currently saved draft version must successfully pass a sample validation once before the system allows publishing.

  2. Publish the version and set it as default:

    • After verifying that the sample output meets expectations, click Publish (POST /v1/memory/pipelines/{pipelineId}/publish); you can simultaneously check Set as the default Pipeline for this scenario (makeDefault: true).

    • After publishing, you can explicitly select the published Pipeline on the memory, profile, or experience & skills pages, or directly inherit the updated scene default Pipeline. Accepted historical tasks continue to use the published version frozen at enqueue time; switching the default will not recompute historical data.

Trial runs for saved Pipeline versions

A project can use a trial run to compare saved Pipeline versions for the same scenario. Create a run with POST /v1/memory/pipeline-runs with an authorized Console administrator session; a normal project API key cannot provide the required projects.write scope. Supply a scenario, 1–8 candidates, and 1–20 samples. Supported scenarios are add_memory, profile, distillation, and forgetting. HTTP 202 means the request was accepted, not that the trial is complete.

Use GET /v1/memory/pipeline-runs/{runId} to inspect progress and per-sample results, or GET /v1/memory/pipeline-runs to list runs by scenario; reading with a project API key requires both projects.read and memories.read. Console operations use an authorized session. A trial freezes candidates and samples when accepted and does not write business memories. Model calls may incur charges depending on the configuration. Availability depends on the deployment.

Create and validate a forgetting pipeline:

Set APPBASE_ENDPOINT to the target API endpoint (including /v1), and use an authorized Console administrator session and set APPBASE_PROJECT_ID and APPBASE_CONSOLE_SESSION; a normal project API key is not suitable for this example. Run each step separately and continue only after an HTTP 2xx response with the expected result. The create response returns pipelineId, draftVersionId, and revision; replace the placeholders below with these values. After validation succeeds, read the latest revision before publishing; reread revision after publication before setting a default. Example numbers are placeholders.

  1. Create a forgetting pipeline using defaults (scenario=forgetting)

(
  set +x
  set -e -o pipefail
  : "${APPBASE_ENDPOINT:?Set APPBASE_ENDPOINT to the target API endpoint including /v1}"
  : "${APPBASE_PROJECT_ID:?Set APPBASE_PROJECT_ID}"
  : "${APPBASE_CONSOLE_SESSION:?Set APPBASE_CONSOLE_SESSION}"
  APPBASE_ENDPOINT="${APPBASE_ENDPOINT%/}"
  RESPONSE="$(builtin printf 'Cookie: %s\n' "$APPBASE_CONSOLE_SESSION" | curl --disable --header @- -sS -w '\n%{http_code}' -X POST "${APPBASE_ENDPOINT}/memory/pipelines" \
    -H "X-Appwrite-Project: ${APPBASE_PROJECT_ID}" \
    -H "X-Appwrite-Mode: admin" \
    -H "Content-Type: application/json" \
    --data '{"scenario":"forgetting","fromDefaults":true}')"
  HTTP_STATUS="${RESPONSE##*$'\n'}"
  builtin printf '%s\nHTTP %s\n' "${RESPONSE%$'\n'*}" "$HTTP_STATUS"
  case "$HTTP_STATUS" in 2??) ;; *) exit 1 ;; esac
)
  1. Run a single-user Ebbinghaus forgetting dry-run validation preview (POST /v1/memory/pipelines/{id}/validate)

(
  set +x
  set -e -o pipefail
  : "${APPBASE_ENDPOINT:?Set APPBASE_ENDPOINT to the target API endpoint including /v1}"
  : "${APPBASE_PROJECT_ID:?Set APPBASE_PROJECT_ID}"
  : "${APPBASE_CONSOLE_SESSION:?Set APPBASE_CONSOLE_SESSION}"
  APPBASE_ENDPOINT="${APPBASE_ENDPOINT%/}"
  RESPONSE="$(builtin printf 'Cookie: %s\n' "$APPBASE_CONSOLE_SESSION" | curl --disable --header @- -sS -w '\n%{http_code}' -X POST "${APPBASE_ENDPOINT}/memory/pipelines/<PIPELINE_ID_FROM_RESPONSE>/validate" \
    -H "X-Appwrite-Project: ${APPBASE_PROJECT_ID}" \
    -H "X-Appwrite-Mode: admin" \
    -H "Content-Type: application/json" \
    --data '{"versionId":"<DRAFT_VERSION_ID_FROM_RESPONSE>","data":{"userId":"user_zhangwei_001"}}')"
  HTTP_STATUS="${RESPONSE##*$'\n'}"
  builtin printf '%s\nHTTP %s\n' "${RESPONSE%$'\n'*}" "$HTTP_STATUS"
  case "$HTTP_STATUS" in 2??) ;; *) exit 1 ;; esac
)
  1. Publish the pipeline after validation succeeds (POST .../publish)

(
  set +x
  set -e -o pipefail
  : "${APPBASE_ENDPOINT:?Set APPBASE_ENDPOINT to the target API endpoint including /v1}"
  : "${APPBASE_PROJECT_ID:?Set APPBASE_PROJECT_ID}"
  : "${APPBASE_CONSOLE_SESSION:?Set APPBASE_CONSOLE_SESSION}"
  APPBASE_ENDPOINT="${APPBASE_ENDPOINT%/}"
  RESPONSE="$(builtin printf 'Cookie: %s\n' "$APPBASE_CONSOLE_SESSION" | curl --disable --header @- -sS -w '\n%{http_code}' -X POST "${APPBASE_ENDPOINT}/memory/pipelines/<PIPELINE_ID_FROM_RESPONSE>/publish" \
    -H "X-Appwrite-Project: ${APPBASE_PROJECT_ID}" \
    -H "X-Appwrite-Mode: admin" \
    -H "Content-Type: application/json" \
    --data '{"versionId":"<DRAFT_VERSION_ID_FROM_RESPONSE>","expectedRevision":1,"makeDefault":false}')"
  HTTP_STATUS="${RESPONSE##*$'\n'}"
  builtin printf '%s\nHTTP %s\n' "${RESPONSE%$'\n'*}" "$HTTP_STATUS"
  case "$HTTP_STATUS" in 2??) ;; *) exit 1 ;; esac
)
  1. After publication succeeds, set the pipeline as the default.

(
  set +x
  set -e -o pipefail
  : "${APPBASE_ENDPOINT:?Set APPBASE_ENDPOINT to the target API endpoint including /v1}"
  : "${APPBASE_PROJECT_ID:?Set APPBASE_PROJECT_ID}"
  : "${APPBASE_CONSOLE_SESSION:?Set APPBASE_CONSOLE_SESSION}"
  APPBASE_ENDPOINT="${APPBASE_ENDPOINT%/}"
  RESPONSE="$(builtin printf 'Cookie: %s\n' "$APPBASE_CONSOLE_SESSION" | curl --disable --header @- -sS -w '\n%{http_code}' -X PUT "${APPBASE_ENDPOINT}/memory/pipelines/default" \
    -H "X-Appwrite-Project: ${APPBASE_PROJECT_ID}" \
    -H "X-Appwrite-Mode: admin" \
    -H "Content-Type: application/json" \
    --data '{"scenario":"forgetting","pipelineId":"<PIPELINE_ID_FROM_RESPONSE>","expectedRevision":2}')"
  HTTP_STATUS="${RESPONSE##*$'\n'}"
  builtin printf '%s\nHTTP %s\n' "${RESPONSE%$'\n'*}" "$HTTP_STATUS"
  case "$HTTP_STATUS" in 2??) ;; *) exit 1 ;; esac
)

2. Detailed Explanation of the Five Core Configuration Namespaces and Optimistic Concurrency Control

In memory → Configuration → Basic configuration, project configuration is organized into 5 major business namespaces (plus the underlying runtime retrieval fusion namespace):

Namespace (namespace)Core responsibilitiesKey configuration fields and production-recommended valuesFailure policy
providerModel providers and default routing for the five model classesembeddingProviderRef / embeddingModel (text-embedding-v3) / embeddingDims (1024, locked as immutable); sparseEmbeddingEnabled (true); llmProviderRef / chatModel (qwen-plus); structuredOutputMode ("tool_call"); rerankModel (qwen3.7-text-rerank); visionModel (qwen-vl-max).Fail-closed (reject calls when routing is invalid)
policyCapture strategy, search enhancement, observability sampling, and adaptive forgetting- rerankEnabled (search reranking switch, default false), profileRewriteEnabled (profile rewriting switch, default false), autoProfileExtractionEnabled (automatic profile), requestAuditEnabled (request audit, default true);
- observability: enabled, captureContent, successSampleRate, slowThresholdMs;
- forgetting: enabled (true), permanent_forgetting_enabled (false), minimum_protection_hours (168), working_threshold (0.3), short_term_threshold, long_term_threshold.
Core access policy Fail-closed
promptProject-level prompt overrides per stagefactExtractionPrompt, memoryUpdatePrompt, profileExtractionPrompt, profileRebuildPrompt, queryRewritePrompt, skillDistillationPrompt, skillMergePrompt, experienceDistillationPrompt, experienceMergePrompt, evolutionValidationPrompt, contextAggregationPrompt, promptVersion.For nodes migrated into a custom Pipeline, its published version takes precedence
retentionPhysical retention days for various data and task receiptsdefaultDays (default retention days), factDays (fact memory retention days), conversationDays (conversation memory retention days), auditEventDays (audit event retention days), terminalJobDays (finished asynchronous task retention days), idempotencyReceiptDays (idempotency receipt retention days).Expired data immediately becomes invisible online; background asynchronous cleanup follows
evolutionExperience/skill activation thresholds and Dreaming context schedulingenabled, autoDistillEnabled, requireConfirmation (self-evolution secondary confirmation, default false), allowSingleVerifiedUserActivation, crossUserPromotionEnabled; activation (minConfidence, minIndependentSessionsForAgent, requireVerifiedSuccess); retrieval (experienceTopK, skillTopK, maxTokens); dreaming (enabled, mode, batchSize, minimumChanged).Fail-closed (remains shadow until thresholds are met)

Additional note (runtime namespace): The system also supports tuning the underlying retrieval fusion parameters via /v1/projects/{projectId}/memory/config/runtime, such as recallFusion.method, rrfK, weights (dense / sparse / keyword / graph four-way weights), candidateThresholds, and queryEmbeddingCache.maxEntries.

3. Optimistic Concurrency Control (expectedConfigVersion + If-Match) and Configuration Rollback

To prevent silent overwrites when multiple administrators modify configuration simultaneously, all configuration namespaces enforce strict optimistic concurrency locks with HTTP conditional request header support:

Use a Console session with administrative access. Explicitly set APPBASE_ENDPOINT (including /v1), APPBASE_PROJECT_ID, and APPBASE_CONSOLE_SESSION for the target environment. Run these steps separately in the same session; update only after a successful read and review of the configuration.

Read the current configuration.

: "${APPBASE_ENDPOINT:?Set APPBASE_ENDPOINT to the target API endpoint including /v1}"
: "${APPBASE_PROJECT_ID:?Set APPBASE_PROJECT_ID}"
APPBASE_ENDPOINT="${APPBASE_ENDPOINT%/}"
# 1. Read the current editable retention configuration and versions
unset RETENTION_RESP RET_VER RET_SCHEMA RET_ETAG RET_VALUE
if RETENTION_RESP="$(
  set +x
  set -e -o pipefail
  : "${APPBASE_CONSOLE_SESSION:?Set APPBASE_CONSOLE_SESSION}"
  builtin printf 'Cookie: %s\n' "$APPBASE_CONSOLE_SESSION" | curl --disable --header @- -fsS "${APPBASE_ENDPOINT}/projects/${APPBASE_PROJECT_ID}/memory/config/retention" \
  -H "X-Appwrite-Project: ${APPBASE_PROJECT_ID}" \
  -H "X-Appwrite-Mode: admin")"; then
RET_VER="$(printf '%s' "${RETENTION_RESP}" | jq -er '.configVersion')" &&
RET_SCHEMA="$(printf '%s' "${RETENTION_RESP}" | jq -er '.schemaVersion')" &&
RET_ETAG="$(printf '%s' "${RETENTION_RESP}" | jq -er '.etag')" &&
RET_VALUE="$(printf '%s' "${RETENTION_RESP}" | jq -ec '.editableValue | objects')"
else
  builtin printf 'Failed to read retention configuration\n' >&2
  false
fi

Update only after confirming the target.

(
  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_PROJECT_ID:?Set APPBASE_PROJECT_ID}"
: "${APPBASE_CONSOLE_SESSION:?Set APPBASE_CONSOLE_SESSION}"
APPBASE_ENDPOINT="${APPBASE_ENDPOINT%/}"
: "${RET_VER:?Read the current retention configuration first}"
: "${RET_SCHEMA:?Read the current retention configuration first}"
: "${RET_ETAG:?Read the current retention configuration first}"
: "${RET_VALUE:?Read the current retention configuration first}"
# 2. Preserve existing fields and update only the intended retention days
UPDATE_BODY="$(jq -n --argjson version "${RET_VER}" --argjson schema "${RET_SCHEMA}" \
  --argjson value "${RET_VALUE}" \
  '{expectedConfigVersion: $version, schemaVersion: $schema,
    reason: "Update retention periods", value: ($value | .factDays = 365 | .auditEventDays = 90)}')"
: "${UPDATE_BODY:?Failed to construct the request}"
builtin printf 'Cookie: %s\n' "$APPBASE_CONSOLE_SESSION" | curl --disable --header @- -fsS -X PUT "${APPBASE_ENDPOINT}/projects/${APPBASE_PROJECT_ID}/memory/config/retention" \
  -H "X-Appwrite-Project: ${APPBASE_PROJECT_ID}" \
  -H "X-Appwrite-Mode: admin" \
  -H "If-Match: ${RET_ETAG}" \
  -H "Content-Type: application/json" --data "${UPDATE_BODY}" | jq .
)

Inspect a historical diff when needed.

(
  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_PROJECT_ID:?Set APPBASE_PROJECT_ID}"
: "${APPBASE_CONSOLE_SESSION:?Set APPBASE_CONSOLE_SESSION}"
APPBASE_ENDPOINT="${APPBASE_ENDPOINT%/}"
# 3. Select two IDs from the history list and inspect their diff
: "${FROM_HISTORY_ID:?Set the source history ID}"
: "${TO_HISTORY_ID:?Set the target history ID}"
builtin printf 'Cookie: %s\n' "$APPBASE_CONSOLE_SESSION" | curl --disable --header @- -fsS -G "${APPBASE_ENDPOINT}/projects/${APPBASE_PROJECT_ID}/memory/config/retention/history/${FROM_HISTORY_ID}/diff" \
  --data-urlencode "toHistoryId=${TO_HISTORY_ID}" \
  -H "X-Appwrite-Project: ${APPBASE_PROJECT_ID}" \
  -H "X-Appwrite-Mode: admin" | jq .
)

FAQ (Frequently Asked Questions and Troubleshooting)

1. Why does clicking the “Publish” button in a custom Pipeline prompt that it cannot be published?

2. What is the impact of toggling the “Permanent forgetting (permanent_forgetting_enabled)” switch? Does it affect user-initiated deletion (DELETE)?

3. After modifying the default memory-addition Pipeline or system prompts, are previously written old memories automatically re-extracted?


Pipeline comparison trials

Compare saved Pipeline versions from the same scenario against fixed samples. The scenarios are add_memory, profile, distillation and forgetting. A trial accepts 1–8 candidates and 1–20 uniquely identified samples. Candidate configuration and inputs are frozen on acceptance; later draft changes do not alter that run.

Trials do not write business memories but can invoke models. Compare candidate results, errors and cost before choosing a configuration to publish. Acceptance only means queued; wait for terminal state. Trial access uses projects.read/projects.write, rather than memories.read alone.