Docs
Contents

User Profile Extraction and Management

Feature overview and core scenarios

User Memory Profiles is the core aggregation capability of Agentbase Memory for personalized agent services. In real business scenarios, a single user often has dozens or even hundreds of fragmented individual memories (e.g., tech stack preferences, cluster modules they are responsible for, past support ticket background, communication style preferences). If each conversation only retrieves scattered memory entries, it is difficult for the agent to quickly grasp the user's overall identity characteristics. The user profile feature uses a large model (e.g., qwen-plus under dashscope-prod) and a configurable profile Pipeline to organize a user's valid sources and new conversations into highly cohesive content profile (content) and structured topics profile (topics).

In the example project 企业智能客服与知识中台 (enterprise-ai-hub-210) of Agentbase 企业智能中台 (69c6d1aa00062e6bb60), the system maintains dynamically evolving dedicated user profiles for the VIP architect user_zhangwei_001 and the front-line engineer user_lina_002:


Core Concepts and Architecture

User profiles sit above the raw memories/sources (L0/L1) and serve as the user-level global semantic view, working closely with memory retrieval (Query Rewrite profile rewriting) and agent system prompt injection.

User Profile Extraction and Management: 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

Core Concepts and Mode Comparison

Concept / operation modeParameter identifierApplicable scenarios and core technical semantics
Content ProfileprofileType: "content"A coherent, concise natural language paragraph that directly describes the user's role identity, tech stack background, communication preferences, and recent focus areas; best suited for direct inclusion in the Agent System Prompt.
Topics ProfileprofileType: "topics"A topic collection organized by structured dimensions (e.g., role function, core systems, preference constraints, recent pain points), following the structure specification defined in runtime.profileSchemaVersion.
Incremental extraction (Incremental Mode)mode: "incremental" (default)Merges the messages newly passed in this round into the user's current existing profile without deleting the old one beforehand; suitable for continuous evolution after daily conversations.
Regeneration (Replace Mode)mode: "replace"Centers on the description messages newly passed in this round, combined with the optionally passed sourceMemoryIds (at most 100 valid, unexpired memories of the same project and user), and atomically replaces the current profile and source relations within a single transaction.
Rebuild from sources (Rebuild)POST /profile/rebuildDoes not accept new message input. When the project upgrades its profile model (e.g., from qwen-turbo to qwen-plus), adjusts profileRebuildPrompt, or some underlying sources have been forgotten and cleaned up, the profile is recomputed based on the currently valid associated sources.

Feature Entrypoints and Permission Matrix

Console Entry Points and API Mapping

The Console entry point is located at: the Project enterprise-ai-hub-210 → Memory → Profiles tab.

Function actionConsole operation entryREST API endpointRequired API Key scopeRelated notes
Query user profileEnter user ID + select content / topics → QueryGET /v1/memory/memories/users/{userId}/profilememories.readA missing profile may return 404; inspect the actual error type from the target environment
Query profile sourcesSources area of profile detailsGET /v1/memory/memories/users/{userId}/profile/sourcesmemories.readDisplays the valid sources and memory associations supporting the current profile version
Incremental update / regenerationIncremental update / Regenerate operation areaPOST /v1/memory/memories/users/{userId}/profile/extractionsmemories.writeOptionally pass in the published profile pipelineId and sessionId
Rebuild from valid sourcesRebuild profile buttonPOST /v1/memory/memories/users/{userId}/profile/rebuildmemories.writeCall only on demand after the model, prompt, or underlying sources have changed
Delete a specified profile typeDelete profile buttonDELETE /v1/memory/memories/users/{userId}/profilememories.deleteOnly clears that profile type's aggregation, underlying raw memories are preserved

Synergy with Other Modules


Feature Details and Operation Guide

1. Query and manage user profiles in the Console

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

  2. Enter the target user ID in the top query bar (e.g., user_zhangwei_001 or user_lina_002), select Content (content) or Topics (topics) in the profile type, and click Query.

  3. The page displays the currently effective profile content, profile version number, last update time, and the running status of the background profile extraction task.

User profile view

Figure: A synthetic profile with Chinese example content in a 2.12.0 test project.

2. Perform incremental update (incremental) and regeneration based on evidence (replace)

Method One: Incrementally update the profile (absorbing the latest conversation dynamics)

  1. On the Profile tab action area, select Incremental Update.

  2. Enter the target user ID user_zhangwei_001, and select Use default Pipeline (or a published custom profile Pipeline) in the Pipeline dropdown.

  3. Add the new message and its role (e.g., role: "user", content: 近期我们核心账务集群正在将向量检索切换为 OceanBase 1024 维 HNSW 索引,并在 AI 网关配置了工具接入。).

  4. After submitting, inspect the actual processing result, click Query again, and review the profile and its sources.

Method Two: Regenerate the profile based on new circumstances (replace mode)

When the user's job responsibilities or system environment change significantly and the profile needs a complete refresh:

  1. Switch to Regenerate in the action area, enter the user ID user_zhangwei_001 and new background description text.

  2. Select the evidence source scope:

    • Use only this new input (corresponding to API sourceMemoryIds: []);

    • All valid memories (up to 100): the console uses records loaded in the list and excludes profile-source records; with more records this is not necessarily the user’s complete set;

    • Manually check specific memory evidence (check core memory IDs from the list as supplementary evidence).

  3. Verify and submit. The system replaces the profile content and source associations within the same database transaction; if the model call fails midway, the transaction rolls back automatically, never exposing a half-updated profile, and no underlying raw memories are deleted.

3. REST API Parameter Specification for Profile Extraction, Rebuild, and Deletion

The following is the complete parameter reference table for the /v1/memory/memories/users/{userId}/profile/* series of APIs:

API and MethodParameter NameTypeRequiredDefault ValueDetailed Description and Value Constraints
POST .../profile/extractionsmodestringNo"incremental"Value "incremental" (incremental merge) or "replace" (full replacement).
POST .../profile/extractionsprofileTypestringNo"content"Value "content" or "topics".
POST .../profile/extractionsmessagesarrayYes-Array of conversation messages for this extraction; each item contains role (user/assistant/system) and a non-empty content.
POST .../profile/extractionssourceMemoryIdsstring[]No-Only available when mode="replace"; at most 100 valid memory IDs belonging to the same project and the same user.
POST .../profile/extractionspipelineIdstringNoScenario defaultSpecifies the published profile scenario Pipeline ID for the current project; draft versions will be rejected.
POST .../profile/extractionssessionIdstringNoEmpty stringUp to 128 characters; used to associate this extraction task and its async Trace with a specified business session.
POST .../profile/rebuildprofileTypestringNo"content"Recomputes the specified profile type based on existing valid sources; does not accept messages new input.
DELETE .../profileprofileTypestringYes-Specifies the profile type to delete ("content" or "topics"); supports including reason and source for audit records.

4. Hands-on Example: Injecting the user_zhangwei_001 VIP Architect Profile into an Agent Prompt

The following demonstrates how, in an enterprise intelligent customer service backend, to use the REST API with agentbase-node-sdk@2.12.0 to extract the user_zhangwei_001 profile and dynamically inject it into the Agent Runtime or the system prompt of a large model call:

Set a unique PROFILE_IDEMPOTENCY_KEY for each new profile extraction; reuse the original key and identical request content only when retrying the same submission.

(
  set +x
  set -o pipefail
  : "${APPBASE_API_KEY:?Set API key}"
  : "${PROFILE_IDEMPOTENCY_KEY:?Set a unique key for this new extraction}"
: "${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}"
# 1. Use cURL to trigger incremental profile extraction for user_zhangwei_001
builtin printf 'X-Appwrite-Key: %s\n' "$APPBASE_API_KEY" | curl --disable --header @- -fsS -X POST "${APPBASE_ENDPOINT}/memory/memories/users/user_zhangwei_001/profile/extractions" \
  -H "X-Appwrite-Project: ${APPBASE_PROJECT_ID}" \
  -H "Idempotency-Key: ${PROFILE_IDEMPOTENCY_KEY}" \
  -H "Content-Type: application/json" \
  --data '{
    "mode": "incremental",
    "profileType": "content",
    "sessionId": "sess_ticket_TK_20261022_001",
    "messages": [
      {
        "role": "user",
        "content": "我是核心账务系统架构师张伟,目前负责 enterprise-ai-hub-210 项目的 OceanBase Shared V2 向量库与 prod-enterprise-ai-gateway 网关高可用治理,排障时请直接给出 SQL 诊断语句和网关限流参数。"
      }
    ]
  }' | jq .
)

Read the profile on the Node.js server side (using agentbase-node-sdk@2.12.0) and construct a personalized Agent Prompt:

Before running, replace <APPBASE_ENDPOINT_WITH_V1> and <APPBASE_PROJECT_ID> with the confirmed target API endpoint and project ID. Until replaced, the SDK rejects the invalid endpoint before making a request.

// Use the official server SDK: agentbase-node-sdk@2.12.0
import { Client, Memory } from 'agentbase-node-sdk';

const client = new Client()
    .setEndpoint('<APPBASE_ENDPOINT_WITH_V1>')
    .setProject('<APPBASE_PROJECT_ID>')
    .setKey(process.env.APPBASE_API_KEY);

const memory = new Memory(client);

async function buildPersonalizedSystemPrompt(userId) {
    let personaBlock = '当前用户尚无历史画像,请按标准企业技术支持 SOP 礼貌解答。';

    try {
        const profileRes = await memory.getProfile({
            userId,
            profileType: 'content'
        });
        if (profileRes?.profile?.profileContent) {
            personaBlock = [
                `【用户专属画像 (版本 v${profileRes.profile.version})】`,
                profileRes.profile.profileContent,
                '请严格遵循上述画像中的技术深度与沟通偏好进行回复,避免冗余解释。'
            ].join('\n');
        }
    } catch (err) {
        // Only an explicit profile_not_found falls back; let the caller handle other errors
        if (err.code !== 404 || err.type !== 'profile_not_found') throw err;
    }

    return `你是 Agentbase 企业智能客服专家,绑定知识库 kb_enterprise_support。\n\n${personaBlock}`;
}

// Generate a dedicated system prompt for VIP architect user_zhangwei_001
const systemPrompt = await buildPersonalizedSystemPrompt('user_zhangwei_001');

Some deployments map a missing profile to memory_not_found, which can also mean another resource is missing. The example propagates that error; verify its cause before deciding whether to use a default prompt.


FAQ (Frequently Asked Questions and Troubleshooting)

1. Why does the profile query still return 404 after I write memories for the user?

2. When should I use "Regenerate (mode=replace)" and when should I use "Rebuild Profile (/profile/rebuild)"?

3. After deleting a user's profile, will the historical memories and raw conversations under that user be deleted as well?