Skip to main content

Memory Overview

The memory store lets agents retain user preferences and history across sessions.

Overview

LLMs are limited by context windows and cannot retain information across sessions. The memory store automatically extracts key information from conversations and persists it. In subsequent conversations, relevant memories are retrieved via semantic search and injected into the context, enabling agents to continuously understand user preferences and historical information. The memory store provides open API interfaces that can be integrated into any application and supports multiple applications sharing the same memory store. Two types of memory content are supported:
  • Memory segments: Key events and information automatically extracted from conversations, such as "user needs a water reminder at 9 AM every morning." Suitable for most long-term memory scenarios.
  • User profiles: Structured attributes extracted from conversations based on custom templates, such as age, occupation, and preferences. Suitable for scenarios requiring fixed attributes.
Usage flow:
  1. Obtain an API Key, then create or use the default memory store.
  2. After each conversation turn, call AddMemory to write the memory.
  3. View and search memories in the console, or call SearchMemory to search within your application.
  4. Inject the retrieved results into the prompt to enable personalized responses.

Quick Start

The following example uses the default memory store and demonstrates writing, viewing, and searching memories in 3 steps. To customize memory rules, see Configure Memory Rules.

Step 1: Write Memory

Call the AddMemory API to store the conversation into the memory store. Before calling, configure DASHSCOPE_API_KEY; see the API Key page for how to obtain one. Replace {workspaceId} in the request URL with your actual workspace ID, and use an API key that belongs to the same workspace. cURL 
curl -X POST https://{workspaceId}.cn-beijing.maas.aliyuncs.com/api/v2/apps/memory/add \
--header "Authorization: Bearer $DASHSCOPE_API_KEY" \
--header "Content-Type: application/json" \
--data '{
"messages": [
{"role": "user", "content": "Remind me to drink water at 9 AM every morning"},
{"role": "assistant", "content": "OK, noted."},
{"role": "user", "content": "Remind me to organize meeting notes tomorrow at 10 AM."}
],
"user_id": "user_001"
}'
Python 
from agentscope_runtime.tools.modelstudio_memory import (
AddMemory, SearchMemory, Message, AddMemoryInput, SearchMemoryInput,
)
import asyncio

async def basic_example():
add_memory = AddMemory()
search_memory = SearchMemory()
try:
# Write memory
await add_memory.arun(AddMemoryInput(
user_id="user_001",
messages=[
Message(role="user", content="Remind me to drink water at 9 AM every morning"),
Message(role="assistant", content="OK, noted."),
],
# memory_library_id="your_memory_library_id",  # Optional; uses the default store if not set
meta_data={"location_name": "Beijing"}
))

await asyncio.sleep(2)

# Search memory
result = await search_memory.arun(SearchMemoryInput(
user_id="user_001",
messages=[Message(role="user", content="What do I need to do?")],
top_k=5,
# memory_library_id="your_memory_library_id",  # Optional; uses the default store if not set
))
for node in result.memory_nodes:
print(f"Memory: {node.content}")
finally:
await add_memory.close()
await search_memory.close()

asyncio.run(basic_example())

Step 2: View Memory in the Console

Go to the Memory Store Management page. Click the target memory store name to enter the details page, then click the Memory tab to view and search all memory segments for the current user.

Step 3: Search Memory via API

Call SearchMemory to semantically search relevant historical memories. It is recommended to set top_k between 3 and 10. 
curl -X POST https://{workspaceId}.cn-beijing.maas.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",
"messages": [
{"role": "user", "content": "What do I need to do?"}
],
"top_k": 5
}'

Configure Memory Rules

Creating a Memory Store

Click Create Memory Store on the Memory Store Management page. Each memory store can contain multiple memory segments; one memory store can be shared by multiple applications.

Memory Segments and User Profiles

Memory segments are automatically extracted key information, stored as structured memory entries. Write via AddMemory; search via SearchMemory. User profiles extract structured attributes (age, occupation, interests, etc.) based on profile templates. Configure on the memory store details page under the Memory Rules tab.
Memory segments apply to most long-term memory scenarios. When fixed attribute extraction is needed, use user profiles in combination with memory segments.

Use Memory in Applications

For use in Agent applications, see Using Memory in Applications. For the complete API reference, see Long-term Memory API.