AgentStorage provides knowledge retrieval and memory capabilities for AI applications. In the AgentStorage console, you can create an instance, manage knowledge bases and memory stores, debug retrieval results, and verify results in Agent chat together with a model, without writing code.
Prerequisites
All operations in this topic are performed in the AgentStorage console. Before you begin, make sure that the following requirements are met:
AgentStorage is available in the China (Beijing) and China (Hangzhou) regions.
Your account must have the permissions to view and manage AgentStorage. For more information, see Configure access control. If you use a RAM user, ask the account administrator to grant the permissions.
To import knowledge documents from a local device or OSS, your account must have an available OSS bucket. The bucket must reside in the same region as the AgentStorage instance. If an OSS authorization prompt appears when you create a knowledge base, complete the authorization before you continue.
Manage AgentStorage instances
An AgentStorage instance hosts knowledge bases and memory stores. Create an instance in the target region before you use these features.
Create an AgentStorage instance
Select the target region and click Create AgentStorage.
Enter a name. The name must be 3 to 16 characters in length, start with a letter, and contain only letters, digits, and hyphens. It cannot end with a hyphen and must be unique within the region.
Enter a description and select a resource group as needed, and then click OK.
After the instance is created, it requires a short initialization. The console automatically detects when the instance becomes available. If you cannot open a feature page yet, refresh the page or select the instance again.
View and maintain AgentStorage instances
In the AgentStorage selector in the upper-left corner, click AgentStorage management to search for the instances in the current region and perform the following operations:
Click Details to get the instance name and access address that Agent Storage SDK requires, and to view the region, storage specification, resource group, and creation time.
Click Modify description to update the instance description. You cannot change the instance name or region after creation.
Click Delete to release an instance that you no longer use.
Deletion cannot be undone. Before you delete an AgentStorage instance, make sure that the related workloads no longer use it.
Manage knowledge bases
A knowledge base stores document content and provides context for question-answering applications through vector retrieval, full-text retrieval, and reranking.
Create a knowledge base
Go to Knowledge base management and click Create knowledge base.
Configure the following parameters.
| Parameter | Description |
| Name | Must start with a letter and can contain only letters, digits, and underscores. It can be up to 64 characters in length. |
| Description and tags | Describe the purpose of the knowledge base to simplify later management. |
| Metadata schema | Defines the additional attributes of a document, such as custom fields for source, category, and version number. When you import a document, you can specify the values of these fields, and you can filter retrieval results by field. Plan the required fields before you create the knowledge base. |
| Enable subspace | Suitable for isolating documents within the same knowledge base by business line, project, or tenant. |
| Multi-modal | Supports image document ingestion, image retrieval, and multi-modal embedding and reranking. |
| Table and formula caption | After you enable this option, the system generates natural language descriptions for the tables and formulas in a document, which improves the retrieval hit rate for such content. |
| Advanced settings | Lets you set the embedding model, number of recalled results, retrieval type, and reranking strategy. If you have no specific tuning requirements, use the default configurations first. |
You cannot change the multi-modal setting after the knowledge base is created. Confirm whether you need this capability before you create the knowledge base.
After the knowledge base is created, it appears in the list. To modify the retrieval or embedding configuration of the knowledge base or adjust the reranking strategy, click ··· and then Settings in the upper-right corner of the target card.
Import documents
Open the knowledge base card, go to Document management, and click the upload entry. The console supports the following three import methods:
Upload file: Select a local file and specify the OSS bucket and the directory to save it to.
Upload folder: Upload files in a directory in batches. You can specify whether to recurse into subdirectories and which file name extensions to include or exclude.
Import from OSS: Directly select an existing file or directory in OSS.
The limits on the file type, single file size, and batch quantity are the ones shown on the upload panel in the console. After a document is uploaded, it goes through parsing and chunking. You can run a retrieval test only after the status changes to Completed. In the document details, you can view the metadata and chunk content, and edit the chunks where editing is supported.
Test retrieval
Click the target knowledge base, and then choose Retrieval test on the left side to verify retrieval results:
Enter the question or keywords to retrieve. If subspaces are enabled, also enter the name of the subspace to search.
For Search type, select both Vector retrieval, which matches by semantic similarity, and Full-text retrieval, which matches by keywords.
Keep the default TopK (the maximum number of results to return) for each retrieval method and the default number of final results after reranking.
Keep the default reranking strategy. Reranking strategies, such as model reranking, weighted fusion, and RRF, reorder the preliminary results by relevance.
If the knowledge base defines metadata fields, add metadata filter conditions.
Click Run retrieval to view the recalled content, similarity, and latency.
For the first round of debugging, use the default parameters. After you confirm that the target document can be recalled, gradually adjust TopK and the reranking configuration based on the recall accuracy and the number of results. If the results do not contain the target content, troubleshoot in the following order:
Confirm that the document status is Completed.
Confirm that the subspace and metadata filter conditions match your expectations.
Temporarily remove the filter conditions to verify that basic recall works.
Increase TopK.
Adjust the reranking strategy.
Verify question-answering results in the Knowledge base lab
The Knowledge base lab lets you verify end-to-end retrieval-augmented generation (RAG) question-answering results without modifying the documents in the knowledge base:
Go to the Knowledge base lab and configure the temperature and system prompt of the model on the left.
Select one or more knowledge bases. If a knowledge base has subspaces enabled, also enter the corresponding subspace name.
Set the global retrieval parameters, and enable the citation panel as needed.
Enter a question in the chat area in the middle. On the right, view the documents and chunks that were actually retrieved, their similarity, and the number of citations provided to the model.
If the answer does not meet your expectations, first check whether the citation panel recalled the correct content. If the target content was not recalled, adjust the documents, subspace, and retrieval parameters first. If the content was recalled but the answer is unsatisfactory, adjust the system prompt or the model parameters.
Manage memory stores
A memory store persists the context within the Scope of an application, user, agent, and conversation.
Create and manage a memory store
Go to Memory store management and click Create memory store.
Configure the following parameters.
| Parameter | Description |
| Name | Can contain only letters, digits, and underscores, and can be up to 32 characters in length. |
| Description | Describes the business purpose of the memory store. |
| Storage mode | Cannot be changed after creation. Select a mode based on how you plan to use the memory store. |
| Extraction instructions | Guides the system to extract structured memories from text or conversations. Can be up to 4096 characters in length. Supported only in structured memory mode and structured memory with file projection mode. |
The following table describes the available storage modes.
| Storage mode | Scenarios | Key capabilities |
| Structured memory | Long-term memories such as user preferences, facts, and tasks | Long-term memory, short-term memory, retrieval, tasks, and Dream |
| Structured memory with file projection | Both structured queries and a file view are required | Retains structured capabilities and provides read-only file browsing |
| File memory | Memory content organized as files | Writable files, directory management, and version history; does not generate structured memories |
After the memory store is created, the memory store card displays the name, storage mode, and creation time. To delete a memory store, go back to the Memory store management list page, click ··· in the upper-right corner of the target memory store card, and select Delete.
This action cannot be undone. You must enter the memory store name to confirm the deletion.
Use a memory store
The menu on the memory store details page changes based on the storage mode. The following example uses structured memory mode to describe how to use the main features.
Write memory
Click Write memory, enter the expected Scope multi-tenancy (which indicates the ownership and isolation boundary of memory data), select an input method, and then enter the memory content:
Text input: Directly enter the text to record. You can attach metadata as needed.
Message JSON: Suitable for debugging conversation message scenarios. Example:
[{"role":"user","content":"Hello"},{"role":"assistant","content":"Hello! How can I help you?"}]
After you finish, click Write memory. Note the following:
appIdis required. If you leave the other Scope fields (tenantId,agentId, andrunId) blank, the system automatically fills them with default values. Write operations cannot use wildcards.A successful write only means that the content was received. Long-term memory extraction runs asynchronously. Refresh the long-term memory page to view the extraction results.
View short-term memories
Go to Short-term memory and select the same Scope and an appropriate time range. The page retains the originally written messages, which helps you reconstruct the context that the user entered at the time. If no data appears here, first check the Scope, the time range, and the write result.
View long-term memories
Go to Long-term memory and refresh the page to view the long-term memories that the system extracted from the written content. In the list, you can view the memory type, version, and creation time. You can also open the details of a single memory and modify or delete it.
Long-term memories are information that a model has organized, and they do not equal the original messages. In production, spot-check the extraction results, and use the extraction instructions to specify the information to keep and the information to ignore.
Retrieve memories
Go to Memory retrieval, enter a query statement, set TopK, enable reranking as needed, and then click Search. The retrieval results show the similarity, relevance, memory type, Scope, version, and creation time. If your application attached metadata during writes, you can also use a metadata filter to narrow the results.
Relevance — The final basis for sorting the retrieval results. When reranking is enabled, this is the relevance score returned by the reranking model. When reranking is disabled, this is the normalized vector similarity. When you use the SDK to set the similarity threshold (
minSimilarity), this value is also the one that is filtered.Similarity — The raw cosine similarity between the query and the memory content. It is for reference only and does not participate in sorting or filtering. It is not returned when vector similarity is not calculated.
View extraction tasks
Go to the Tasks page to view the status, input Scope, memory count, and processing time of asynchronous memory extraction tasks. Click a task to confirm its details, including the input content, processing status, duration, and generated results. When a write succeeds but the long-term memory does not appear, check this page first to see whether the task is still running or has failed.
Organize memories with Dream
Dream generates organization suggestions for a group of existing memories. Go to Dream, click to create a task, enter a Scope, and provide organization instructions. For example:
Merge duplicate preferences, and keep the latest user profile and explicit to-do items.After you submit the task, it enters the running state. Dream must read and analyze existing memories, so processing usually takes longer than a regular query. After the task completes, it generates organization suggestions that are pending review. The page shows the suggestion type, target Scope, confidence level, and reason.
Dream suggestions are not applied automatically. Review each suggestion in detail, and apply or skip it only after you confirm that no valid information is lost.
Verify knowledge and memory with Agent chat
Agent chat lets you combine a model, knowledge bases, and memory stores for verification.
Go to Agent chat and expand Agent configuration on the right.
Adjust the temperature and system prompt of the model as needed.
Select knowledge bases, and set the TopK, retrieval type, and reranking method for each knowledge base, as well as the global aggregate TopK.
To use memory, select a memory store and enter
appId,tenantId, andagentId. Enable memory retrieval and set the memory TopK as needed. The console can generaterunIdautomatically, or you can enter it yourself.Return to the chat area, enter a question, and view the answer, the knowledge base citations, and the memories that were matched.
If you do not enable a memory store, the conversation history is kept on the current page and is lost after you refresh. After you enable a memory store, the conversation content is written to the memory store, and you can view the historical messages under the corresponding Scope in the memory store after you refresh the page.
Model-generated content may be inaccurate. For production operations, permissions, security, and business decisions, cross-check the content manually against the citations.
When you accept a combined question-answering result, verify at least the following three points:
The answer covers the question.
The knowledge base citations come from the expected documents.
The memory citations belong to the current Scope.
If any point does not meet your expectations, go back to the corresponding knowledge base or memory store and troubleshoot it separately.
Best practices
Use different AgentStorage instances for test workloads and production workloads to avoid mixing debugging data with production data.
Plan the subspaces and metadata fields before you create a knowledge base. Determine the storage mode and the Scope rules before you create a memory store.
Complete basic verification with the default retrieval configurations, and then adjust the parameters based on a real question set.
Run the retrieval test again after you update documents to confirm that the new content takes effect.
Before you delete an AgentStorage instance, knowledge base, memory store, or memory unit, confirm that it is no longer used and keep the necessary backups.
FAQ
Why is there no AgentStorage instance in the current region?
First confirm that the region at the top of the page is correct. Resources are not displayed cross-region. If no instance exists in the target region, create one and wait for the initialization to complete.
An "insufficient OSS permissions" message appears when I create a knowledge base or upload a document
Complete the authorization as prompted by the console dialog box, and confirm that the current account has the required permissions on the selected bucket and directory. A RAM user needs the account administrator to grant the permissions.
A document is uploaded, but its content cannot be retrieved
Check the document processing status, subspace, metadata filter conditions, retrieval type, and TopK in order. You can first remove the filter conditions and use the default parameters. After you confirm that basic recall works, add the conditions back one at a time.
The content that I just wrote cannot be found in the memory store
Confirm that the query and the write use the same appId, tenantId, agentId, and runId, and check whether a wildcard was used by mistake. Refresh the page and query again after the write.