Store and use short-term memory

In your AI agent, you need to write code to add the interactions/messages as events in AgentCore Memory that you created. These events are stored as short-term memory. You can use the following operations to manage the short-term memory

Create event

Events are the fundamental units of short-term and long-term memory in AgentCore Memory. The CreateEvent operation allows you to store various types of data within an AgentCore Memory, organized by an actor and session. Events are scoped within memory under:

CreateEvent operation stores a new immutable event within a specified memory session. Events represent individual pieces of information that your agent wants to remember, such as conversation messages, user actions, or system events.

This operation is particularly useful for:

The CreateEvent operation stores a new immutable event within a specified memory session. Events represent individual pieces of information that your agent wants to remember, such as conversation messages, user actions, or system events. This operation is particularly useful for:

Event payload types

The payload parameter accepts a list of payload items, allowing you to store different types of data in a single event. Common payload types include:

Event branching

The branch parameter enables advanced event organization through branching. This is particularly useful for scenarios like message editing, alternative conversation paths, or concurrent event streams.

When creating a branch, you specify:

Here's an example of creating a branched event to represent an edited message:

{
  "memoryId": "mem-12345abcdef",
  "actorId": "/agent-support-123/customer-456",
  "sessionId": "session-789",
  "eventTimestamp": 1718806000000,
  "payload": [
    {
      "Conversational": {
        "content": "I'm looking for a waterproof action camera for extreme sports.",
        "role": "user"
      }
    }
  ],
  "branch": {
    "name": "edited-conversation",
    "rootEventId": "evt-67890"
  }
}
        

The following example shows that when a user edits a previous message, the agent can fork the history at that point:

// Original conversation sequence
const originalMessages = [
  { role: "user", message: "I need a waterproof camera" },
  { role: "assistant", message: "We have several waterproof cameras. What's your budget?" },
  { role: "user", message: "Around $300" }
];

// User edits their first message to change the request
const editedMessage = { 
  role: "user", 
  message: "I need a waterproof action camera for extreme sports" 
};

// Find the event to branch from
const events = await dataPlaneClient.listEvents({
  memoryId,
  actorId: "/agent-support-123/customer-456",
  sessionId: "session-789"
});

const eventToBranchFrom = events.events[0]; // The first message

// Create a new branch starting from the edited message
const forkedEvent = await dataPlaneClient.createEvent({
  memoryId,
  actorId: eventToBranchFrom.actorId,
  sessionId: eventToBranchFrom.sessionId, 
  eventTimestamp: timestamp,
  payload: [
    {
      Conversational: {
        message: editedMessage.message,
        role: editedMessage.role
      }
    }
  ],
  branch: {
    name: "edited-conversation",
    rootEventId: eventToBranchFrom.eventId
  }
});

Get event

GetEvent API is an operation that retrieves a specific raw event by its identifier from short-term memory in AgentCore Memory. This API requires you to specify the memoryId, actorId, sessionId, and eventId as path parameters in the request URL, allowing you to precisely target individual events within your memory sessions.

List events

ListEvents API is a read-only operation that lists events from a specified session in an AgentCore Memory instance. This paginated API requires you to specify the memoryId, actorId, and sessionId as path parameters, and supports optional filtering through the filter parameter in the request body, allowing you to efficiently retrieve relevant events from your memory sessions. You can control whether payloads are included in the response using the includePayloads parameter (default is true), and limit the number of results with maxResults.

The ListEvents API is particularly valuable for applications that need to reconstruct conversation histories, analyze interaction patterns, or implement memory-based features like conversation summarization and context awareness.

Delete event

The DeleteEvent API removes individual events from your AgentCore Memory, enabling fine-grained control over conversation history and interaction data. This API helps maintain data privacy and relevance by allowing you to selectively remove specific events from a session while preserving the broader context and relationship structure within your application's memory. Note that these are manual deletion operations, and do not overlap with automatic deletion of events based on the eventExpiryDuration parameter set at the time of CreateEvent operation.

The API requires memory ID, actor ID, session ID, and event ID parameters to precisely target the specific event for deletion. Upon successful execution, the API returns the ID of the deleted event as confirmation that the operation completed successfully.