记忆库

​

概述

• 记忆片段：从对话中自动提取的关键事件和信息，如"用户每天上午9点需要喝水提醒"。适用于大多数长期记忆场景。
• 用户画像：基于自定义模板从对话中提取的结构化属性，如年龄、职业、偏好等。适用于需要固定属性的场景。

1. 获取 API Key，创建或使用默认记忆库。
2. 每轮对话结束后，调用 AddMemory 写入记忆。
3. 在控制台查看和检索记忆，或调用 SearchMemory 在应用中检索。
4. 将检索结果注入 Prompt，实现个性化回答。

​

快速开始

​

步骤一：写入记忆

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"
  }'

from agentscope_runtime.tools.modelstudio_memory import (
    AddMemory, AddMemoryInput, Message,
)
import asyncio

async def add_memory_example():
    add_memory = AddMemory()
    try:
        await add_memory.arun(AddMemoryInput(
            user_id="user_001",
            messages=[
                Message(role="user", content="每天上午9点提醒我喝水"),
                Message(role="assistant", content="好的，已记录"),
                Message(role="user", content="明天10点提醒我整理会议纪要。"),
            ]
        ))
        print("记忆写入成功")
    finally:
        await add_memory.close()

asyncio.run(add_memory_example())

​

步骤二：在控制台查看记忆

1. 登录百炼控制台，进入默认记忆库的记忆详情标签页。
2. 在记忆实体 ID中输入 user_001，单击查看，即可看到系统从对话中自动提取的记忆片段。

curl -X 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"

from agentscope_runtime.tools.modelstudio_memory import (
    ListMemory, ListMemoryInput,
)
import asyncio

async def list_memory_example():
    list_memory = ListMemory()
    try:
        result = await list_memory.arun(ListMemoryInput(
            user_id="user_001",
            page_size=10,
            page_num=1
        ))
        for node in result.memory_nodes:
            print(f"记忆: {node.content}")
    finally:
        await list_memory.close()

asyncio.run(list_memory_example())

​

步骤三：在控制台检索记忆

1. 切换到记忆检索标签页，输入记忆实体 ID为 user_001。
2. 在输入框输入"我需要做什么？"，点击运行，查看系统返回的相关记忆。

curl -X POST https://dashscope.aliyuncs.com/api/v2/apps/memory/search \
  --header "Authorization: Bearer $DASHSCOPE_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "user_id": "user_001",
    "query": "我需要做什么？"
  }'

from agentscope_runtime.tools.modelstudio_memory import (
    SearchMemory, SearchMemoryInput, Message,
)
import asyncio

async def search_memory_example():
    search_memory = SearchMemory()
    try:
        result = await search_memory.arun(SearchMemoryInput(
            user_id="user_001",
            messages=[Message(role="user", content="我需要做什么？")]
        ))
        for node in result.memory_nodes:
            print(f"记忆: {node.content}")
    finally:
        await search_memory.close()

asyncio.run(search_memory_example())

​

创建记忆库

​

默认记忆库

• 默认记忆库无法删除，但可以编辑名称和描述、添加自定义记忆规则。
• 默认记忆库已预置一条”默认项目”记忆片段规则，默认有效期 180 天。可点击编辑调整信息。 创建新的记忆库
  1. 在记忆库页面，单击右上角的创建记忆库。
  2. 在创建记忆库对话框中，填写以下基础信息： 记忆库名称：描述记忆库内容的名称。 记忆库描述：可能会用于指导智能体调用的描述语句。
  3. 单击确定完成创建。
  4. 创建成功后，会提示是否立即开始创建记忆规则：
     • 单击立即创建（推荐）：跳转到记忆规则配置页面，继续配置记忆规则。该页面包含记忆片段规则和用户画像规则两个区域，前者通过对话记录描述记忆的关键事件，后者保存用户实体的信息。
     • 单击暂不：返回记忆库列表页面，可后续通过点击记忆库卡片上的查看详情进入配置。

​

配置记忆规则

记忆库已预置一条“默认项目”记忆片段规则，默认有效期 180 天。不可删除，但可点击编辑调整信息。

​

配置记忆片段规则

1. 点击记忆库卡片的查看详情，进入记忆库详情页，在记忆规则标签页下的记忆片段规则区域，单击添加片段规则按钮。
2. 在对话框中配置以下参数：
   • 规则名称：当前记忆抽取规则的唯一标识。
   • 规则指令：定义记忆抽取的策略指令，即描述如何抽取和抽取哪些内容。可选择默认规则指令或自定义规则指令。
     • 默认规则指令（推荐）
     • 自定义规则指令
   • 自动更新：开启后，模型会自动更新记忆内容。默认开启。
   • 记忆过期时间：记忆的有效期，可选：7 天、30 天、180 天、永不过期。
   • 记忆抽取策略版本：选择 Pro（推荐）或 Lite。Pro 版检索时开启 Rerank，质量更高，¥0.03/次；Lite 版关闭 Rerank，成本更低，¥0.018/次。不传时默认 Pro。详见计费说明。
3. 单击确认完成配置。

​

配置用户画像规则

1. 进入记忆库详情页，在记忆规则标签页下的用户画像规则区域，单击添加用户画像。
2. 在对话框中配置以下参数：
   • 画像规则名称：当前画像规则的唯一标识。
   • 画像字段列表：点击添加用户画像字段填写以下信息，然后点击保存。
     • 用户画像字段名称：定义抽取出的画像包含哪些字段。
     • 描述：描述该字段的含义，引导模型提取相关信息。
     • 初始值：为该画像属性设置初始默认值。当用户尚未通过对话提供相关信息时，系统将使用该初始值作为画像属性的值。
   • 记忆抽取策略版本：选择 Pro（推荐）或 Lite。Pro 版 ¥0.03/次，Lite 版 ¥0.025/次。不传时默认 Pro。详见计费说明。
3. 单击确认完成配置。

在智能体应用中配置长期记忆变量

1. 进入智能体应用编排页面，切换到记忆标签页。
2. 开启长期记忆开关，然后单击配置按钮，进入记忆变量对话框。
3. 在记忆变量对话框中，单击+ 添加字段（0/32）新增记忆变量，配置字段名称和描述后单击保存。
4. 配置完成后，单击发布按钮发布应用，配置才会生效。
5. 发布后，在测试窗口中输入与记忆变量相关的信息，智能体会触发长期记忆检索，并将提取的信息更新到对应的记忆变量中。

​

用户画像

​

在控制台配置用户画像

1. 进入记忆库详情页，在记忆规则标签页的用户画像规则区域，单击添加用户画像。
2. 填写画像规则名称，添加画像字段（如"年龄""职业""爱好"），为每个字段填写描述以引导模型提取。
3. 单击确认完成配置。详细参数说明请参见配置用户画像规则。

​

通过 API 使用用户画像

# 1. 创建画像模板（CreateProfileSchema）
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": "包含年龄和兴趣的用户信息",
    "attributes": [
      {"name": "年龄", "description": "用户年龄"},
      {"name": "爱好", "description": "用户的兴趣爱好"},
      {"name": "职业", "description": "用户职业"}
    ]
  }'

# 2. 添加对话并提取画像（AddMemory，传入上面返回的 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. 获取用户画像（GetUserProfile，等待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"

from agentscope_runtime.tools.modelstudio_memory import (
    CreateProfileSchema, GetUserProfile, AddMemory,
    ProfileAttribute, CreateProfileSchemaInput,
    GetUserProfileInput, AddMemoryInput, Message,
)
import asyncio

async def profile_example():
    create_schema = CreateProfileSchema()
    get_profile = GetUserProfile()
    add_memory = AddMemory()

    try:
        # 1. 创建画像模板
        schema_result = await create_schema.arun(CreateProfileSchemaInput(
            name="用户基础画像",
            description="包含年龄和兴趣的用户信息",
            attributes=[
                ProfileAttribute(name="年龄", description="用户年龄"),
                ProfileAttribute(name="爱好", description="用户的兴趣爱好"),
                ProfileAttribute(name="职业", description="用户职业"),
            ]
        ))
        schema_id = schema_result.profile_schema_id

        # 2. 添加对话并提取画像（必须传入 profile_schema，否则不会提取画像）
        await add_memory.arun(AddMemoryInput(
            user_id="user_001",
            profile_schema=schema_id,
            messages=[
                Message(role="user", content="我今年28岁，是一名软件工程师。周末喜欢踢足球。"),
                Message(role="assistant", content="很高兴认识你！"),
            ]
        ))

        await asyncio.sleep(3)  # 等待画像提取

        # 3. 获取用户画像
        profile = await get_profile.arun(GetUserProfileInput(
            schema_id=schema_id, user_id="user_001"
        ))
        for attr in profile.profile.attributes:
            print(f"{attr.name}: {attr.value or '未提取'}")

    finally:
        await create_schema.close()
        await get_profile.close()
        await add_memory.close()

asyncio.run(profile_example())

​

管理记忆

​

查看记忆详情

curl -X 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"

from agentscope_runtime.tools.modelstudio_memory import (
    ListMemory, ListMemoryInput,
)
import asyncio

async def list_memory_example():
    list_memory = ListMemory()
    try:
        result = await list_memory.arun(ListMemoryInput(
            user_id="user_001",
            page_size=10,
            page_num=1
        ))
        for node in result.memory_nodes:
            print(f"记忆: {node.content}")
    finally:
        await list_memory.close()

asyncio.run(list_memory_example())

​

检索调试

1. 在记忆库详情页的记忆检索标签页中，配置以下参数：
   • 记忆实体 ID：输入写入记忆时设置的user_id字段值。
   • 记忆片段规则：选择指定规则进行检索。
   • 最大召回数量：每次检索返回的记忆条数（1~100）。
   • 意图判别召回：系统判断当前对话是否需要召回记忆，避免无关检索。建议开启。
   • 改写：对用户查询进行优化改写，提升语义检索的准确率。当提问较口语化时建议开启。
   • 排序：开启后将对检索结果进行重排，提升相关性。
     • 选择排序模型：目前仅支持gte-rerank-v2模型。
     • 相似度阈值（0.0~1.0）：建议设置在 0.5~0.7 之间。过高可能漏召相关记忆，过低可能引入噪声。
   • 输入：传入当前提问，系统将基于语义检索返回最相关的记忆片段和用户画像。
2. 点击运行，查看检索结果。

curl -X POST https://dashscope.aliyuncs.com/api/v2/apps/memory/search \
  --header "Authorization: Bearer $DASHSCOPE_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "user_id": "user_001",
    "query": "我需要做什么？",
    "max_results": 10,
    "rewrite": true,
    "rerank": true,
    "similarity_threshold": 0.6
  }'

from agentscope_runtime.tools.modelstudio_memory import (
    SearchMemory, SearchMemoryInput, Message,
)
import asyncio

async def search_memory_example():
    search_memory = SearchMemory()
    try:
        result = await search_memory.arun(SearchMemoryInput(
            user_id="user_001",
            messages=[Message(role="user", content="我需要做什么？")],
            top_k=10,
            min_score=0.6
        ))
        for node in result.memory_nodes:
            print(f"记忆: {node.content}")
    finally:
        await search_memory.close()

asyncio.run(search_memory_example())

​

更新和删除记忆

# 列出记忆
curl -X 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"

# 更新记忆
curl -X 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 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"

from agentscope_runtime.tools.modelstudio_memory import (
    ListMemory, ListMemoryInput,
    DeleteMemory, DeleteMemoryInput,
)
import asyncio

async def manage_memory_example():
    list_memory = ListMemory()
    delete_memory = DeleteMemory()
    try:
        # 列出记忆
        result = await list_memory.arun(ListMemoryInput(
            user_id="user_001", page_size=10, page_num=1
        ))
        for node in result.memory_nodes:
            print(f"记忆 {node.memory_node_id}: {node.content}")

        # 删除记忆
        await delete_memory.arun(DeleteMemoryInput(
            user_id="user_001",
            memory_node_id="MEMORY_NODE_ID"
        ))
    finally:
        await list_memory.close()
        await delete_memory.close()

asyncio.run(manage_memory_example())

​

删除记忆库

• 在记忆库卡片上点击...，然后点击删除。
• 在记忆库详情页右上角点击...，然后点击删除。

​

相关 API

​

计费说明

​

免费额度

​

计费标准

​

Pro 与 Lite 策略版本说明

​

常见问题

1. 记忆内容会存储多长时间？ 生成的记忆片段与用户画像暂无失效日期（除非在创建记忆库时配置了记忆过期时间）。您可以随时通过控制台或 API 删除不再需要的记忆内容。
2. 如何实现不同用户之间的记忆隔离？ 记忆的存储和检索以记忆实体（如 user_id）为维度进行隔离。不同用户的记忆内容互不干扰。您也可以创建多个记忆库，分别用于不同的业务场景。
3. 与之前的长期记忆功能有什么区别？ 记忆库是之前长期记忆功能的全面升级版。主要区别在于：引入了记忆库作为独立的记忆管理容器，支持更灵活的记忆规则配置，新增了用户画像能力，并在检索效果、成本和延时方面进行了优化。
4. 记忆片段和用户画像有什么区别？何时使用哪个？ 记忆片段适用于记录具体的事件和信息（如"用户上周去了北京"），用户画像适用于结构化的用户属性（如年龄、职业、偏好等）。如果需要记录固定的用户属性，建议使用用户画像；如果是动态的事件信息，使用记忆片段。两者可以同时使用。
5. 记忆实体数量在哪里查看？ 在记忆库列表页单击查看详情，在记忆详情标签页可查看记忆片段数、用户画像数和记忆实体数的统计信息。
6. 如何优化记忆检索效果？ 可通过以下方式优化：1）在记忆库详情的记忆检索标签页进行调试测试；2）调整相似度阈值（建议 0.5-0.7）；3）开启"意图判别召回"避免无关检索；4）开启"改写"和"排序"提升检索准确性；5）合理设置最大召回数量（根据实际需求设置）。
7. 默认记忆库可以删除吗？ 默认记忆库不可删除，但可以编辑其名称、描述和记忆规则。默认记忆库已预置一条"默认项目"记忆片段规则，默认有效期 180 天，您可以根据需要修改或添加新的规则。
8. API 是否存在限流？

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

9. Pro 和 Lite 策略版本有什么区别？如何选择？ Pro 版检索时开启 Rerank（结果重排序），检索质量更高但成本也更高；Lite 版关闭 Rerank，成本更低。对回答准确性要求高的场景建议用 Pro，高频调用且成本敏感的场景用 Lite。Add 调用的策略版本由记忆规则配置决定，Search 调用的策略版本由请求参数 plan_version 独立控制。详见计费说明。
10. 免费额度有效期多久？ Add 和 Search 的免费额度自商业化生效日起 3 个月内有效，逾期未用自动作废。10,000 条免费存储无有效期限制，长期有效。
11. 创建规则后可以切换 Pro/Lite 策略版本吗？ 可以。在控制台编辑记忆规则时可修改策略版本，也可通过 API 的 UpdateMemoryProject / UpdateProfileSchema 接口修改 plan_version 字段。修改后新写入的记忆遵循新策略版本规则，已写入的记忆不受影响。
12. 长期记忆功能支持在 APP 端使用吗？ 支持。记忆库提供开放的 API 接口，记忆的写入与检索全部通过 API 完成，与调用方的客户端类型无关。Web 应用、移动 APP、小程序均可通过 AddMemory、SearchMemory 接口集成记忆能力。若需将智能体应用发布到移动端，多平台发布与集成方式请参见应用分享。