Manage Memory Spaces

Feature overview

A memory space belongs to a Workspace and stores an Agent's long-term memory and session history. Create memory spaces as needed after you create the Workspace.

The resource summary on the Overview page counts the memory spaces created in the current Workspace.

Long-term memory

Long-term memory is information such as preferences, facts, and requirements that is extracted from submitted text or conversation messages. Your application can retrieve this information in later interactions to help an Agent understand the user.

For example, if a user says that restaurant recommendations should prioritize vegetarian options, that preference can become long-term memory. The Agent can use the preference in a later recommendation without requiring the user to repeat it in every session.

Use long-term memory to:

Save user preferences for personalized services.
Retain reusable facts and requirements across sessions.
Retrieve information in a business-specific scope to inform an Agent's response.

Submitted content and generated memories do not necessarily have a one-to-one relationship. Submitting text or a set of messages can generate multiple memories, or no new memory.

Session history

Session history is a record of messages organized by session. A session contains multiple messages, and each message uses a role and content to describe an interaction, such as a user question and an Agent response.

Use session history to identify the recorded sessions, the associated business users and Agents, and the messages in a specific session. It helps you review an interaction, understand the context of a request, and analyze Agent responses and interaction results.

Item	Long-term memory	Session history
Stored content	Preferences, facts, requirements, and other information extracted from input	Messages recorded in a session
Primary use	Retrieve and reuse information in later interactions	Review and trace an interaction
How to view	View the memory list or details, or run a semantic search	View the session list and then the messages in a selected session
Example	A user's preference for vegetarian restaurants	The message where the user expresses that preference and the Agent's response

Note

Creating a memory space only prepares the resource. Write data through a supported integration method before using it. A memory space does not automatically collect all Agent conversations, and displayed session history depends on the messages that your application submits.

Isolate memories with Scope

Scope organizes and isolates memories by business user, Agent, and session. Your application defines and submits all three fields.

Field	Meaning	Example
`userId`	user ID	`user-001`
`agentId`	Agent ID	`travel-agent`
`sessionId`	session ID	`session-001`

When you write a memory, provide these fields as needed to associate the memory with its business context. When you query long-term memory, a specified field performs an exact filter and an unspecified field does not filter results. If you specify multiple fields, a result must satisfy all specified fields.

For example:

Specify only userId to query a user's memories across Agents and sessions.
Specify userId and agentId to query memories associated with that user and Agent.
Specify all three fields to limit the query to one session for a user and Agent.

When you do not specify Scope filters, the query covers the current memory space without restricting these three dimensions. userId is a business field, not a RAM user or caller identity. Maintain these business IDs in your application and use them consistently when writing and querying memories.

Tag memories with Metadata

Metadata adds custom business tags to long-term memory, such as a category, source, or topic. Metadata consists of string key-value pairs.

Tag	Example value	Meaning
`category`	`dietary-preference`	A memory about dietary preferences
`source`	`conversation`	The memory originated from a conversation

Scope expresses the business ownership of a memory, while Metadata expresses its business attributes. Combine them when needed, such as when you filter dietary-preference memories within one user's memory scope.

Prepare to use memory spaces

Before you use a memory space, make sure that you have enabled AgentCore, created the target Workspace, and selected the target region and Workspace. Your account must also have the required permissions to access and manage memory spaces.

A memory space belongs to a Workspace in a specific region. Before you view data, verify that the selected region and Workspace are the same ones that you used to create the memory space. Create or switch Workspaces by using Manage Workspace.

Create a memory space

Log on to the AgentCore console.
Select the target region and Workspace. In the left-side navigation pane of the Workspace details page, choose Asset management > Memory Space.
Click Create Memory Space.
In the Create Memory Space dialog box, configure the following parameters.

Parameter	Description
Memory Space Name	Required. Enter 1 to 64 lowercase letters, digits, or hyphens (`-`), such as `travel-assistant`. The name must be unique within the current Workspace, but different Workspaces can use the same name.
Description	Optional. Enter up to 1,024 characters to describe the purpose of the memory space.

Click Create. Wait until the memory space status becomes Ready before writing or retrieving memories. Creation is asynchronous, so check the status instead of submitting another creation request while the memory space is not ready.

View memory spaces

On the Memory Space page, view the memory spaces in the list and use the search box to filter them by memory space name.

If no memory space has been created, the list displays No Memory Space.

View and use long-term memory

View the memory list and details

Open the target memory space to view its written long-term memories. Review the following information for each memory:

Memory content, including the saved preferences, facts, and requirements.
Scope, including the associated user ID, Agent ID, and session ID.
Metadata tags, such as category and source.
The memory ID, which uniquely identifies the memory.

If the memory space has no data, write content through an application integration or API before viewing memories.

Filter memories

Set filters that match your business need. For example, to inspect a user's dietary preferences, specify the user's userId and use a relevant Metadata tag.

Viewing need	Scope condition
Memories for one user	`userId`
Memories for one Agent	`agentId`
Memories for one session	`sessionId`
Memories for one user and Agent	`userId`, `agentId`
Memories for one user in a specified session	`userId`, `sessionId`

These are the filtering semantics for memory queries. The filters available in the console depend on the options shown on the page.

Search for relevant memories

Use semantic search to find memories that are relevant to a natural-language question. For example, enter What dietary preferences does the user have? to find information about dietary preferences.

Combine Scope and Metadata to narrow the search. Returned results are also affected by the result count, similarity, and reranking settings. Use a list query to browse memories and semantic search to find information relevant to a question. To confirm whether a specific memory exists, view the list or query it by memory ID.

Maintain memories

Update a memory when a user preference changes or a memory needs correction, and delete a memory that is no longer needed. APIs support querying, updating, and deleting a memory by memory ID. Available console operations depend on the options shown on the page.

For example, when a user changes a preference from vegetarian restaurants to vegetarian or seafood restaurants, update the corresponding long-term memory.

View session history

View the session list

Open the target memory space to view session history and identify recorded sessions and their business ownership. User IDs, Agent IDs, and session IDs help distinguish interactions. One user can interact with multiple Agents or have multiple sessions with the same Agent.

View session messages

Select a session to view its messages and roles, then review the interaction between the user and Agent. Use the session's business ownership to identify the intended session and avoid confusing sessions with the same name that belong to different users or Agents.

Note

Session history displays message records, while long-term memory displays extracted information. Messages that do not generate new memories can still appear in session history.

View memory space information

On the memory space management page, view the name, description, and status of a memory space. You can read and write memories after the status becomes Ready.

Update the description

Update the description to identify the purpose of the memory space and distinguish memory spaces used by different business scenarios.

Delete a memory space

Delete a memory space that you no longer need. Deletion is asynchronous, so wait for the operation to finish.

Warning

Deleting a memory space deletes its data. Re-creating a memory space with the same name does not restore deleted data. Before deleting a memory space, verify the target region, Workspace, and memory space.

Integrate a memory space with an Agent or application

To let an Agent use memory in later interactions, complete the following workflow:

Write content by submitting text or conversation messages to the memory space and associating them with Scope and Metadata.
Retrieve memories within the appropriate business scope when you receive a new question.
Provide retrieved memories together with the current question to the model when you generate a response.

For example, when a travel assistant receives a restaurant recommendation request in a new session, retrieve the user's dietary preferences by user ID and use those preferences when generating the response.

Use a supported SDK or API to integrate memory capabilities. The following APIs are available:

Capability	API
Create, view, list, update, and delete memory spaces	`CreateMemoryStore`, `GetMemoryStore`, `ListMemoryStores`, `UpdateMemoryStore`, `DeleteMemoryStore`
Write memories	`AddMemories`
Search memories semantically	`SearchMemories`
List, query, update, and delete memories	`ListMemories`, `GetMemory`, `UpdateMemory`, `DeleteMemory`
View session lists and messages	`ListMemorySessions`, `ListMemorySessionMessages`

MemoryStore remains the API resource name for a memory space.

Frequently asked questions

Does an Agent automatically remember every conversation after I create a memory space?

No. Creating a memory space only prepares the resource. Configure a supported integration method or submit text and conversation messages from your application. The memories that your application uses, and when it writes and retrieves them, depend on your integration workflow.

What is the difference between long-term memory and session history?

Use session history to review messages and interactions. Use long-term memory to retain reusable information and retrieve it later. For example, a user's vegetarian request and the Agent's response are session history, while the user's preference for vegetarian restaurants is long-term memory.

How should I choose Scope and Metadata?

Use Scope for business ownership, such as the user, Agent, and session. Use Metadata for business attributes, such as category and topic.

For example, for dietary preferences of user user-001, store the user ID in Scope and the dietary-preference category in Metadata.

Why cannot I find an expected memory?

Verify the selected region, Workspace, and memory space. Then check whether the input content was submitted and whether the filters are correct. Submitted input and generated memories do not have a guaranteed one-to-one relationship, so use the actual write result as the reference.

Why does a memory appear in the list but not in semantic search results?

Semantic search depends on the query text, Scope, Metadata, result count, and retrieval threshold. It does not guarantee that it returns every memory that matches a filter. To confirm that a specific memory exists, view the list or query it by memory ID.

Why did a query return memories from other sessions?

When you query long-term memory without sessionId, the query does not restrict the session and can return memories across sessions. To limit results to one session, provide the corresponding sessionId. Likewise, omitting userId or agentId does not restrict that dimension.

References

Overview helps you view the runtime status of the Agents in a Workspace and its resource summary.