AgentLoop:Use a memory store

Prerequisites

For the basic concepts of memory stores, see Memory Store overview.

• An existing agent space, and access to the AgentLoop console of that space.

• The application to integrate, and a set of sample conversations for validation.

• If you plan to write data through the API, your local machine or the application runtime environment can reach the endpoint provided by the console. The HTTP examples in this topic use curl.

Step 1: Create a memory store

1. Log on to the AgentLoop console and select the target region and the agent space.

2. In the left-side navigation pane, choose Context Engineering, and then click the Memory Store tab.

3. Click Create Memory Store

   Parameter	Required	Description
   Memory Store Name	Yes	A name that is easy to identify, for example, cooking_memory.
   Memory Store Description	No	The purpose of the memory store and the applications that use it, for example, "Stores the dietary preferences of cooking assistant users".

4. Click OK.

   After the memory store is created, verify the name and the description on the Overview tab to confirm that the subsequent operations target the intended memory store.

Step 2: Create an API key

1. Go to the details page of the memory store that you created in Step 1, and then click the API Key tab.

2. If no API key exists, click Create Now and follow the instructions on the page to create an API key.

3. Copy the API key for application integration.

   An API key is bound to the memory store and the agent space. When you call the memory APIs listed on the API Key tab, you do not need to pass the memory store name or the space name separately.

Distinguish between the following two types of information when you use the memory store:

Step 3: Integrate the application and write a conversation

export AGENTLOOP_ENDPOINT="<Endpoint copied from the Integration tab>"
export AGENTLOOP_API_KEY="<API key of this memory store>"

curl -X POST "$AGENTLOOP_ENDPOINT/v1/memories" \
  -H "Authorization: Token $AGENTLOOP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      {"role": "user", "content": "I live in Hangzhou and I like unsweetened Americano coffee."},
      {"role": "assistant", "content": "OK. I have noted that you live in Hangzhou and like unsweetened Americano."}
    ],
    "user_id": "user-001",
    "infer": true
  }'

Step 4: Retrieve long-term memory

1. On the details page of the memory store, click the Long-term Memory Retrieval tab.

2. Enter a query statement, for example, "What coffee does this user like?".

3. Set User ID to user-001

   Parameter	Description
   topK	The maximum number of memories to return, for example, 5. The actual number of returned memories may be lower.
   User ID	Filters the memories by the associated business user identifier. To query the preferences of a user across sessions, retrieve by user scope.
   App ID	Filters the memories by the associated app identifier.
   Agent ID	Filters the memories by the associated agent identifier.
   Run ID	Filters the memories by the associated run identifier. Add this condition only when you need the memories of a specific run. Otherwise, relevant memories from other sessions are excluded.

4. Click Start Retrieval and view the memory content in the Retrieval Results section.

   A query statement expresses the information that you need, for example, "the dietary preferences of the user" or "what coffee the user likes". The ID filters limit the query scope. Use the two together, and make sure that the App ID, Agent ID, and Run ID filters correspond to the identifiers associated with the data that was actually written.

For the example in this topic, check whether information about "unsweetened Americano coffee" is returned in the Retrieval Results section. This is the second of the three integration checks. To retrieve memories from your application instead of the console, use the API call examples on the Integration tab.

How the application uses memories

After the application is integrated with the memory store, each round of interaction follows this process:

1. Receive a new question: Determine the user identifier from the logged-on user or the business context of the application.

2. Retrieve memories: Query the relevant memories by the current question and the user identifier. Use the examples on the Integration tab for the actual API calls.

3. Organize the model input: Add the relevant memories as background information to the request, together with the current question and the necessary recent conversation.

4. Generate the answer: The agent answers the question based on the current requirements and the historical background.

5. Write this conversation: Write the interactions that actually happened in this round to the memory store for later extraction and retrieval.

   The application should keep the explicit requirements of the current question. For example, if the historical memory is "likes coffee" but the user now asks to "recommend beverages without coffee", pass the current requirement to the agent as well. When the retrieval result is empty, the application can continue with the current question and the existing conversation context.

Example: Add user preferences for a cooking assistant

The following example shows how an application uses memories. It does not depend on a specific agent framework.

Organize the model input in the following structure. The memory content must come from the actual retrieval results:

Current question:
What should I have for dinner tonight?
Relevant user memories (background information):
The user prefers light, mildly seasoned home-style dishes.
Response requirements:
Give a suggestion based on the current question and the relevant preferences. The explicit requirements that the user states in this request take precedence.

This is an example of context organization. The actual answer depends on the current question, the retrieval results, and the model. When you validate, first confirm that the memories are retrieved, and then confirm that the application uses them.

Interpret validation results

The checks in Step 3, Step 4, and the cooking assistant example cover different stages of the integration. Use the following rules when you interpret the results:

• Separate stages — Resource provisioning, conversation writes, and memory extraction are separate stages. Check the write response and the retrieval results individually.

• Write success — A successful write response, or the word "noted" in the conversation, does not confirm that a memory was extracted.

• Extracted text — The actual extracted text, language, and number of entries may differ from the input. Judge whether the meaning matches the input.

• Retrieval score — The score indicates the confidence level of the retrieval match and helps you judge how well a result matches the current question. A score does not mean that the memory content has been fact-checked, and it does not mean that the application must pass all returned results to the agent.

• Single answer — Do not infer that the entire integration is correct from a single answer.

FAQ