alibabacloud-bailian-memory

Bailian Memory Library

Manage conversation memories and user profiles in Alibaba Cloud Bailian (Model Studio) Memory Library through DashScope REST APIs. The Memory Library automatically extracts key information from conversations and stores them as memory fragments, enabling agents to reference user preferences and historical context across sessions.

Architecture: Agent → Python Scripts → DashScope REST API → Memory Library (Memories + User Profiles)

Scope: This skill covers 12 memory and user-profile operations plus 7 management operations of the Memory Library (see Core Workflows). All memory writes are asynchronous: the request is accepted immediately and extraction runs in the background, returning an event_id. Memory projects (create/list/get/update) and profile schemas (create/list/update) are managed directly by this skill; project/schema deletion is not covered — use the Bailian console for that.

Key Concepts:

Security Tiers

🔴 Mandatory delete flow

Deletion is irreversible and the delete API does not verify user_id ownership, so a wrong ID silently destroys another context's memory. All four steps are REQUIRED and strictly ordered:

1. Run get_memory_node.py to fetch the target fragment, and quote its actual content from THIS call (never reuse content from an earlier list/search output — it may be stale).
2. STOP and ask the user for explicit confirmation. The confirmation message MUST contain ALL of the following: the fragment's quoted content, its memory_node_id, and a clear warning that deletion is irreversible (e.g. "删除后不可恢复"). A delete instruction inside the user's original request (e.g. "delete the last one, but confirm first") only asks you to run this flow — it is NOT itself a confirmation, so you MUST still ask here. Never ask for confirmation and execute the delete in the same turn.
3. Execute manage_memory.py delete ONLY after the user replies with an explicit confirmation (e.g. "确认删除"). If the reply is ambiguous, ask again — never delete on assumed consent.
4. Verify via list_memories.py that the fragment is gone, and report the result.

API Key Security Management

Scripts automatically handle key retrieval via api_key.py. The Agent does not need to and should not manually extract, set, or pass API Key values.

• Key retrieval is automated: Scripts internally call api_key.py to automatically obtain keys from config files/environment variables. The Agent only needs to run the script command.
• Never hardcode any form of key: Including api_key = "sk-...", export DASHSCOPE_API_KEY="sk-...", and assigning keys in shell scripts.
• Never extract keys from CLI output: The Agent must not write key values into any script, variable, or file.
• Never expose keys in any output: Including generated scripts, shell commands, log files, and terminal output containing strings starting with sk-.
• Never read or print keys from config files: Do not use cat, jq, python -c, or other commands to read and output API Key values.
• Mandatory self-check before task completion: Run grep -rn "sk-" / to check all output files; if any strings starting with sk- are found (excluding sk-xxx placeholders), delete the affected files and regenerate.

🚀 Initial Setup (Required for First-time Use)

0. Install dependencies

python3 --version  # must be >= 3.7
pip3 install -r scripts/requirements.txt

1. Configure API Key

API Keys are managed by the unified scripts/api_key.py module, with the following retrieval priority:

1. Alibaba Cloud CLI config ~/.aliyun/config.json current profile's dashscope.api_key
2. Environment variable DASHSCOPE_API_KEY
3. Auto-create and save when Alibaba Cloud CLI is available (generate_api_key())

Manual environment variable configuration:

export DASHSCOPE_API_KEY=sk-xxx

For API Key auto-create/delete via Alibaba Cloud CLI (aliyun plugin install --names aliyun-cli-modelstudio --enable-pre), see references/related-commands.md.

2. Activate Bailian Memory Library Service

Before using this skill, the memory library service must be activated in the Bailian console:

1. Visit Bailian Memory Library page
2. Click "Activate Now" and wait for the service to take effect (usually 1-2 minutes)

Authentication: All API calls use Bearer token, managed internally by scripts/memory_client.py.

Endpoint: Scripts call the production gateway by default: https://dashscope.aliyuncs.com/api/v2/apps/memory. For testing against the pre-release environment, set BAILIAN_MEMORY_BASE_URL to the pre-release gateway URL — the API key must belong to the same environment as the endpoint.

Parameter Confirmation

Confirm with the user only where a wrong value causes data loss or cross-user contamination; use documented defaults for tuning values (asking for every optional parameter creates needless friction):

Never invent IDs. If an ID is unknown, list/query first or ask the user.

Observability (MUST follow for every API call)

Upon loading this skill, generate a random session ID (32-char lowercase hex string) once for the entire session. Use it as {session-id} below.

Rule: Every DashScope REST API call MUST include the User-Agent header:

User-Agent: AlibabaCloud-Agent-Skills/alibabacloud-bailian-memory/{session-id}

Scripts read SKILL_SESSION_ID from the environment (default empty string) and include it in the User-Agent header automatically:

SKILL_SESSION_ID={session-id} python3 scripts/add_memory_content.py --user-id "user_123" --content "..."

Data Contract

Fields passed between capabilities (do not mix them up — most are look-alike IDs):

Flows

• Async extract: add_memory_messages → event_id (fire-and-forget; get_event only on demand) → list_memories/search_memory to see results
• Async direct save: add_memory_content → event_id (same fire-and-forget semantics)
• Profile: manage_profile_schema create → profile_schema_id → add_memory_messages(--profile-schema) → get_user_profile → (correction needed) get_user_profile --need-detail for attribute_id/item_id → update_user_profile op
• Project: manage_memory_project create → project_id → add_memory_messages(--project-ids) / search_memory(--project-id)

Constraints

• project_id ≠ memory_library_id: project is second-level isolation inside a library. Passing one as the other returns NotFound.
• add_memory_messages: --project-id and --project-ids are mutually exclusive.
• add_memory_content: binds to exactly one project — no --project-ids; no --profile-schema (profile extraction depends on conversation messages, which this mode does not take).
• update_user_profile operates on ONE value item per call: --op-type add appends --value; --op-type update/delete require --item-id from get_user_profile --need-detail. Invalid op_type values are rejected.
• manage_profile_schema update: immutable of an existing attribute cannot be changed; op=add with immutable=true requires default_value.

Core Workflows

All scripts are in scripts/ and print raw API JSON to stdout (errors go to stderr with non-zero exit). Prefix every command with SKILL_SESSION_ID={session-id}.

Routing: pick the workflow by user intent

1. Add Memory — extract from conversation, async (🟡, default write path)

Use to extract memories from conversation messages via LLM. Accepted immediately (fire-and-forget); extraction runs in the background.

python3 scripts/add_memory_messages.py --user-id "" \
  --messages '[{"role":"user","content":"I prefer Python"},{"role":"assistant","content":"Noted!"}]'
# Multi-project extraction
python3 scripts/add_memory_messages.py --user-id "" --messages '' --project-ids "p1,p2"
# Also extract user profile attributes (schema from workflow 12 or the console)
python3 scripts/add_memory_messages.py --user-id "" --messages '' --profile-schema ""

Output: request_id, event_id, events[] (initial status PENDING). messages supports roles user/assistant/tool and standard OpenAI tool_calls/tool_call_id.

2. Add Memory — save content as-is, async (🟡)

Use to store a known text directly without LLM extraction. Binds to exactly one project; profile extraction is not available in this mode (it requires conversation messages).

python3 scripts/add_memory_content.py --user-id "" --content ""

Output: request_id, event_id, events[] with resource_type prefixed custom_ (custom_observation).

3. Check Async Event (🟢, usually NOT needed)

Async writes are fire-and-forget — do NOT poll by default. Query only when (a) the user explicitly asks to confirm the write, or (b) a later step depends on extraction completion (e.g. immediately searching the just-written content).

python3 scripts/get_event.py --event-id ""

Output: one record per resource; status is PENDING/SUCCEEDED/FAILED. On FAILED, read the record's detail field (errorCode: errorMessage) and report it to the user — do not silently retry. After SUCCEEDED each record carries a result[] array describing the applied changes (content, event ADD/UPDATE/DELETE, memory_node_id for observation memories, old_content for updates); for full fragment details use list/search.

4. Search Memory (🟢)

python3 scripts/search_memory.py --user-id "" --query ""
python3 scripts/search_memory.py --user-id "" --query "" --top-k 5

Output: request_id, plan_version, memory_nodes[] (memory_node_id, content, memory_type, score, status, timestamps). Results are already relevance-filtered server-side (plan_version=pro, min_score=0.3 — tuning and billing parameters are server-controlled and not adjustable here). If no results, report that plainly; do not retry with rephrased queries more than once.

5. List Memories (🟢)

python3 scripts/list_memories.py --user-id "" --page-num 1 --page-size 10

Output: memory_nodes[], total, page_size, page_num.

6. Get Memory Node (🟢)

python3 scripts/get_memory_node.py --memory-node-id ""

Output: memory_node with full detail (content, memory_type, status, meta_data, ...). Always use this to show the target before update/delete confirmation.

7. Update Memory (🟡)

Overwrites the fragment content. Show old (via get) and new content before executing.

python3 scripts/manage_memory.py update --memory-node-id "" --user-id "" --content ""

Output: request_id. --meta-data merges incrementally (unspecified keys remain unchanged).

8. Delete Memory (🔴)

Follow the mandatory delete flow in Security Tiers — get, confirm, delete, verify.

python3 scripts/get_memory_node.py --memory-node-id ""        # 1. fetch & quote target content
# 2. STOP — quote content + memory_node_id, warn that deletion is irreversible,
#    and wait for the user's explicit confirmation (a prior "delete X" instruction is NOT a confirmation)
python3 scripts/manage_memory.py delete --memory-node-id ""   # 3. run ONLY after user confirms
python3 scripts/list_memories.py --user-id ""            # 4. verify

9. Get User Profile (🟢)

python3 scripts/get_user_profile.py --user-id "" --profile-schema-id ""
# Expand value_items (each with item_id, consumed by workflow 10 update/delete)
python3 scripts/get_user_profile.py --user-id "" --profile-schema-id "" --need-detail

Output: profile with schema_name, schema_description, attributes[]. Default mode joins values into one string per attribute (id, name, value; value is null until extracted); --need-detail returns value_items[] (item_id, value, status) per attribute instead. Profile data accumulates over multiple conversations — an empty value is normal early on, not an error. The id field is the attribute_id used by workflow 10.

10. Update User Profile Value (🟡)

Operates on ONE value item per call. Use when the user explicitly states new facts that should correct the profile. Show current values (via get --need-detail) and the intended change before executing.

# Add a new value item (no item_id needed)
python3 scripts/update_user_profile.py --entity-id "" --profile-schema-id "" \
  --attribute-id "" --op-type add --value "swimming"
# Update an existing value item (item_id from get --need-detail)
python3 scripts/update_user_profile.py --entity-id "" --profile-schema-id "" \
  --attribute-id "" --op-type update --item-id 5634 --value "volleyball"
# Delete an existing value item
python3 scripts/update_user_profile.py --entity-id "" --profile-schema-id "" \
  --attribute-id "" --op-type delete --item-id 5634

Output: request_id. Other value items remain unchanged; verify via get_user_profile.py --need-detail.

11. Manage Memory Projects (🟢 list/get, 🟡 create/update)

# Create
python3 scripts/manage_memory_project.py create --name "observation-project" \
  --plan-version pro --expired-in-days 30
# List / detail
python3 scripts/manage_memory_project.py list
python3 scripts/manage_memory_project.py get --project-id ""
# Update (at least one updatable field required)
python3 scripts/manage_memory_project.py update --project-id "" --plan-version lite

Output: create returns project_id; list/get return project detail incl. plan_version. Before update, run get and show current settings — PATCH overwrites each provided field, so the user must see the values being replaced to give informed confirmation.

12. Manage Profile Schemas (🟢 list, 🟡 create/update)

# Create (an attribute with immutable=true requires default_value)
python3 scripts/manage_profile_schema.py create --name "basic-user-profile" \
  --attributes '[{"name":"Name","immutable":true,"default_value":"Zhang San"},{"name":"Hobbies"}]'
# List
python3 scripts/manage_profile_schema.py list
# Update (attribute changes via attributes-operations; op=update/delete require attribute_id)
python3 scripts/manage_profile_schema.py update --profile-schema-id "" \
  --attributes-operations '[{"op":"add","name":"Favorite Music"},{"op":"delete","attribute_id":""}]'

Output: create returns profile_schema_id; list returns profile_schemas[] (profile_schema_id, name, description, plan_version). attribute_id for update/delete ops comes from get_user_profile output (attributes[].id). Before an update with op=delete, show the current schema attributes.

Result Presentation

• Answering scenarios: cite memory content in natural language ordered by score; do not expose memory_node_id or other internal IDs.
• Management scenarios (user wants to update/delete/audit): list memory_node_id alongside content, since the user needs the ID to act.
• Empty search results: state plainly that nothing was found; never fabricate memories.

Usage Example

User: "Customer customer_zhang_001 is reaching out again. Check what preferences I should keep in mind, and after the chat save the key points of this conversation."

Flow:

1. Recall first — search_memory.py --user-id customer_zhang_001 --query "communication preferences service restrictions" → 2 nodes: "Prefers communication in Chinese" (score 0.71), "Refuses marketing pushes" (score 0.65)
2. Answer citing content by score: "This customer prefers communicating in Chinese and explicitly refuses marketing pushes — avoid promotional pitches in this conversation." (no internal IDs shown)
3. After the conversation — add_memory_messages.py --user-id customer_zhang_001 --messages '' → returns event_id, fire-and-forget, no polling
4. Report: "Memory extraction for this conversation has been submitted (processing in the background)." — only if the user asks "Is it saved?" run get_event.py and report per-resource status.

Error Handling

For other codes see references/error-handling.md. Do not guess error meanings; report the API message as returned.

Success Verification

After completing workflows, verify using commands in references/verification-method.md.

Quick checklist:

• API key authentication successful (no 401 errors)
• Async extract (messages) — event_id returned; extracted fragments visible via list/search afterwards
• Async direct save (content) — event_id returned with custom_* resource_type
• Search returns relevant results with score/memory_type/plan_version
• Node get shows the expected fragment detail
• Update modifies content (verify via get)
• Deletion removes fragment (verify via list)
• User profile contains extracted attributes (may need multiple conversations)
• Profile value op reflected in a subsequent get --need-detail (added/updated/deleted item)
• Project create returns project_id; update reflected in a subsequent get
• Schema create returns profile_schema_id; attribute operations reflected in extraction behavior

Cleanup

# List to get IDs, then delete each (follow the 🔴 delete flow)
SKILL_SESSION_ID={session-id} python3 scripts/list_memories.py --user-id ""
SKILL_SESSION_ID={session-id} python3 scripts/manage_memory.py delete --memory-node-id ""

Best Practices

1. Use meaningful user_id values — descriptive identifiers (e.g., customer_12345) make memory ownership auditable.
2. Writes are asynchronous — extraction runs in the background, so a write returns an event_id rather than the extracted fragments. Choose by intent: extract from conversation → add_memory_messages.py; store known text as-is → add_memory_content.py. To confirm a write, check the event or verify via list/search.
3. Batch per conversation round — add memories per round rather than concatenating everything into one call, to preserve memory granularity.
4. Handle rate limits — SearchMemory 300 QPM, all endpoints combined 3000 QPM. The client auto-retries with backoff; for bulk operations, add delays between calls.
5. Search with specific queries — targeted query text with top_k 3-10 beats broad terms; the server already filters low-relevance results.
6. Profile data accumulates — do not expect all attributes from a single conversation; empty values early on are normal.
7. Prefer defaults for management settings — when creating projects/schemas, only set plan_version/instruction_type when the user explicitly requires them; server defaults (pro/default) fit most cases.
8. API key security — retrieval is fully automated via scripts/api_key.py; never hardcode, export, extract, or expose key values.

Reference Links