长期记忆 API

AI 在长对话中会遗忘关键信息，且跨会话没有记忆，导致上下文丢失、体验不连贯。为解决此痛点，我们引入了长期记忆功能。该功能可自动从历史对话中提炼并结构化存储记忆片段与用户画像。在后续对话或新会话中，开发者可以检索这些记忆并将其注入 Prompt，赋能 AI 实现真正的持续性理解。

核心功能

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

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

生成的记忆片段与用户画像暂无失效日期。

适用范围

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

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

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

使用方法

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

# 添加记忆
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"
  }'

# 添加记忆
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 '{}'

# 创建画像 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"

环境变量配置

API 参考

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

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

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

# 创建 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 管理画像模板：

# 创建 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 参数规则

相关文档

如需通过百炼控制台使用和管理本文介绍的长期记忆与用户画像功能，请参见记忆库。

常见问题

API 是否存在限流？

商业化计费相关

• 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 生效。