Skip to main content

Memory

Use Bailian CLI to add and search long-term memory, manage memory nodes and profile schemas, read user profiles, and export skill memories.

Long-term memory capabilities are currently available only to China site (aliyun.com) accounts.
Append --help to any command for full parameter details, e.g. bl memory search --help. High-risk delete operations are blocked unless --yes is explicitly passed (exit code 7); use --dry-run to preview the request instead. Command details are verified against bl 2.5.1.
The commands on this page apply to Bailian CLI 2.5.0 and later. Version 2.5.0 introduced breaking changes to the Memory commands; if you are upgrading from an earlier version, check the Changelog first. For memory concepts, billing, and APIs, see Memory Overview. This page is a command reference. For task-based workflows, see Use Memory with the CLI.

Configure the workspace

Memory commands call the memory API through a workspace-specific endpoint, so every command requires a workspace ID, and the API key must belong to the same workspace. To get the workspace ID, see Authentication. Provide the workspace ID in any of the following ways, listed from highest to lowest priority:
  • The --workspace-id <id> flag
  • The BAILIAN_WORKSPACE_ID environment variable
  • The workspace_id config field, e.g. bl config set workspace_id <id>
export DASHSCOPE_API_KEY='<your-api-key>'
export BAILIAN_WORKSPACE_ID='<your-workspace-id>'
The memory API is rate-limited per Alibaba Cloud account: add 120 QPM, search 300 QPM, and 3000 QPM across all memory APIs. On HTTP 429, back off and retry, leaving at least 1 second between calls. See Rate Limits.

Command reference

CapabilityCommandDescription
Add and searchbl memory addExtract memory from messages, or store custom content verbatim (async extraction)
bl memory searchSearch memory nodes by query text or conversation context
Memory node managementbl memory listList a user's memory nodes page by page
bl memory node showShow the full details of a single memory node
bl memory updateUpdate the content of a memory node
bl memory deleteDelete a single memory node
Profile schemas and user profilesbl memory profile createCreate a profile schema
bl memory profile listList profile schemas page by page
bl memory profile showShow a profile schema definition with attribute IDs
bl memory profile updateUpdate a profile schema, extraction scene, or plan version
bl memory profile deleteDelete a profile schema
bl memory profile getGet the user profile extracted under a schema
Skill memorybl memory skill exportExport a skill memory node
The flag tables below omit --workspace-id, --api-key, and global flags such as --output and --dry-run.

bl memory add

Add memory from messages or custom content. The command submits an async extraction task, then polls it locally until every task finishes or the wait budget runs out. Syntax 
bl memory add --user-id <id> [--messages <json>] [--content <text>] [flags]
FlagTypeRequiredDescription
--user-id <id>stringYesMemory entity ID that owns the memory
--messages <json>stringNoMessages JSON array, e.g. [{"role":"user","content":"..."}]. role supports user, assistant, and tool; OpenAI tool_calls are supported. Up to 50 messages
--content <text>stringNoCustom content to store verbatim. If --messages is also passed, the server uses --content
--profile-schema <id>stringNoProfile schema ID. Without it, no user profile is extracted
--extract-mode <profile_only>stringNoExtract only the user profile. Requires --profile-schema and --messages; cannot be used with --content
--skill-name <name>stringNoSkill name for skill memory. Must be passed together with --skill-description and --skill-tags
--skill-description <text>stringNoSkill description for skill memory. Must be passed together with --skill-name and --skill-tags
--skill-tags <tag>arrayNoSkill tag; repeatable. Must be passed together with --skill-name and --skill-description
--meta-data <json>stringNoCustom metadata JSON object, e.g. {"location_name":"Beijing"}
--wait <seconds>numberNoPolling budget in seconds. Default: 120. Set to 0 to return the event_id right after submission
--project-id <id>arrayNoMemory fragment rule ID; repeatable. Message extraction accepts up to 5; custom content accepts 1
--library-id <id>stringNoMemory library ID. Default: the account's default library
Examples 
# Store a known fact and wait for extraction to finish
bl memory add --user-id user1 --content "The user likes cycling" --output json

# Extract fact memory from a conversation
bl memory add --user-id user1 --messages '[{"role":"user","content":"I live in Hangzhou and go cycling on weekends."}]'

# Submit only, without waiting for extraction
bl memory add --user-id user1 --content "The user likes photography" --wait 0
  • Pass at least one of --content and --messages. Passing only one is recommended.
  • One call can add, update, or delete several memory nodes at once. When the wait budget runs out, the command exits with a timeout while extraction may continue in the background. Check the results with bl memory list, bl memory search, or bl memory profile get before deciding whether to resubmit.
  • --wait 0 returns only the submission receipt and event_id; it does not mean extraction is complete. event_id is not a memory node ID. Use memory_node_id from list or search results as the node ID.
  • If some extraction tasks fail, the command exits with a non-zero code, and the output may still include the results of completed tasks.
  • For adding user profiles and skill memories, see Profile schemas and user profiles and Skill memory.
Search memory nodes by query text or conversation context. Syntax 
bl memory search --user-id <id> [--query <text>] [flags]
FlagTypeRequiredDescription
--user-id <id>stringYesMemory entity ID that owns the memory
--query <text>stringNoSearch text, sent as a single user message
--messages <json>stringNoMessages JSON array for context-based search; takes precedence over --query
--top-k <n>numberNoMaximum number of results, 1–100. Default: 10
--min-score <score>numberNoMinimum similarity score, 0–1. Default: 0.3. Effective only with the pro plan
--memory-types <observation|skill>arrayNoMemory types to search; repeatable. Without it, the server searches observation only
--memory-type <observation|skill>stringNoDeprecated alias for --memory-types; cannot be combined with --memory-types
--project-ids <id>arrayNoMemory fragment rule ID; repeatable
--project-id <id>arrayNoDeprecated alias for --project-ids; cannot be combined with --project-ids
--plan-version <pro|lite>stringNoPlan version: pro (rerank on) or lite (rerank off), billed differently. Default on the server: pro
--library-id <id>stringNoMemory library ID. Default: the account's default library
Examples 
# pro plan, filtered by score threshold
bl memory search --user-id user1 --query "What sports does the user like?" --plan-version pro --min-score 0.5

# lite plan does not filter by --min-score; only the result count is limited
bl memory search --user-id user1 --query "weekend activities" --plan-version lite --top-k 5

# Search fact and skill memories by conversation context
bl memory search --user-id user1 --messages '[{"role":"user","content":"Help me summarize the meeting"}]' --memory-types observation --memory-types skill
  • Pass at least one of --query and --messages. If both are passed, --messages takes precedence.
  • Plan versions differ in search strategy and billing, so do not compare scores across plans. See Pro vs Lite.
  • An empty result is not an error. If a newly added memory is not found, first confirm that async extraction has finished, then check that --user-id, --library-id, rule IDs, and memory types match those used when adding.

Memory node management

Node IDs come from memory_node_id in list or search results.

bl memory list

List a user's memory nodes page by page. Syntax 
bl memory list --user-id <id> [flags]
FlagTypeRequiredDescription
--user-id <id>stringYesMemory entity ID that owns the memory
--page-size <n>numberNoResults per page. Default: 10
--page <n>numberNoPage number. Default: 1
--project-id <id>stringNoMemory fragment rule ID. Default: the library's default rule
--library-id <id>stringNoMemory library ID. Default: the account's default library
Examples 
bl memory list --user-id user1 --page-size 20 --page 2
bl memory list --user-id user1 --project-id <project-id> --output json
  • Without --project-id, only nodes under the default rule are listed. Nodes under other fact or skill rules require the corresponding rule ID.
  • Each call returns one page. Adjust --page to get more results.

bl memory node show

Show the full details of a single memory node, including its type, status, content, and metadata. Syntax 
bl memory node show --node-id <id> [flags]
FlagTypeRequiredDescription
--node-id <id>stringYesMemory node ID
Example 
bl memory node show --node-id <node-id> --output json
  • Before updating a node, you can use this command to check whether it is a skill memory.
  • A deleted node may still return details with status set to delete.

bl memory update

Update the content of a memory node. Syntax 
bl memory update --node-id <id> --content <text> [flags]
FlagTypeRequiredDescription
--node-id <id>stringYesMemory node ID
--content <text>stringYesNew content for the memory node, up to 512 characters
--meta-data <json>stringNoCustom metadata JSON object, merged incrementally, e.g. {"key":"value"}
--skill-name <name>stringNoSkill name for skill memory. Must be passed together with --skill-description and --skill-tags
--skill-description <text>stringNoSkill description for skill memory. Must be passed together with --skill-name and --skill-tags
--skill-tags <tag>arrayNoSkill tag; repeatable. Must be passed together with --skill-name and --skill-description
--library-id <id>stringNoMemory library ID. Default: the account's default library
Example 
bl memory update --node-id <node-id> --content "The user now prefers swimming" --meta-data '{"source":"user_correction"}'
  • --content replaces the node content in full, --meta-data is merged incrementally, and the node's original timestamps are kept.
  • If the target node is a skill memory, you must pass --skill-name, --skill-description, and --skill-tags even if you only change the content.
  • This command does not update extracted user profiles.

bl memory delete

Delete a single memory node. Syntax 
bl memory delete --node-id <id> [flags]
FlagTypeRequiredDescription
--node-id <id>stringYesMemory node ID
--library-id <id>stringNoMemory library ID. Default: the account's default library
--yesswitchRequired to executeConfirm the deletion. Not required with --dry-run
Examples 
bl memory delete --node-id <node-id> --dry-run
# Run after confirming the node ID
bl memory delete --node-id <node-id> --yes
  • Only the specified node is deleted. Extracted user profile values and profile schemas are not deleted, and the user's other memories are kept.
  • After deletion, the node details may still show status as delete. Use list and search results to confirm the deletion.

Profile schemas and user profiles

A profile schema defines the attributes to extract and can be shared by multiple users. A user profile holds the attribute values extracted for one user under one schema. For the full workflow, see Use user profiles.

bl memory profile create

Create a profile schema. Syntax 
bl memory profile create --name <name> --attributes <json> [flags]
FlagTypeRequiredDescription
--name <name>stringYesSchema name
--description <text>stringNoSchema description
--attributes <json>stringYesAttributes JSON array, e.g. [{"name":"age","description":"age","default_value":"18"}]. Each attribute requires name; description and default_value are optional
--plan-version <pro|lite>stringNoPlan version: pro (rerank on) or lite (rerank off), billed differently
--extract-scene <efficient|intelligent>stringNoExtraction scene. Default on creation: efficient
--library-id <id>stringNoMemory library ID. Default: the account's default library
Example 
bl memory profile create --name travel_profile --attributes '[{"name":"city","description":"city of residence"},{"name":"hobby","description":"hobbies"}]' --output json
Creating a schema does not extract any user profile by itself. Record the returned profile_schema_id and pass it to bl memory add with --profile-schema to extract profiles under this schema. Use the same --library-id for later adds and reads.

bl memory profile list

List profile schemas page by page. Syntax 
bl memory profile list [flags]
FlagTypeRequiredDescription
--page-size <n>numberNoResults per page. Default: 10
--page <n>numberNoPage number. Default: 1
--library-id <id>stringNoMemory library ID. Default: the account's default library
Example 
bl memory profile list --page-size 20 --page 2
This command returns schema definitions only, not users' profile values.

bl memory profile show

Show a profile schema definition with attribute IDs. Syntax 
bl memory profile show --schema-id <id> [flags]
FlagTypeRequiredDescription
--schema-id <id>stringYesProfile schema ID
--library-id <id>stringNoMemory library ID. Default: the account's default library
Example 
bl memory profile show --schema-id <schema-id> --output json
The returned attribute_id values are used by bl memory profile update to update or delete attributes.

bl memory profile update

Update the name, description, attributes, extraction scene, or plan version of a profile schema. Syntax 
bl memory profile update --schema-id <id> [flags]
FlagTypeRequiredDescription
--schema-id <id>stringYesProfile schema ID
--name <name>stringNoNew schema name
--description <text>stringNoNew schema description
--attributes-operations <json>stringNoAttribute operations JSON array, e.g. [{"op":"add","name":"plan"}]
--plan-version <pro|lite>stringNoPlan version: pro (rerank on) or lite (rerank off), billed differently
--extract-scene <efficient|intelligent>stringNoExtraction scene
--library-id <id>stringNoMemory library ID. Default: the account's default library
Examples 
# Add an attribute
bl memory profile update --schema-id <schema-id> --attributes-operations '[{"op":"add","name":"travel_style","description":"travel preference"}]'

# Preview the request before deleting an attribute
bl memory profile update --schema-id <schema-id> --attributes-operations '[{"op":"delete","attribute_id":"<attribute-id>"}]' --dry-run
  • Besides --schema-id, pass at least one field to update: --name, --description, --attributes-operations, --plan-version, or --extract-scene.
  • Each attribute operation requires op: add requires name; update and delete require attribute_id. Get attribute IDs with bl memory profile show.
  • This command changes the shared schema, not one user's profile values. A delete operation removes the attribute definition without a --yes confirmation, so check the schema with bl memory profile show and preview the request with --dry-run first.

bl memory profile delete

Delete a profile schema. Syntax 
bl memory profile delete --schema-id <id> [flags]
FlagTypeRequiredDescription
--schema-id <id>stringYesProfile schema ID
--library-id <id>stringNoMemory library ID. Default: the account's default library
--yesswitchRequired to executeConfirm the deletion. Not required with --dry-run
Examples 
bl memory profile delete --schema-id <schema-id> --dry-run
# Run after confirming the impact
bl memory profile delete --schema-id <schema-id> --yes
Deletion is irreversible: the schema and its attribute definitions are permanently removed, and profiles already extracted under this schema become unreachable for all users.

bl memory profile get

Get the user profile extracted under a profile schema. Syntax 
bl memory profile get --schema-id <id> --user-id <id> [flags]
FlagTypeRequiredDescription
--schema-id <id>stringYesProfile schema ID
--user-id <id>stringYesMemory entity ID that owns the profile
--library-id <id>stringNoMemory library ID. Default: the account's default library
Example 
# Extract the profile only, then read the result
bl memory add --user-id user1 --profile-schema <schema-id> --extract-mode profile_only --messages '[{"role":"user","content":"I live in Hangzhou and like cycling."}]'
bl memory profile get --schema-id <schema-id> --user-id user1 --output json
  • Attribute values are extracted only after messages have been added with bl memory add --profile-schema using the same schema ID; otherwise every attribute comes back empty.
  • User profile values are updated through message extraction. The CLI does not provide commands to edit or delete a single attribute value directly, or to clear one user's profile.

Skill memory

Skill memory is a memory type in the memory library. Adding, searching, and updating skill memories use the add, search, and update commands, scoped by the ID of a skill-type memory fragment rule. The CLI does not provide commands to create or manage rules, so use an existing rule ID. 
# Add a skill memory: pass the skill rule ID and the full skill name, description, and tags
bl memory add --user-id user1 --content "Summarize meeting notes: extract topics, decisions, action items, and owners" --project-id <skill-project-id> --skill-name meeting-summary --skill-description "Summarize meeting action items" --skill-tags office --skill-tags meeting

# Search skill memories: the memory type must be specified explicitly
bl memory search --user-id user1 --query "summarize meeting notes" --memory-types skill --project-ids <skill-project-id>

bl memory skill export

Export a skill memory node. Syntax 
bl memory skill export --node-id <id> [flags]
FlagTypeRequiredDescription
--node-id <id>stringYesSkill memory node ID
Examples 
bl memory skill export --node-id <skill-node-id> --output text > meeting-summary.md
bl memory skill export --node-id <skill-node-id> --output json > meeting-summary.json
  • Text output is the skill body without frontmatter. JSON output also includes skill_name, skill_description, and skill_tags.
  • The command does not write files directly; use shell redirection to save the output. Exporting does not install the skill into any Agent.