Memory Space overview

Updated at:
Copy as MD

When an Agent needs to store and retrieve information beyond a single run, it requires a dedicated location for that content. Memory Space is an independent resource in AgentCore that provides Agents with persistent memory capabilities.

Memory Space and integration methods

You can create separate Memory Spaces for different business purposes and access their memory capabilities through Model Context Protocol (MCP) or Software Development Kit (SDK). MCP exposes memory read and write operations as standard tools, suitable for Agents that consume memory through tool calls. SDK allows application code to call Memory Space directly, giving pro-code applications more flexible control over memory reads and writes. For the differences and selection criteria, see Choose an integration method.

After you enable MCP in a Memory Space, AgentCore deploys a corresponding MCP service for that Memory Space and identifies it as a Memory Space resource. This MCP is system-generated, remains associated with the Memory Space, and appears in both Tool Management and Agent Asset Configuration for viewing and selection.

Relationship between Agents and Memory Spaces

An Agent's own conversation history is not equivalent to the history in a Memory Space. After content is written to a Memory Space, the system distills reusable information from it and saves the results as long-term memory. The three concepts differ as follows:

ConceptContent recorded
Agent conversation historyThe actual interactions of that Agent. Not automatically synced to any Memory Space.
Memory Space conversation historyThe raw conversation content actually written to that Memory Space.
Long-term memoryReusable information distilled by the system from the raw conversation content written to the Memory Space.

Mounting a Memory Space to an Agent does not mean all of the Agent's conversation history is automatically synced to that Memory Space, nor does it mean an Agent can only use one Memory Space. You must decide which Memory Spaces an Agent uses based on business purposes, and control which Memory Space to read from and write to in different scenarios. After completing memory tool integration, you can encode these rules in the Agent's system prompt or encapsulate them as a Skill for the Agent to use — for example, specifying when to read memory, what content to write, which Memory Space corresponds to which business scenario, and what content should not be saved.

Use cases

Use Memory Spaces when an Agent needs to persistently store and retrieve information across multiple runs. Based on the Agent's scope of responsibility and memory isolation approach, there are three usage patterns.

Single Agent with a dedicated Memory Space

When an Agent has a relatively fixed scope of responsibility and related information can accumulate continuously within the same memory boundary, mount a dedicated Memory Space to that Agent. For example, a dedicated account manager Agent, personal assistant Agent, or long-term project tracking Agent can query the same Memory Space before responding and continuously write conversation content that remains useful to that Space. This pattern means the Agent uses one Memory Space for its business, but mounting does not mean all Agent conversations are automatically synced. You still need to specify through the Agent's prompt or application code when to read memory, what content to write, and what information should not be saved.

Multiple Agents with scenario-based Memory Spaces

When a business encompasses multiple relatively independent domains and information from different domains requires separate management, set up multiple Agents and multiple Memory Spaces by scenario. For example, a customer service business can set up a pre-sales Agent, an order service Agent, and an after-sales Agent, mounted with "Pre-sales Service", "Order Service", and "After-sales Service" Memory Spaces respectively: the pre-sales Agent saves customer requirements and product preferences in the "Pre-sales Service" Memory Space, the order service Agent saves order confirmations and delivery progress in the "Order Service" Memory Space, and the after-sales Agent saves returns and fault resolution information in the "After-sales Service" Memory Space.

Each Agent can use only the Memory Spaces relevant to its responsibilities, or mount multiple Memory Spaces based on business workflows. There is no requirement for a fixed one-to-one mapping between Agents and Memory Spaces. Dividing Agents and Memory Spaces by scenario gives different business domains relatively independent conversation histories and long-term memories, preventing all information from mixing into a single memory boundary.

Unified entry Agent routing to multiple Memory Spaces

When a business uses a unified entry or routing Agent that has access to multiple Memory Spaces, define the scenario-to-Memory-Space mapping in the prompt. For example, pre-sales inquiries map to the "Pre-sales Service" Memory Space, order confirmations or delivery progress map to the "Order Service" Memory Space, and returns or fault reports map to the "After-sales Service" Memory Space. When a single request involves multiple scenarios, process each part according to its content affiliation rather than writing all content to every Memory Space. When the scenario cannot be determined, confirm with the user first. For mapping rule examples, see Prompt example for scenario-based multi-Memory-Space usage.

Integration process

Prerequisites

  • The target Agent that requires memory capabilities has been created. Mounting is done on the Agent Asset Configuration page of the target Agent.

  • You have determined whether to integrate through MCP or SDK. Choose either method based on your application type; both are not required simultaneously.

  • For MCP: Enabling MCP and mounting to an Agent are two independent steps. Enabling MCP makes the memory capability available for selection; mounting determines whether the current Agent can invoke that capability. Mounting only means the Agent's runtime environment can access the corresponding tools. Pro-code Agents additionally need application code to integrate MCP tools into the Agent framework or model invocation flow, and handle tool calls and result returns.

  • For SDK: Refer to the corresponding SDK user guide for specific integration and invocation methods.

Plan memory boundaries

First determine which information requires long-term retention based on business purposes, and whether different business domains need separate management. An Agent can mount one or more Memory Spaces. If content, usage purposes, or management requirements differ across scenarios, create separate Memory Spaces.

Create a Memory Space

Create or select a Memory Space in AgentCore and complete the configuration as prompted. If you need to distinguish multiple business scenarios, create corresponding Memory Spaces according to your plan.

Choose an integration method

Memory Spaces can be accessed through MCP or SDK. Choose either method based on your application type; both are not required simultaneously. The selection depends on who orchestrates memory reads and writes: MCP exposes memory capabilities as standard tools, with reads and writes triggered by model tool calls and guided through prompts. SDK allows application code to directly orchestrate reads and writes.

ComparisonMCPSDK
Integration approachEnable MCP in the Memory Space, then mount it on the Memory Space tab of the target AgentCall Memory Space through application code
Read/write orchestrationTriggered by model tool calls; requires prompt guidance for read and write timingApplication code controls when to read or write memory, which Memory Space to use, and what conversation content to write
Suitable forProviding memory capabilities to Agents as standard toolsPro-code applications, custom-built Agents, or custom business workflows such as multi-scenario routing and conditional reads/writes
Remaining steps after integrationPro-code Agents need application code to integrate MCP tools into the Agent framework or model invocation flow, and handle tool calls and result returnsRefer to the corresponding SDK user guide for specific integration and invocation methods

Pro-code applications are not limited to SDK: after mounting a Memory Space MCP, application code can also integrate MCP tools, with prompts guiding model invocation.

Mount through MCP

MCP integration consists of two independent steps: enabling MCP and mounting to an Agent.

Enable MCP

  1. Enable MCP in the target Memory Space.

  2. Confirm that the MCP has entered the Memory Space resource catalog. Only MCPs enabled through a Memory Space enter this catalog. Regular MCPs are not recognized as Memory Spaces by the system, even if they use the same name or user tags.

Mount to an Agent

  1. Go to the Agent Asset Configuration page of the target Agent.

  2. Mount the required resources on the Memory Space tab. Mounting determines which Memory Spaces the current Agent can use.

  3. On the Tools tab, confirm that the MCP displays the Memory Space badge, indicating the mount is effective. The actual invocable tool names, parameters, and supported memory capabilities are subject to the tool list displayed after mounting.

Note

In Agent Asset Configuration, the Memory Space tab is a dedicated view for Memory Space MCPs, while the Tools tab shows all MCPs available for mounting to the current Agent. Both tabs share the same mount records — mounting or removing from either tab syncs the result. No separate configuration is needed.

Important

Mounting does not automatically write all of the Agent's conversation history to the Memory Space. You must still define read and write targets as described in Configure read and write rules.

Orchestrate memory reads and writes through SDK

Pro-code applications are those where developers build Agents or customize business workflows through application code. These applications can call Memory Spaces through SDK, with application code controlling when to read or write memory, which Memory Space to use, and what conversation content to write to the target Space. This approach suits custom requirements such as multi-scenario routing and conditional reads/writes. Unlike the standardized MCP mounting approach, SDK read/write orchestration does not depend on model tool calls. Refer to the corresponding SDK user guide for specific integration and invocation methods.

Configure read and write rules

Regardless of whether you use MCP or SDK, you must define the read and write targets for each scenario based on business logic. Only conversation content actually written to a Memory Space becomes that Space's conversation history and is subsequently used to distill long-term memory. Agent conversations not written to a Memory Space do not belong to that Space's history. Read and write rules can be encoded in the Agent's system prompt or implemented through application code. For specific patterns, see Customize memory usage.

Customize memory usage

A Memory Space is not an automatic mirror of Agent conversation history, nor does it prescribe a fixed Agent mapping. Memory read, write, scenario routing, and content filtering patterns can be designed according to business objectives — for example, consolidating long-term information from a single Agent, saving only specific content types, or letting multiple Agents share a category of memory. These rules can be written into the Agent's system prompt or encapsulated as a Skill. The following examples use system prompts.

Complete tool integration

Mounting a Memory Space MCP only means the Agent's runtime environment can access the corresponding tools — it does not mean the model will automatically invoke them. Pro-code Agents additionally need application code to integrate MCP tools into the Agent framework or model invocation flow, and handle tool calls and result returns.

Guide memory reads and writes through system prompts

After completing tool integration, add memory usage rules to the Agent's system prompt to guide the model on when to read or write memory and which Memory Space to use. The prompt can also specify what content to save, the mapping between business scenarios and Memory Spaces, how to handle ambiguous scenarios, and what sensitive or temporary information should not be saved. The following prompts are for reference only. Adjust them based on your actual tools, model capabilities, and business scenarios, and verify effectiveness before production use.

Prompt example for a single dedicated Memory Space

If an Agent uses a single dedicated Memory Space, refer to the following pattern and adjust based on your actual business, tool definitions, and retention scope:

You have access to memory capabilities in "<Memory Space name>".

Before responding to a user, if the current question may relate to the user's historical preferences, confirmed information, or pending items, search that Memory Space first and use only content relevant to the current user and current question.

When the current interaction produces new information that remains useful afterward, write the relevant raw conversation content to that Memory Space — for example, stable preferences, explicit requirements, confirmed decisions, and follow-up items. Do not write passwords, verification codes, access keys, irrelevant chitchat, or temporary information valid only in the current turn.

If no relevant memory is retrieved, continue processing based on the current conversation. Do not fabricate historical information.

When the model can correctly understand and invoke the relevant tools, this pattern guides the Agent to read from and write to the same Memory Space. Regardless of prompt configuration, only content for which the write tool is actually invoked enters the Memory Space.

Prompt example for scenario-based multi-Memory-Space usage

If multiple Agents handle different business scenarios, refer to the following approach: specify each Agent's responsibilities and default Memory Space in its system prompt. For example, the pre-sales Agent's prompt can include:

Your responsibility is to handle requests related to "<business scenario>". Use "<corresponding Memory Space>" by default.

Before processing a request, if you need to understand historical requirements, confirmed information, or pending items for that scenario, search that Memory Space first. Write only raw conversation content that belongs to the current business scenario and remains useful afterward to that Memory Space.

If a request does not belong to the current business scenario, do not write the related content to the current Memory Space. When you cannot determine whether content belongs to the current business scenario, do not write it.

Do not read from or write to Memory Spaces unrelated to your current responsibility, even if other memory tools are available.

Following this approach, configure corresponding prompts for the pre-sales Agent, order service Agent, and after-sales Agent, with default Memory Spaces set to "Pre-sales Service", "Order Service", and "After-sales Service" respectively.

If a unified entry or routing Agent is also configured with access to multiple Memory Spaces, further define the scenario-to-Memory-Space mapping in its prompt:

Before performing memory operations, determine the scenario of the current request:
- Pre-sales inquiries: use the "Pre-sales Service" Memory Space.
- Order confirmations or delivery progress: use the "Order Service" Memory Space.
- Returns or fault reports: use the "After-sales Service" Memory Space.

Search and write only to the Memory Space corresponding to the current scenario. When a single request involves multiple scenarios, process each part according to its content affiliation — do not write all content to every Memory Space. When the scenario cannot be determined, confirm with the user first.

Limitations of prompts

Prompts only guide how the model uses tools that have already been integrated. They do not replace tool integration, resource mounting, or access control. When strict isolation is required, mount only the Memory Spaces within each Agent's scope of responsibility, and implement necessary scenario determination, read/write routing, and content filtering rules through application code.

Differences between Memory Space MCP and regular MCP

The following applies only to MCPs enabled from a Memory Space. A Memory Space MCP is a system-provided controlled entry point. It points to the same MCP as the corresponding entry in Tool Management — no separate creation or maintenance is required.

ComparisonRegular MCPMemory Space MCP
SourceUser-createdSystem-generated after MCP is enabled in a Memory Space
Configuration scopeFully configurableOnly log configuration and credentials are adjustable. All other settings are system-generated and locked as read-only.
Memory Space resource catalogNot included. Even with the same name or user tags, the system does not recognize it as a Memory Space.Included. Can be mounted to Agents as a Memory Space resource.
Viewing and adjustmentCreated and maintained in Tool ManagementView basic information and tool capabilities in Tool Management; to adjust the Memory Space itself, return to the Memory Space

Common misconceptions

The following lists frequent misconceptions when using Memory Spaces, organized by symptom, cause, and resolution. For the full causal relationship, see Relationship between Agents and Memory Spaces.

SymptomCauseResolution
Memory Space is mounted but the Agent does not read or write memoryMounting only means the Agent's runtime environment can access the tools — the model does not automatically invoke them. Pro-code Agents additionally need application code to integrate MCP tools into the Agent framework or model invocation flow.After completing tool integration, add memory usage rules to the system prompt and verify effectiveness before production use.
Some Agent conversations do not appear in the Memory SpaceMounting does not automatically sync all Agent conversation history. Only content for which the write tool is actually invoked enters the Memory Space.Define the write scope, read timing, and content exclusions through prompts or application code.
Target resource not found on the Memory Space tabOnly MCPs enabled through a Memory Space enter the Memory Space resource catalog.Enable MCP in the Memory Space first, then mount the corresponding resource.
Memory Space history differs from the Agent's own conversation historyMemory Space conversation history records only the raw content actually written. After writing, the system further distills long-term memory from it.Determine read and write targets for each scenario based on business purposes.

Related information

  • For SDK integration and invocation methods, refer to the corresponding SDK user guide.

  • The actual invocable tool names, parameters, and supported memory capabilities are subject to the tool list displayed after Memory Space MCP mounting, the AgentCore console, and the corresponding user guides.