AgentCore Memory in Practice: How Short-Term and Long-Term Memory Work Across Sessions

An agent that forgets once its reply ends is the default behavior, but for a replenishment assistant it is the wrong behavior. AWS AgentCore's memory capability tries to solve this: a single memory resource carries both a short-term event log and long-term extracted records, so the agent still remembers the manager's regional preference in a brand-new session.

Business scenario: why agents need to remember

Northwind Gear operates forty stores and replenishes every Monday. A store manager once told the replenishment assistant to focus only on the North China region. The following Monday, in a new session, the assistant asked again which region. The model itself was fine—that sentence never left the session in which it was spoken, and subsequent sessions had no way to look it up.

This case reveals the fundamental limitation of the default stateless agent: the session boundary equals the memory boundary. Three of AWS AgentCore's nine capabilities support this scenario—Memory provides the memory resource, Runtime hosts the agent and allocates a separate microVM per session, and Identity uses the actor id as the partition key for the memory namespace.

MicroVM is a lightweight virtual machine implemented by AWS on top of Firecracker technology. Compared with traditional virtual machines, MicroVMs start quickly (in milliseconds), have low memory overhead, and provide the same level of security isolation as hardware virtualization. In AgentCore Runtime, each session is allocated a separate MicroVM, which means the file system, memory, and processes are fully isolated between sessions. This isolation mechanism also explains why agents cannot retain state across sessions by default—because a new session runs in a brand-new, clean MicroVM, and the memory state of the previous session simply does not exist. To achieve cross-session memory, you must rely on an external persistence service, which is exactly the problem AgentCore Memory solves.

The two halves of memory: short-term events and long-term records

AgentCore's memory resource puts short-term and long-term in the same resource, but the mechanisms are completely different. Short-term memory is an append-only event log keyed by actor and session; long-term memory consists of records the service extracts from those events and writes into namespaces.

The key point: the agent itself never stores preferences. It only appends conversation turns and then asks the service questions. The act of writing an event simultaneously triggers the extraction process, which is why the second session can find what the first session said. Extraction is not part of the invocation—the CLI returns within 19 seconds (of which 12,117 ms is the model call), and the records arrive later.

The actor id (participant identifier) is a unique identifier that AgentCore Identity assigns to each invoking principal, usually corresponding to a user or customer identity. In the memory scenario, the actor id plays the role of a namespace partition key: all memory records related to that user belong under a path prefixed with the actor id. This way, different users' memories are naturally isolated, and no additional filter conditions need to be written at query time. The difference between an actor id and a session id is that a session id identifies a single session, whereas an actor id identifies a long-lived principal (such as a store manager), so the actor id remains constant across multiple sessions while the session id changes every session. Embedding the actor id in the namespace template (e.g., /users/{actorId}/preferences) achieves a design where "isolation is a property of the keyspace."

Namespace design: isolation as a property of the keyspace

The memory resource uses three strategies to determine the form long-term records take: the USER_PREFERENCE strategy writes preferences to /users/{actorId}/preferences; the EPISODIC strategy writes episodes to /episodes/{actorId}/{sessionId}, with reflection records written to the parent level /episodes/{actorId}; and the SEMANTIC strategy writes facts to /users/{actorId}/facts.

Putting the actor id into the namespace template means isolation is an inherent property of the keyspace, not a filter that some code path needs to remember to add. The reflection namespace sits above a single session, so a prefix read on /episodes/{actorId}/ retrieves both individual episodes and the lessons written across all episodes.

Retrieval timing: put it in the system prompt, not the tool

Retrieval happens before the model is called, because the records become part of the system prompt. Each invocation creates a brand-new Agent rather than reusing one per session. A cached Agent would keep serving the first turn's recollections, and retrieval failures are logged and swallowed—an agent that can't remember is still usable.

Putting retrieval into the system prompt rather than a tool is an architectural choice worth noting: the model does not depend on choosing to call a tool, and the memory is always already in context.

The system prompt is a set of instructions or context injected before the conversation history each time a large language model is called, used to set the model's behavior, role, and available background knowledge. Unlike tool calls, the system prompt is input that the model necessarily sees on every inference, and the model does not need to actively choose whether to read it. In AgentCore's memory architecture, retrieved long-term records are concatenated into the system prompt, so the model already has the relevant memory when generating its reply, avoiding the problem of memory going unused because "the model forgot to call the tool" or "the model chose not to call the tool." Moving retrieval ahead of the model call also means retrieval results are deterministic and executed every time, rather than depending on the model's decisions. This design improves memory reliability but increases the number of input tokens per call (with a corresponding rise in cost).

Empirical validation: three assertions and one independent check

The smoke tests run after deployment contain four assertions, all of which pass:

• The second session can retrieve the preference written in the first session;
• Actor A cannot retrieve actor B's memory;
• The EPISODIC strategy can recall a previously failed approach ("the Guangzhou warehouse cannot be used for North China replenishment");
• No other use case's resources leak in.

The North region manager and the South region manager each write to their own preference namespace, and a semantic query "which region does this store manager replenish for" returns North China for one and South China for the other. There is no filter that can be written wrong, because the actor id is part of the key.

Extraction latency: episodic memory is slower than expected

The third assertion led to an unexpected finding: episodic extraction is slow, and episodes are written about fifteen minutes after the event occurs. In the test, the preference record's extraction was visible within 1.5 seconds, but that was because the preference had already been extracted by a previous run against the same resource; a new episode took 959 seconds. This is not a broken strategy but a slower queue—a 300-second timeout would simply fail.

A prefix read on /episodes/store_manager_north/ returns two kinds of records: the BASE episode archived under the session that produced it, and the REFLECTION written at the parent level. That is why one template contains {sessionId} and the other does not.

The EPISODIC strategy is one of the three long-term memory extraction strategies supported by AgentCore Memory, used to record and recall specific events or experiences (episodes), such as "the last time we tried to replenish, the Guangzhou warehouse failed." Alongside it are the USER_PREFERENCE strategy (extracting user preferences, such as "focus only on North China") and the SEMANTIC strategy (extracting factual knowledge, such as "the North China region includes Beijing, Tianjin, etc."). EPISODIC records usually contain two types: BASE and REFLECTION. BASE is the archive of the event itself, attached to the session that produced it; REFLECTION is a higher-level reflection or summary of the event, attached at the actor level. Because episodic extraction requires more complex post-processing (such as association and generalization), its asynchronous queue is usually slower than preference extraction, with measured latency of up to 15 minutes.

Cost and troubleshooting

A single traced invocation consumed 3,433 input tokens and 210 output tokens across two model calls, costing about $0.0025 at $0.62 and $1.85 per million tokens. Memory storage and extraction calls are billed separately, and this item was not measured in the original article.

Two typical troubleshooting points: a session id shorter than 33 characters fails before sending (a hexadecimal uuid is only 32 characters—one short); episodic records not appearing within 1500 seconds does not mean the strategy is broken, you just need to raise the deadline beyond the observed fifteen minutes.

Key takeaways

Memory is two mechanisms, not one: the event log you write, and the records the service extracts. Only the latter survives across sessions. Put the actor id into the namespace template, and isolation is zero-cost and cannot be forgotten by some code path. Extraction is asynchronous and slow, so every assertion needs a timeout, and every timeout needs to be longer than you think. Retrieval belongs in the system prompt, before the model call, not in a tool the model may or may not choose. Teardown is genuinely two steps: remove all clears the contract, and the subsequent deployment performs the deletion.

One-line Summary

AWS AgentCore Memory enables cross-session memory through an event log and asynchronously extracted records, with lessons for isolation and retrieval design.

Paragraph Summary

Using a replenishment assistant as an example, this article explains how AWS AgentCore solves the problem of agents forgetting across sessions. AgentCore Memory combines a short-term event log with long-term extracted records in a single resource, uses namespace templates with the actor id as a partition key for natural isolation, and injects retrieval results into the system prompt rather than relying on tool calls. Empirical tests validated preference retrieval, actor isolation, and episodic memory, but also revealed that EPISODIC extraction takes about 15 minutes. The article also provides cost estimates (about $0.0025 per call) and troubleshooting advice (session id length, timeout settings), emphasizing that memory is two mechanisms, isolation is a keyspace property, and retrieval should happen before the model call.