记忆库

概述

大模型受上下文窗口限制，无法跨会话保留信息。记忆库通过自动从对话中提取关键信息并持久化存储，在后续对话中基于语义检索相关记忆并注入上下文，使智能体能够持续理解用户偏好和历史信息。记忆库提供开放的 API 接口，可接入任意应用，也支持多应用共享同一记忆库。

记忆库支持两种记忆内容：

• 记忆片段：从对话中自动提取的关键事件和信息，如"用户每天上午9点需要喝水提醒"。适用于大多数长期记忆场景。

• 用户画像：基于自定义模板从对话中提取的结构化属性，如年龄、职业、偏好等。适用于需要固定属性的场景。

使用流程：

1. 获取 API Key，创建或使用默认记忆库。

2. 每轮对话结束后，调用 AddMemory 写入记忆。

3. 在控制台查看和检索记忆，或调用 SearchMemory 在应用中检索。

4. 将检索结果注入 Prompt，实现个性化回答。

快速开始

以下示例使用默认记忆库，3 步快速体验记忆的写入、查看和检索。如需自定义记忆规则，请参见创建记忆库。

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())

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())

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())

创建记忆库

创建记忆库并配置记忆规则，以定义记忆的提取和召回行为。每个用户账号下都自带一个默认记忆库，无需额外创建即可直接使用。如需自定义记忆规则或为不同业务场景分别管理记忆，可创建新的记忆库。

用户画像

用户画像用于从对话中提取结构化的用户属性（如年龄、职业、偏好），适用于需要持久化存储固定属性的场景。

# 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. 添加对话并提取画像
        await add_memory.arun(AddMemoryInput(
            user_id="user_001",
            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())

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

更多调用详情请参阅长期记忆 API。

计费说明

• 记忆库功能与 API 调用：目前限时免费。

• 模型调用：在检索记忆并将其注入 Prompt 时，记忆内容会作为上下文传递给大模型，从而增加 Token 消耗。具体费用以实际调用大模型产生的 Token 用量为准。

常见问题

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