长期记忆 API - 阿里云百炼

核心功能

记忆库将于 2026 年 8 月 20 日 10:00（北京时间）正式商业化计费。Add 和 Search 调用区分 Pro 和 Lite 两个版本，Pro 版检索开启 Rerank 质量更高，Lite 版关闭 Rerank 成本更低。详见记忆库计费标准。

记忆片段：从对话自动提取关键内容并结构化存储为记忆片段；也可以直接指定要存入的记忆内容；支持基于历史对话检索和动态更新。
用户画像：基于自定义画像模板，从对话中提取结构化用户属性（如年龄、职业、兴趣等）。

记忆片段适用于大多数长期记忆场景；当需要抽取固定属性时，建议搭配用户画像功能使用该功能。生成的记忆片段与用户画像暂无失效日期。

适用范围

长期记忆功能通过开放的 API 接口，可接入任意应用，也支持多应用共享同一记忆库。

相比旧版长期记忆 API的改进

速度与效率高：拥有更低的延迟，更高的记忆检索召回效果。
自动提取能力：支持从对话中自动提取关键信息，自动去重，无需手动输入。
检索算法优化：新增语义检索能力，检索准确性显著提升，响应速度更快。
用户画像能力：新增完整的用户画像提取和管理能力。

使用方法

使用前需要配置环境变量DASHSCOPE_API_KEY，获取与配置方式请参考获取 API Key。

添加记忆片段
更新记忆片段
提取用户画像

建立记忆：通过 AddMemory 保存上一轮对话内容，转换为记忆片段并构建语义索引。
检索记忆：通过 SearchMemory 基于语义检索相关历史记忆。

最佳实践：在每轮对话结束后及时调用 AddMemory 保存记忆，检索时建议将 top_k 设置在 3 到 10 之间，平衡性能和效果。

cURL

# 添加记忆
curl -X POST https://dashscope.aliyuncs.com/api/v2/apps/memory/add \
  --header "Authorization: Bearer $DASHSCOPE_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "messages": [
      {"role": "user", "content": "每天上午9点提醒我喝水"},
      {"role": "assistant", "content": "好的，已记录"},
      {"role": "user", "content": "明天10点提醒我整理会议纪要。"}
    ],
    "user_id": "user_001",
    "memory_library_id": "your_memory_library_id",
    "project_id": "your_project_id",
    "profile_schema": "your_profile_schema_id",
    "meta_data": {
      "location_name": "北京"
    }
  }'
# memory_library_id：非必填，记忆库 ID，在记忆库卡片上获取。不填则使用默认记忆库。
# project_id：非必填，记忆片段规则 ID，在记忆库详情页的记忆规则中获取。
# profile_schema：非必填，用户画像规则 ID，在记忆库详情页的记忆规则中获取。不传则不提取用户画像。
# meta_data：非必填，自定义元数据，用于对记忆进行分类管理。

# 添加记忆（自定义内容）
curl -X POST https://dashscope.aliyuncs.com/api/v2/apps/memory/add \
  --header "Authorization: Bearer $DASHSCOPE_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "custom_content": "用户周末去上海参加WAIC",
    "user_id": "user_001",
    "memory_library_id": "your_memory_library_id",
    "meta_data": {
      "custom_key": "custom_value"
    }
  }'

# 搜索记忆
curl -X POST https://dashscope.aliyuncs.com/api/v2/apps/memory/memory_nodes/search \
  --header "Authorization: Bearer $DASHSCOPE_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "user_id": "user_001",
    "memory_library_id": "your_memory_library_id",
    "messages": [
      {"role": "user", "content": "我需要做什么？"}
    ],
    "top_k": 5,
    "plan_version": "pro"
  }'

管理记忆：通过 ListMemory、UpdateMemory、DeleteMemory 管理记忆片段，支持元数据分类和智能去重。最佳实践：使用元数据对记忆进行分类管理（如按类别、优先级等），便于后续的精确检索和管理。

cURL

# 添加记忆
curl -X POST https://dashscope.aliyuncs.com/api/v2/apps/memory/add \
  --header "Authorization: Bearer $DASHSCOPE_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "user_id": "user_001",
    "messages": [
      {"role": "user", "content": "每天上午9点提醒我喝水"},
      {"role": "assistant", "content": "好的，已记录"}
    ]
  }'

# 列出记忆
curl --location --request GET 'https://dashscope.aliyuncs.com/api/v2/apps/memory/memory_nodes?user_id=user_001&page_size=10&page_num=1' \
  --header "Authorization: Bearer $DASHSCOPE_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{}'

# 更新记忆
curl --location --request PATCH 'https://dashscope.aliyuncs.com/api/v2/apps/memory/memory_nodes/{memory_node_id}' \
  --header "Authorization: Bearer $DASHSCOPE_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "user_id": "user_001",
    "custom_content": "还要提醒我上午10点吃药。"
  }'

# 查看更新的记忆
curl -X POST https://dashscope.aliyuncs.com/api/v2/apps/memory/memory_nodes/search \
  --header "Authorization: Bearer $DASHSCOPE_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "user_id": "user_001",
    "memory_library_id": "your_memory_library_id",
    "messages": [
      {"role": "user", "content": "我需要做什么？"}
    ],
    "top_k": 5,
    "plan_version": "pro"
  }'

# 删除记忆
curl --location --request DELETE 'https://dashscope.aliyuncs.com/api/v2/apps/memory/memory_nodes/{memory_node_id}' \
  --header "Authorization: Bearer $DASHSCOPE_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{}'

创建画像模板：通过 CreateProfileSchema 定义需要提取的用户属性。
提取画像：调用 AddMemory 时传入画像模板 ID，从对话中提取用户属性并更新画像。
获取画像：通过 GetUserProfile 获取完整的用户画像信息。

最佳实践：画像字段及描述应该清晰、具体，避免过于抽象。属性名称应尽可能保证在语义中唯一，如["姓名"、"名称"、"名字"]、["年龄"、"年纪"、"岁数"]不应同时出现，否则会对抽取效果有一定影响。不应期望一次对话就能提取所有信息，应通过多轮对话收集。

cURL

# 创建画像 Schema
curl -X POST https://dashscope.aliyuncs.com/api/v2/apps/memory/profile_schemas \
  --header "Authorization: Bearer $DASHSCOPE_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "name": "用户基础画像",
    "description": "包含年龄和兴趣的用户信息",
    "plan_version": "pro",
    "attributes": [
      {"name": "年龄", "description": "用户年龄"},
      {"name": "爱好", "description": "用户的兴趣爱好"},
      {"name": "职业", "description": "用户职业"}
    ]
  }'

# 添加包含画像信息的对话（使用上面返回的 profile_schema_id）
curl -X POST https://dashscope.aliyuncs.com/api/v2/apps/memory/add \
  --header "Authorization: Bearer $DASHSCOPE_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "user_id": "user_001",
    "messages": [
      {"role": "user", "content": "我今年28岁，是一名软件工程师。周末喜欢踢足球。"},
      {"role": "assistant", "content": "很高兴认识你！"}
    ],
    "profile_schema": "YOUR_SCHEMA_ID"
  }'

# 获取用户画像（等待3秒后执行）
curl -X GET "https://dashscope.aliyuncs.com/api/v2/apps/memory/profile_schemas/{YOUR_SCHEMA_ID}/user_profile?user_id=user_001" \
  --header "Authorization: Bearer $DASHSCOPE_API_KEY" \
  --header "Content-Type: application/json"

环境变量配置

环境变量	必需	默认值	说明
`DASHSCOPE_API_KEY`	是	-	百炼 API 密钥，获取方式请参见获取 API Key

API 参考

完整的 API 接口参考（包括请求参数、返回结果和示例代码），请参见长期记忆（新）API 参考。以下补充记忆规则管理和画像模板管理相关的 API。

记忆片段规则管理（Memory Project）

记忆片段规则的 plan_version 决定该规则下 Add 调用的策略版本。不传时默认 Pro。可通过以下 API 管理规则：

接口	方法	计费	说明
CreateMemoryProject	POST	—	创建记忆片段规则，入参含 `plan_version`（默认 pro）。Pro ¥0.03/次，Lite ¥0.018/次。
UpdateMemoryProject	PATCH	—	更新规则，可修改 `plan_version`（pro↔lite）。修改后新 Add 调用遵循新策略版本。
ListMemoryProjects	GET	—	列出规则，出参含 `plan_version` 字段。
GetMemoryProject	GET	—	查询规则详情，出参含 `plan_version` 字段。
SearchMemory	POST	Pro ¥0.001/次 Lite ¥0.00002/次	检索记忆，入参 `plan_version` 独立控制策略版本，与规则的策略版本无关。不传默认 pro。优先级高于 `enable_rerank`。
AddMemory	POST	Pro ¥0.03/次 Lite ¥0.018/次	写入记忆，策略版本由关联规则的 `plan_version` 决定。不传 `project_id` 时默认 pro。

# 创建 Pro 版记忆片段规则
curl -X POST https://dashscope.aliyuncs.com/api/v2/apps/memory/memory_projects \
  --header "Authorization: Bearer $DASHSCOPE_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "memory_library_id": "your_memory_library_id",
    "name": "my-project",
    "instruction_type": "default",
    "expired_in_days": 30,
    "auto_refresh": true,
    "plan_version": "pro"
  }'

# 更新规则策略版本为 Lite
curl -X PATCH https://dashscope.aliyuncs.com/api/v2/apps/memory/memory_projects/{project_id} \
  --header "Authorization: Bearer $DASHSCOPE_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "memory_library_id": "your_memory_library_id",
    "plan_version": "lite"
  }'

画像模板管理（Profile Schema）

画像模板的 plan_version 控制画像记忆的策略版本。不传时默认 Pro。可通过以下 API 管理画像模板：

接口	方法	计费	说明
CreateProfileSchema	POST	Pro ¥0.03/次 Lite ¥0.025/次	创建画像模板，入参含 `plan_version`（默认 pro）。
ListProfileSchemas	GET	—	列出画像模板，出参含 `plan_version` 字段。
UpdateProfileSchema	PATCH	—	更新画像模板，可修改 `plan_version`（pro↔lite）。
GetProfileSchema	GET	—	查询画像模板详情，出参含 `plan_version` 字段。

画像模板的 plan_version 当前仅作为字段透出，不影响画像提取的实际处理逻辑。后续版本可能根据 plan_version 区分画像记忆的写入策略版本。

# 创建 Lite 版画像模板
curl -X POST https://dashscope.aliyuncs.com/api/v2/apps/memory/profile_schemas \
  --header "Authorization: Bearer $DASHSCOPE_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "memory_library_id": "your_memory_library_id",
    "name": "user-profile-lite",
    "description": "用户基础画像",
    "plan_version": "lite",
    "attributes": [
      {"name": "姓名", "description": "用户姓名", "immutable": true},
      {"name": "爱好", "description": "用户兴趣爱好", "immutable": false}
    ]
  }'

plan_version 参数规则

规则	说明
Add 策略版本来源	由关联的 MemoryProject 的 `plan_version` 决定。不传 `project_id` 时默认 pro。
Search 策略版本来源	由请求参数 `plan_version` 独立控制，与 project 的策略版本无关。不传默认 pro。
大小写	不敏感。"PRO"、"pro"、"Pro" 等效；"LITE"、"lite" 等效。
非法值	传入非 pro/lite 的值时返回报错。
优先级	Search 同时传 `plan_version` 和 `enable_rerank` 时，`plan_version` 优先。仅未传 `plan_version` 时 `enable_rerank` 生效。
更新生效范围	修改规则的 `plan_version` 后，新 Add 的记忆遵循新策略版本，已写入的记忆不受影响。
存量兼容	商业化前已存在的规则，`plan_version` 默认为 pro。

常见问题

API 是否存在限流？

API 接口	限流（阿里云账号级别）
全部接口	总计不超过 3000 QPM
记忆片段 add 接口	120 QPM
记忆片段 search 接口	300 QPM

商业化计费相关

Pro 和 Lite 策略版本有什么区别？ Pro 版检索时开启 Rerank（结果重排序），质量更高；Lite 版关闭 Rerank，成本更低。Add 的策略版本由 MemoryProject 的 plan_version 决定，Search 的策略版本由请求参数 plan_version 独立控制。详见记忆库计费标准。
SearchMemory 的 plan_version 和 MemoryProject 的 plan_version 是什么关系？ 两者独立。SearchMemory 的 plan_version 只影响本次检索调用，与 project 的策略版本无关。例如 project 为 lite，Search 传 plan_version: "pro" 时仍按 pro 计费并开启 Rerank。
plan_version 和 enable_rerank 同时传会怎样？ plan_version 优先级更高。传了 plan_version 时 enable_rerank 被忽略。仅当未传 plan_version 时 enable_rerank 生效。

​核心功能

​适用范围

​相比旧版长期记忆 API的改进

​使用方法

​环境变量配置

​API 参考

​记忆片段规则管理（Memory Project）

​画像模板管理（Profile Schema）

​plan_version 参数规则

​相关文档

​常见问题

​API 是否存在限流？

​商业化计费相关

核心功能

适用范围

相比旧版长期记忆 API的改进

使用方法

环境变量配置

API 参考

记忆片段规则管理（Memory Project）

画像模板管理（Profile Schema）

plan_version 参数规则

相关文档

常见问题

API 是否存在限流？

商业化计费相关