Use a memory store
This topic describes how to select a memory source, create a memory store, integrate the memory store with an application, and retrieve and maintain long-term memories. To get started, select Manual write and use a sample conversation to verify the complete process. If you already have agent traces or business datasets, configure the corresponding data source in the creation wizard. For basic concepts, see Memory Store overview.
Prerequisites
-
An agent space is created, and you can access the AgentLoop console of the space.
-
You have determined the information to store and the business user, agent, or application identifiers to associate with memories.
-
If you use agent traces as the source, usable agent traces exist in the current space.
-
If you use a Dataset as the source, a dataset is prepared in the same space and you have read permissions on the dataset. For field requirements, see the following section.
-
If you integrate an application by using APIs, the runtime environment can access the endpoint provided in the console.
Step 1: Create a memory store
Log on to the AgentLoop console, select a region and agent space, choose Context Engineering > Memory Store, and then click Create Memory Store.
1. Select a data source
Enter a Memory Store Name and an optional Description, and then select a data source type.
Type |
Input method |
Example |
Manual write |
The application submits conversations by using an API. |
Write the dietary preferences of a user to |
Agent traces |
Continuously read agent traces from the current space. |
Extract user context from the run traces of a lifestyle assistant. |
Dataset |
Read a compliant dataset from the same space. |
Extract facts from a curated dataset of customer conversations. |
Click Next. You cannot change the data source type after the memory store is created. Determine how to prepare data before you proceed.
2. Configure filter conditions or the schema
Manual write
You do not need to configure source filter conditions. Proceed to the next step. After the memory store is created, follow Step 2 to integrate your application and submit conversations.
Agent traces
Parameter |
Description |
Service name | Select or enter the name of the service to consume. A suffix wildcard such as |
Agent name | Select or enter the agent to consume. Leave this parameter empty to impose no agent name restriction. |
Minimum steps | Skip traces that contain fewer than the specified number of steps. Enter a non-negative integer. |
Start time | Specify when consumption starts. If this parameter is empty, consumption starts when the memory store is created. |
Exclude degraded traces | Exclude degraded traces as needed. |
SLS query statement | Add a query condition to the source. This condition takes effect together with the preceding filter conditions. |
Multiple values in the same name list are evaluated by using the OR operator. Different filter items must all be satisfied. The source consists of assembled agent traces, and the input depends on the data actually collected in the current space. Before you select an earlier start time, make sure that the corresponding historical data is still available.
The user, agent, and application identifiers in traces must map to the business objects for which you want to accumulate memories. During retrieval, use the identifiers that are actually associated with the memories. Do not assume that every trace contains a business user ID.
Dataset
Select a Dataset Name in the same agent space. The Schema Contract is
MemorySourceV1.Select a Version Policy. Incremental Follow continuously reads data from newly added sequences. Fixed Version Full reads a snapshot of a specified version. For a fixed version, enter the actual version name. For incremental follow, you can specify a Start seq.
Enter a Filter Condition (where) as needed to select the records to process.
Check the Additional Fields. For fields that the model needs to understand, select Extraction Input and enter a description of their meanings. For other fields, select Ignore. Undeclared additional columns are not automatically used as extraction inputs.
The source Dataset must contain the following nine fixed fields.
Field |
Type |
Description |
| text | The source identifier of an input. Use a stable, non-empty value. |
| json | A non-empty message array. Each message contains |
| long | A positive Unix timestamp in seconds. |
| text | Business user identifier. |
| text | Agent identifier. |
| text | Application identifier. |
| text | Run identifier. |
| json | A business metadata object. If no additional information is available, use |
| json | A source description object in which |
At least one of the four business identifiers must be non-empty. Do not encode JSON arrays or objects as JSON strings again. Convert millisecond timestamps to seconds.
The following example shows the field structure of a Dataset input. During import, replace the source identifier, timestamp, messages, and business identifiers with actual values.
{
"sourceId": "conversation-001",
"messages": [{"role": "user", "content": "I prefer light, mildly spicy dishes."}],
"timestamp": 1788796800,
"userId": "user-001",
"agentId": "cooking-assistant",
"appId": "cooking-app",
"runId": "",
"metadata": {},
"lineage": {"sourceKind": "dataset"}
}
To associate external business information, first complete the association and field preparation in the data processing workflow, and then write the results to the source Dataset. The source Dataset and the result Dataset that stores extracted long-term memories are different resources.
3. Configure strategies
For the initial verification, select Fact Extraction and Merge Update, and retain the default parameters. To accumulate user profiles based on user habits, select Consumer User Profile. To store enterprise business context, select Enterprise Digital Twin. To define specific extraction objectives, select Custom Instructions.
In Scope and Audit, you can specify a type of business identifier that must be provided for recall, such as userId. For details about the parameters and the differences between the two storage modes, see Configure memory extraction and storage strategies.
4. Preview and create
Check the data source, filter conditions, and strategy summary in Preview and Confirm. You can paste a representative sample and click Run Preview to view extracted facts, storage actions, and reasons for skipping content. For an agent trace or Dataset source, you can also sample data from the configured source without pasting a sample.
A preview does not write formal memories. If the preview fails, correct the configuration or input and run the preview again. After confirmation, click Create Memory Store. For the sample format, see Configure memory extraction and storage strategies.
After the memory store is created, go to the Overview page to check the memory store and data source status. For an agent trace or Dataset source, you can also view the consumption progress, latest consumption window, and latest error, and click Pause Consumption or Resume Consumption to control subsequent reads.
Step 2: Integrate an application
For manual write, submit conversations as described in this section. Agent trace and Dataset sources read data based on their configured data sources. When an application needs to retrieve memories, you can also create an API key and configure access parameters.
Create an API key
Go to the API Key tab of the memory store, and create and copy an API key. The credential is bound to the corresponding space and memory store. Go to the Integration tab and copy the endpoint of the destination region. When you use the memory APIs, you do not need to specify the space name or memory store name in requests.
Store the credential in a server-side environment variable or secret manager. The following example uses the HTTP API. Replace the placeholders with the configuration provided on the current page:
export AGENTLOOP_ENDPOINT="<Endpoint copied from the Integration tab>"
export AGENTLOOP_API_KEY="<API key of the current memory store>"New resources require time to become ready. Before the first call, follow the instructions on the Integration tab to confirm that the resource is available.
Write a conversation
The following request associates a conversation with the business user user-001 and uses infer: true to request long-term memory extraction.
curl -X POST "$AGENTLOOP_ENDPOINT/v1/memories" \
-H "Authorization: Token $AGENTLOOP_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"messages": [
{"role": "user", "content": "I prefer light, mildly spicy home-style dishes."},
{"role": "assistant", "content": "I will consider your preferences when recommending dishes."}
],
"user_id": "user-001",
"infer": true
}'First, check whether the response is successful. After a write request is accepted, long-term memories still need to undergo asynchronous extraction and storage. A message from the assistant saying that the information is remembered does not replace checking the server-side result.
Retrieve memories in the application
curl -X POST "$AGENTLOOP_ENDPOINT/v2/memories/search" \
-H "Authorization: Token $AGENTLOOP_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"query": "What are this user's dietary preferences?",
"user_id": "user-001",
"top_k": 5
}'user_id must be the same as the value used during the write operation. top_k specifies the maximum number of results to return. You can also use the following API to list memories by business user and check whether data has been written.
curl -X POST "$AGENTLOOP_ENDPOINT/v2/memories" \
-H "Authorization: Token $AGENTLOOP_API_KEY" \
-H "Content-Type: application/json" \
-d '{"user_id": "user-001", "limit": 20}'For a Python application, choose Integration > Python SDK, and install and initialize MemoryClient based on the example on the page. Use the version, methods, and parameters provided on the page.
Step 3: Retrieve and maintain memories in the console
Verify retrieval results
Go to the Long-term Memory Retrieval tab, enter "What are this user's dietary preferences?", set User ID to user-001, configure topK, and then click Start Retrieval.
You can add filter conditions such as App ID, Agent ID, Run ID, kind, and category as needed. Multiple business IDs are combined by using the AND operator. To query the cross-session preferences of a user, do not add a run ID unrelated to the target memory.
Result cards display memory content and available ranking, revision, source, manual edit, and review status information. Check whether the meaning matches the input. The model does not need to reproduce messages word for word or generate a fixed number of memories. A score indicates retrieval relevance, not factual accuracy.
Edit and delete memories
Open the details of a memory, click Edit, modify the memory content, and then click Save. After the save operation succeeds, refresh the results and check the latest content. If a revision conflict is reported, reopen the details to read the latest version before deciding how to modify the memory.
You can use the delete operation on a memory card to remove content that is no longer needed. Verify the target memory before confirmation. Do not treat deleting source data, deleting a long-term memory, and deleting an entire memory store as the same operation.
After manual edit protection is enabled, new changes proposed by automatic extraction for manually revised content enter the pending review state, and the original content is retained. You can check the source and audit records to determine the reason. For strategy details, see Configure memory extraction and storage strategies.
View source and recall records
If a memory record provides source information and a corresponding write log exists, you can use the source entry to view the input. If the page returns a recall event ID, you can go to Audit Details to inspect the query. For an overall view, see View memory audits and statistics.
Step 4: Let an agent use memories
After the application receives a new question, it determines the user identifier from its logon state or business context, retrieves relevant memories, and then provides the useful results to the agent together with the current question and necessary recent conversations.
For example, if the same user asks "What should I eat tonight?" in a new session, the application can organize the following input:
Current question: What should I eat tonight?
Relevant user memory: The user prefers light, mildly spicy home-style dishes.
Response requirement: Provide suggestions based on the current question and relevant preferences, while honoring any new requirements explicitly stated by the user.The memories in the input must come from actual retrieval results. After the response is generated, write the conversation of the current round as needed, or let the configured data source provide subsequent inputs.
FAQ
Why are no results available after a successful write?
First, confirm the memory store and region associated with the API key. Then, check whether the same user identifier is used for writing and retrieval and whether too many additional filters are applied. For manual write, check input events. For agent trace and Dataset sources, check the consumption status, filter conditions, start position, and latest error. Then, use the extraction and storage audits to determine whether processing is in progress, the content was excluded by a strategy, or the content is pending review.
Why can I preview results but not retrieve them?
A sample preview does not write formal memories. Submit actual input or let the data source consume the corresponding record, and retrieve memories only after storage is complete.
Does changing a strategy reprocess all historical data?
After you save a strategy, you can view the new version in the version history. Historical memories are not automatically rebuilt in full when you save the strategy. To check the effect of a new strategy, run a sample preview first and then observe subsequent actual inputs.
What do I do if consumption stops after source dataset fields are changed?
Check the latest error on the Overview page and confirm that the names and types of fixed fields and the additional fields in use still meet the conventions specified during creation. Do not repeatedly resume consumption to bypass schema errors. Correct the data first, and then check the consumption status.