Memory

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

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.

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

Capability	Command	Description
Add and search	bl memory add	Extract memory from messages, or store custom content verbatim (async extraction)
	bl memory search	Search memory nodes by query text or conversation context
Memory node management	bl memory list	List a user's memory nodes page by page
	bl memory node show	Show the full details of a single memory node
	bl memory update	Update the content of a memory node
	bl memory delete	Delete a single memory node
Profile schemas and user profiles	bl memory profile create	Create a profile schema
	bl memory profile list	List profile schemas page by page
	bl memory profile show	Show a profile schema definition with attribute IDs
	bl memory profile update	Update a profile schema, extraction scene, or plan version
	bl memory profile delete	Delete a profile schema
	bl memory profile get	Get the user profile extracted under a schema
Skill memory	bl memory skill export	Export a skill memory node

The flag tables below omit --workspace-id, --api-key, and global flags such as --output and --dry-run.

Add and search

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]

Flag	Type	Required	Description
--user-id <id>	string	Yes	Memory entity ID that owns the memory
--messages <json>	string	No	Messages JSON array, e.g. [{"role":"user","content":"..."}]. role supports user, assistant, and tool; OpenAI tool_calls are supported. Up to 50 messages
--content <text>	string	No	Custom content to store verbatim. If --messages is also passed, the server uses --content
--profile-schema <id>	string	No	Profile schema ID. Without it, no user profile is extracted
--extract-mode <profile_only>	string	No	Extract only the user profile. Requires --profile-schema and --messages; cannot be used with --content
--skill-name <name>	string	No	Skill name for skill memory. Must be passed together with --skill-description and --skill-tags
--skill-description <text>	string	No	Skill description for skill memory. Must be passed together with --skill-name and --skill-tags
--skill-tags <tag>	array	No	Skill tag; repeatable. Must be passed together with --skill-name and --skill-description
--meta-data <json>	string	No	Custom metadata JSON object, e.g. {"location_name":"Beijing"}
--wait <seconds>	number	No	Polling budget in seconds. Default: 120. Set to 0 to return the event_id right after submission
--project-id <id>	array	No	Memory fragment rule ID; repeatable. Message extraction accepts up to 5; custom content accepts 1
--library-id <id>	string	No	Memory 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.

bl memory search

Search memory nodes by query text or conversation context.

Syntax

bl memory search --user-id <id> [--query <text>] [flags]

Flag	Type	Required	Description
--user-id <id>	string	Yes	Memory entity ID that owns the memory
--query <text>	string	No	Search text, sent as a single user message
--messages <json>	string	No	Messages JSON array for context-based search; takes precedence over --query
--top-k <n>	number	No	Maximum number of results, 1–100. Default: 10
--min-score <score>	number	No	Minimum similarity score, 0–1. Default: 0.3. Effective only with the pro plan
--memory-types <observation|skill>	array	No	Memory types to search; repeatable. Without it, the server searches observation only
--memory-type <observation|skill>	string	No	Deprecated alias for --memory-types; cannot be combined with --memory-types
--project-ids <id>	array	No	Memory fragment rule ID; repeatable
--project-id <id>	array	No	Deprecated alias for --project-ids; cannot be combined with --project-ids
--plan-version <pro|lite>	string	No	Plan version: pro (rerank on) or lite (rerank off), billed differently. Default on the server: pro
--library-id <id>	string	No	Memory 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]

Flag	Type	Required	Description
--user-id <id>	string	Yes	Memory entity ID that owns the memory
--page-size <n>	number	No	Results per page. Default: 10
--page <n>	number	No	Page number. Default: 1
--project-id <id>	string	No	Memory fragment rule ID. Default: the library's default rule
--library-id <id>	string	No	Memory 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]

Flag	Type	Required	Description
--node-id <id>	string	Yes	Memory 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]

Flag	Type	Required	Description
--node-id <id>	string	Yes	Memory node ID
--content <text>	string	Yes	New content for the memory node, up to 512 characters
--meta-data <json>	string	No	Custom metadata JSON object, merged incrementally, e.g. {"key":"value"}
--skill-name <name>	string	No	Skill name for skill memory. Must be passed together with --skill-description and --skill-tags
--skill-description <text>	string	No	Skill description for skill memory. Must be passed together with --skill-name and --skill-tags
--skill-tags <tag>	array	No	Skill tag; repeatable. Must be passed together with --skill-name and --skill-description
--library-id <id>	string	No	Memory 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]

Flag	Type	Required	Description
--node-id <id>	string	Yes	Memory node ID
--library-id <id>	string	No	Memory library ID. Default: the account's default library
--yes	switch	Required to execute	Confirm 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]

Flag	Type	Required	Description
--name <name>	string	Yes	Schema name
--description <text>	string	No	Schema description
--attributes <json>	string	Yes	Attributes 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>	string	No	Plan version: pro (rerank on) or lite (rerank off), billed differently
--extract-scene <efficient|intelligent>	string	No	Extraction scene. Default on creation: efficient
--library-id <id>	string	No	Memory 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]

Flag	Type	Required	Description
--page-size <n>	number	No	Results per page. Default: 10
--page <n>	number	No	Page number. Default: 1
--library-id <id>	string	No	Memory 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]

Flag	Type	Required	Description
--schema-id <id>	string	Yes	Profile schema ID
--library-id <id>	string	No	Memory 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]

Flag	Type	Required	Description
--schema-id <id>	string	Yes	Profile schema ID
--name <name>	string	No	New schema name
--description <text>	string	No	New schema description
--attributes-operations <json>	string	No	Attribute operations JSON array, e.g. [{"op":"add","name":"plan"}]
--plan-version <pro|lite>	string	No	Plan version: pro (rerank on) or lite (rerank off), billed differently
--extract-scene <efficient|intelligent>	string	No	Extraction scene
--library-id <id>	string	No	Memory 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]

Flag	Type	Required	Description
--schema-id <id>	string	Yes	Profile schema ID
--library-id <id>	string	No	Memory library ID. Default: the account's default library
--yes	switch	Required to execute	Confirm 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]

Flag	Type	Required	Description
--schema-id <id>	string	Yes	Profile schema ID
--user-id <id>	string	Yes	Memory entity ID that owns the profile
--library-id <id>	string	No	Memory 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]

Flag	Type	Required	Description
--node-id <id>	string	Yes	Skill 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.