Agent Memory

Short-Term Memory

Short-term memory (STM) stores raw conversation history in chronological order. The platform records each turn in real time as it occurs. When your agent requires immediate conversational context from recent turns, it reads from STM.

From Conversation Turns to Memory

The Atlas Agent Engine converts conversational turns into durable memory through a three-stage lifecycle:

• Turn recording: As the agent interacts with users, the platform records each turn to short-term memory.

• Snapshot generation: When a session reaches a configured message count or idle threshold, a background process compiles the conversation history into a summarized snapshot.

• LLM extraction: A large language model (LLM) analyzes the snapshot and extracts durable knowledge into the appropriate long-term memory types.

Because extraction runs asynchronously, recording turns never blocks the agent's response. Knowledge extracted from a session becomes available in long-term memory for subsequent conversations rather than on the immediate next turn. Recent turns remain immediately available through short-term memory, and extracted knowledge appears shortly afterward.

Long-Term Memory

Long-term memory persists across sessions and holds durable knowledge distilled from conversations. The platform creates long-term memory either by distilling short-term memory or through direct writes.

For platform-deployed agents, the platform automatically records conversations as short-term memory and distills long-term memory from it, though agents can write long-term memory directly when needed. External applications typically write short-term memory using the software development kit (SDK) for platform distillation. They can also write long-term memory directly, through the SDK or the memory Model Context Protocol (MCP).

Semantic Memory

Semantic memory stores labeled facts about a user or an application. A fact is knowledge that stays relevant beyond the conversation that produced it. For example, a fact can capture a user's home airport or their preference for window seats.

The Atlas Agent Engine creates semantic memory through background extraction and direct writes:

• Background extraction: Extracts facts from conversation snapshots and consolidates duplicate or updated information over time.

• Direct writes: Save a fact with save_semantic(label=..., text=...).

To retrieve a fact, use get_semantic to look it up by label or search_semantic to find facts by meaning. Semantic memory is included by default in build_context, so the relevant facts appear in the context your agent retrieves.

The following example saves a fact, retrieves it by label, and searches the chat by meaning:

from agentic_platform_memory import (
    Memory,
    MemoryRequestContext,
)
memory = Memory(
    api_key="<your-access-token>",
    project_id="<your-project-id>",
)
chat = memory.bind(
    MemoryRequestContext(
        user_id="user_1",
        session_id="thread_123",
    )
)
chat.save_semantic(
    label="home-airport",
    text="The user's home airport is Boston.",
)
fact = chat.get_semantic("home-airport")
hits = chat.search_semantic("home airport")

Episodic Memory

Episodic memory stores past conversations as summarized episodes. An episode captures what happened in a conversation, including the decisions made and the outcomes that followed. Episodic memory answers what an agent should know about a user's past interactions.

The Atlas Agent Engine creates episodic memory through background extraction and direct writes:

• Background extraction: Extracts episodes and their participants from conversation snapshots.

• Direct writes: Save an episode with save_episode(title=..., content=...).

Episodes persist across conversations. An agent can recall what happened in one conversation during a later conversation.

To retrieve episodes, use search_episodes to find them by meaning or list_episodes to list a user's episodes. Episodic memory is one of the default sources in build_context, so relevant episodes are included.

The following example saves an episode, searches for it, and lists a user's episodes:

from agentic_platform_memory import (
    Memory,
    MemoryRequestContext,
)
memory = Memory(
    api_key="<your-access-token>",
    project_id="<your-project-id>",
)
chat = memory.bind(
    MemoryRequestContext(
        user_id="user_1",
        session_id="thread_123",
    )
)
chat.save_episode(
    title="Vacation planning",
    content="Planned a summer trip to Lisbon.",
)
episodes = chat.search_episodes("trip to Lisbon")
recent = chat.list_episodes()

Procedural Memory

Procedural memory stores reusable procedures: the step-by-step workflows an agent follows to complete a specific task. A procedure captures how to do something, such as comparing flight options or processing a refund request.

The Atlas Agent Engine creates procedural memory through background extraction and direct writes:

• Background extraction: Extracts reusable procedures from conversation snapshots.

• Direct writes: Save a procedure with save_procedure(procedure=..., description=..., content=...).

To retrieve procedures, use discover_procedures to find candidates by query or get_procedure to load the full procedure by name. Procedural memory requires explicit opt-in in build_context, not the semantic and episodic defaults.

The following example saves a procedure and retrieves it:

from agentic_platform_memory import (
    Memory,
    MemoryRequestContext,
)
memory = Memory(
    api_key="<your-access-token>",
    project_id="<your-project-id>",
)
chat = memory.bind(
    MemoryRequestContext(
        user_id="user_1",
        session_id="thread_123",
    )
)
chat.save_procedure(
    procedure="compare-flights",
    description="Compare flight options.",
    content="Rank flights by price, stops, and total travel time.",
)
candidates = chat.discover_procedures("compare flights")
full = chat.get_procedure("compare-flights")

Taxonomic Memory

Taxonomic memory stores domain terms and their definitions. A term defines the meaning of a word within a domain, such as what a red-eye is in travel management. Unlike user-scoped memories, taxonomic memory is shared domain knowledge available across all users and conversations in a project.

The Atlas Agent Engine creates taxonomic memory through background extraction and direct writes:

• Background extraction: Extracts terms and their domains from conversation snapshots.

• Direct writes: Save a term with save_taxonomic(domain=..., term=..., definition=...).

To retrieve a term, use get_taxonomic_term to look it up by domain and term, or search_taxonomic to find terms by meaning. Use list_domains to list the domains your project has. Taxonomic memory requires explicit opt-in in build_context.

The following example saves a term, reads it, and searches for it:

from agentic_platform_memory import (
    Memory,
    MemoryRequestContext,
)
memory = Memory(
    api_key="<your-access-token>",
    project_id="<your-project-id>",
)
chat = memory.bind(
    MemoryRequestContext(
        user_id="user_1",
        session_id="thread_123",
    )
)
chat.save_taxonomic(
    domain="airline",
    term="red-eye",
    definition="An overnight flight that lands the next morning.",
)
definition = chat.get_taxonomic_term("airline", "red-eye")
matches = chat.search_taxonomic("overnight flight", domain="airline")
domains = chat.list_domains()

Distinguishing Between Types

If information appears to span multiple categories, evaluate where it falls along these operational boundaries:

• Fact versus Event (Semantic versus Episodic): Semantic memory stores a current state or truth, such as a traveler's preferred seat or home airport. Episodic memory stores the historical narrative of the interaction where that preference was discussed or used, such as a past flight booking conversation.

• Knowledge versus Execution (Semantic versus Procedural): Semantic memory provides facts the agent recalls, such as baggage allowance limits. Procedural memory provides instructions the agent executes, such as the sequence of steps required to search and compare flights.

• User Context versus Domain Standards (Semantic versus Taxonomic): Semantic memory tracks user-specific details, such as a traveler's frequent flyer tier. Taxonomic memory defines the standard terminology shared across the entire project, such as what qualifying criteria define an elite tier or a red-eye flight.

Combining Memory Types

Memory types are complementary rather than mutually exclusive. A single agent often queries multiple memory types within the same workflow. For example, a travel booking agent might reference:

• Semantic memory to recall a traveler's home airport, seating preference, and frequent flyer number.

• Episodic memory to review discussions, booked itineraries, and canceled flights from past trips.

• Procedural memory to execute the step-by-step workflow for comparing flight options or rebooking a canceled connection.

• Taxonomic memory to interpret airline industry terminology, such as open-jaw routing, layover, or red-eye.

If your data doesn't fit any of the four built-in types, you can declare custom memory types instead. To learn how, see Declare Custom Memory Types in the Add Memory to Your Agent guide.