/alibabacloud-bailian-memory

name: alibabacloud-bailian-memory
description: |
  Manages conversation memories and user profiles in Alibaba Cloud Bailian (Model Studio)
  Memory Library via DashScope REST APIs. Covers memory extraction from conversations,
  direct content saving, semantic memory search, memory fragment maintenance,
  user profile queries and updates, plus memory project and profile schema administration.
  Use when the user requests memory library ("记忆库") operations
  such as "add memory", "search memory" or "user profile".
  Prerequisites: (1) Configure DashScope API Key (2) Activate Bailian Memory Library service.
  Do NOT use for Bailian RAG knowledge base retrieval or document search.

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](https://bailian.console.aliyun.com/cn-beijing/?tab=app#/memory/list) for that.

**Key Concepts:**

| Concept | Description | |---------|-------------| | Memory Library (`memory_library_id`) | Container for managing memories. Each account has a default library; omit the ID to use it. | | Memory Fragment (`memory_node_id`) | Key events/info extracted from conversations (e.g., "User needs daily reminders"). | | Memory Project (`project_id`) | Second-level memory isolation. Each project has a `plan_version` (pro/lite) setting. Created and managed via this skill (workflow 11). | | Memory Entity (`user_id`) | Identifier for the memory owner. Used for memory isolation between users. | | Profile Schema (`profile_schema_id`) | Template defining which user attributes to extract. Created and managed via this skill (workflow 12); an `immutable` attribute keeps its `default_value` and is never changed by extraction. | | Async Event (`event_id`) | Handle of a background extraction task created by add-async; one record per resource with status `PENDING`/`SUCCEEDED`/`FAILED`; after `SUCCEEDED` the record carries a `result[]` array describing applied changes. |

Security Tiers

| Tier | Operations | Agent behavior | |------|-----------|----------------| | 🟢 Read-only | search, list, get node, get event, get profile, list/get project, list schema | Execute directly, no confirmation needed | | 🟡 Write | add (messages/content), update memory, profile value ops (add/update/delete item), create/update project, create/update schema | Show the content/values/settings to be written, then execute; for update ops, get/list current state first | | 🔴 Destructive | delete memory | **Follow the mandatory delete flow below** |

🔴 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-" <output_directory>/` 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 Clo