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 control hub of Agentbase Memory (v2.10.0). 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.

In the flagship project 企业智能客服与知识中台 (enterprise-ai-hub-210) of Agentbase 企业智能中台 (69c6d1aa00062e6bb60), administrators customized a fact extraction pipeline for intelligent customer service via a custom Pipeline, specifically extracting ticket numbers, OceanBase cluster versions, and SLA tiers, and finely managed the 168-hour new-memory protection period and compliance retention cycle through the policy and retention namespaces.


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
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 .../config/{namespace}/history, /diff, POST .../rollbackprojects.read / projects.write

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 (reusing a registered screenshot)

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

  1. Select the business scenario you want to adjust (e.g., Add Memory Pipeline), and click Create Pipeline from Default (corresponding to POST /v1/memory/pipelines with {"scenario": "add_memory", "fromDefaults": true}).

  2. Expand the pipeline node you want to customize (e.g., Fact Extraction fact_extraction):

    • Click View Built-in Default Prompt below the prompt input box to view and one-click copy the platform's built-in base prompt template (viewing or copying does not automatically modify the current draft; the system also automatically appends non-overridable safety protocol rules at runtime);

    • Modify the extraction instructions, the maximum facts per extraction (maxFacts), or the model routing used by the node to suit your enterprise customer service scenario.

  3. Click Save Draft at the top of the editor (the editor top also provides Duplicate Saved Draft and Delete Pipeline buttons).

Memory pipeline draft view (reusing a registered screenshot)

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

  1. Run sample validation (Dry-run):

    • After the draft is saved, enter a test message or target user ID in the sample area on the right or below, and click Run Sample (calls POST /v1/memory/pipelines/{pipelineId}/validate);

    • The currently saved draft version must successfully pass a sample validation once before the system allows publishing. The audit of sample requests records only the Pipeline ID, version, and result status; the original sample input is never saved.

  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.

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 / If-None-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:

# Example: update a retention policy using expectedConfigVersion and If-Match, and query the version Diff
export APPBASE_ENDPOINT="https://appbuild.oceanbase.com/v1"
export APPBASE_PROJECT_ID="enterprise-ai-hub-210"

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

RET_VER="$(echo "${RETENTION_RESP}" | jq -er '.version')"
RET_ETAG="$(grep -i '^etag:' /tmp/retention_headers.txt | awk '{print $2}' | tr -d '\r')"

# 2. Optimistically update the retention days with expectedConfigVersion and If-Match
curl -fsS -X PUT "${APPBASE_ENDPOINT}/projects/${APPBASE_PROJECT_ID}/memory/config/retention" \
  -H "Cookie: ${APPBASE_CONSOLE_SESSION}" \
  -H "X-Appwrite-Project: ${APPBASE_PROJECT_ID}" \
  -H "X-Appwrite-Mode: admin" \
  -H "If-Match: ${RET_ETAG}" \
  -H "Content-Type: application/json" \
  --data "{
    \"expectedConfigVersion\": ${RET_VER},
    \"reason\": \"按企业合规要求将事实记忆保留期设为 365 天,审计保留期设为 90 天\",
    \"value\": {
      \"defaultDays\": 180,
      \"factDays\": 365,
      \"conversationDays\": 90,
      \"auditEventDays\": 90,
      \"terminalJobDays\": 14,
      \"idempotencyReceiptDays\": 7
    }
  }" | jq .

# 3. Compare version differences (Diff)
curl -fsS "${APPBASE_ENDPOINT}/projects/${APPBASE_PROJECT_ID}/memory/config/retention/diff?fromVersion=${RET_VER}&toVersion=$((RET_VER + 1))" \
  -H "Cookie: ${APPBASE_CONSOLE_SESSION}" \
  -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?