Configure memory extraction and storage strategies - AgentLoop - Centro de documentación de Alibaba Cloud

Configure the extraction strategy

Select an extraction preset

Preset	Scenario	Recommendation
Fact extraction	Objective facts and preferences in general conversations	Start with this preset for the initial validation.
Consumer user profile	Personal habits, preferences, and long-term background	Use stable user IDs to avoid mixing information from different users.
Enterprise digital twin	Enterprise customers, business status, and relationships	Define the business objects and the information to keep.
Custom instruction	Domain-specific or business-specific extraction rules	A custom instruction is required. Specify the extraction scope and exclusions.

For example, a lifestyle assistant can use the following custom instruction:

Extract long-term dietary preferences that the user explicitly states, including flavors the user likes and dislikes.
Do not record suggestions made by the assistant but not confirmed by the user as user preferences.
Do not generalize temporary requirements for the current order into long-term habits.

A custom instruction can contain up to 8,000 characters. The instruction describes extraction goals and cannot replace business identity, access permissions, or scope configurations.

Categories, exclusion rules, and model

Categories: Specify categories such as preference and profile as needed. If the category list is not empty, only facts whose categories are in the list are kept, and results without a category are also filtered out. We recommend that you use the preview to check whether the categories meet your expectations.
Exclusion rules: Describe the content that you do not want to extract, such as temporary verification codes. The application must still perform necessary data filtering before inputs are processed. Do not rely only on model instructions to protect sensitive information.
Extraction model: Use a model option provided in the console. The current model is qwen3.8-flash.

Configure the storage strategy

Event append

Each extracted fact is appended as a new memory, which is suitable for keeping the history of events. After you enable Deduplication, duplicate results that have the same business scope, source, and fact key are skipped. Similar descriptions from different sources may still be stored separately.

For example, requests made by the same customer during two service sessions can be kept separately for later tracing.

Merge update

The system first searches for existing memories in the same business scope and then determines which actions to perform based on the input. This mode is suitable for maintaining changing information, such as user preferences and customer status.

Configuration item	Description
Merge key	Semantic similarity searches by content similarity. factKey searches by fact key. factKey + semantic combines both methods.
Similarity threshold	Valid values: 0 to 1. Default value: 0.4. This threshold is used to find related existing memories. It is not the score threshold for results returned by application retrieval.
Allowed actions	Select the actions that can be automatically performed: `ADD`, `UPDATE`, `MERGE`, and `DELETE`. Keep at least one action.

factKey identifies a type of fact, such as the dietary preferences of a specific user. The following table describes the actions.

Action	Description
ADD	Adds a memory.
UPDATE	Updates an existing memory.
MERGE	Merges related memories.
DELETE	Processes old memories that are no longer valid based on new facts. The actual storage handling is subject to the record status and audits.

For example, if a new input changes from "likes sweet drinks" to "now prefers sugar-free drinks", the system may propose an update or addition. The actual action depends on the scope, existing content, strategy, and extraction result. Use samples to observe the proposed actions before you decide which automatic changes to allow.

Manual edit protection and retention period

Manual edit protection is enabled by default. If automatic extraction needs to modify a manually revised memory, the system keeps the current content and records the change as pending review. The review status of the memory and related audits can help you determine why new content did not directly overwrite old content.

Expiration days must be a non-negative integer. 0 indicates that memories never expire. A positive value sets the retention period for memories written afterward. Do not assume that changing this configuration retroactively cleans up all historical records.

Configure business scope and audit

Configuration item	Description
Required scope for recall	You can select `userId`, `agentId`, `appId`, and `runId`. A request must contain at least one of the selected dimensions. If this parameter is left empty, no additional requirement is applied.
Audit retention days	Valid values: 1 to 180. Default value: 30.
Query logging mode	Log Original Text stores the query text. Log HMAC Only stores the query digest, and the audit page does not display the original query text.
Log discarded candidates	Records candidates that are not ultimately returned, as needed, to help analyze the stage at which filtering occurs.

Business scope conditions restrict the objects to query, and API keys are used for access authentication. The application must determine the IDs that can be queried from a trusted business context. If a query provides multiple IDs, all of them must match.

For information about how to use audit settings, see View memory audits and statistics.

Check strategies with samples

In Preview and Confirm of the creation wizard or Strategy > Sample Preview of an existing store, paste one or more samples. You can paste up to 20 samples.
Click Run Preview.
Check the Extracted Facts, Storage Action, and Skip Reason of each sample. Pay special attention to whether facts are accurate, whether the categories keep the required information, and whether unexpected updates or deletions occur.

The following sample can be pasted into the preview input box. The preview uses the nested scope field to represent the business scope. For information about the flat field format of Dataset sources, see Use a memory store.

[
  {
    "sourceId": "preview-001",
    "scope": {"userId": "user-001"},
    "messages": [{"role": "user", "content": "I like light, mildly spicy home-style dishes"}]
  }
]

For trace or Dataset sources, you can leave the samples empty, and the system samples data from the configured data source. For manual write sources, you must paste samples. The preview uses the configuration in the current form and does not require you to save it first. The preview does not write formal memories or generate audit records for formal extraction and storage.

Save the strategy and view versions

After you check the preview result, click Save Strategy. After the strategy is saved, verify information such as the strategy summary and creation time of the current version in Version History.

Reset on the page discards unsaved form changes and restores the current saved configuration. The version history is used to view existing records. Saving a strategy does not automatically re-extract all historical data.