letta-nightly 0.11.6.dev20250903104037__py3-none-any.whl → 0.11.7.dev20250904045700__py3-none-any.whl

letta/prompts/prompt_generator.py

@@ -9,7 +9,6 @@ from letta.schemas.memory import Memory
 
 
 class PromptGenerator:
-
     # TODO: This code is kind of wonky and deserves a rewrite
     @trace_method
     @staticmethod
@@ -18,6 +17,7 @@ class PromptGenerator:
         timezone: str,
         previous_message_count: int = 0,
         archival_memory_size: Optional[int] = 0,
+        archive_tags: Optional[List[str]] = None,
     ) -> str:
         """
         Generate a memory metadata block for the agent's system prompt.
@@ -32,6 +32,7 @@ class PromptGenerator:
             timezone: The timezone to use for formatting timestamps (e.g., 'America/Los_Angeles')
             previous_message_count: Number of messages in recall memory (conversation history)
             archival_memory_size: Number of items in archival memory (long-term storage)
+            archive_tags: List of unique tags available in archival memory
 
         Returns:
             A formatted string containing the memory metadata block with XML-style tags
@@ -42,6 +43,7 @@ class PromptGenerator:
             - Memory blocks were last modified: 2024-01-15 09:00 AM PST
             - 42 previous messages between you and the user are stored in recall memory (use tools to access them)
             - 156 total memories you created are stored in archival memory (use tools to access them)
+            - Available archival memory tags: project_x, meeting_notes, research, ideas
             </memory_metadata>
         """
         # Put the timestamp in the local timezone (mimicking get_local_time())
@@ -50,7 +52,7 @@ class PromptGenerator:
         # Create a metadata block of info so the agent knows about the metadata of out-of-context memories
         metadata_lines = [
             "<memory_metadata>",
-            f"- The current time is: {get_local_time_fast(timezone)}",
+            f"- The current system date is: {get_local_time_fast(timezone)}",
             f"- Memory blocks were last modified: {timestamp_str}",
             f"- {previous_message_count} previous messages between you and the user are stored in recall memory (use tools to access them)",
         ]
@@ -61,6 +63,10 @@ class PromptGenerator:
                 f"- {archival_memory_size} total memories you created are stored in archival memory (use tools to access them)"
             )
 
+        # Include archive tags if available
+        if archive_tags:
+            metadata_lines.append(f"- Available archival memory tags: {', '.join(archive_tags)}")
+
         metadata_lines.append("</memory_metadata>")
         memory_metadata_block = "\n".join(metadata_lines)
         return memory_metadata_block
@@ -91,6 +97,7 @@ class PromptGenerator:
         template_format: Literal["f-string", "mustache", "jinja2"] = "f-string",
         previous_message_count: int = 0,
         archival_memory_size: int = 0,
+        archive_tags: Optional[List[str]] = None,
     ) -> str:
         """Prepare the final/full system message that will be fed into the LLM API
 
@@ -115,6 +122,7 @@ class PromptGenerator:
                 previous_message_count=previous_message_count,
                 archival_memory_size=archival_memory_size,
                 timezone=timezone,
+                archive_tags=archive_tags,
             )
 
             full_memory_string = memory_with_sources + "\n\n" + memory_metadata_string

letta/schemas/agent.py

@@ -91,6 +91,8 @@ class AgentState(OrmMetadataBase, validate_assignment=True):
     project_id: Optional[str] = Field(None, description="The id of the project the agent belongs to.")
     template_id: Optional[str] = Field(None, description="The id of the template the agent belongs to.")
     base_template_id: Optional[str] = Field(None, description="The base template id of the agent.")
+    deployment_id: Optional[str] = Field(None, description="The id of the deployment.")
+    entity_id: Optional[str] = Field(None, description="The id of the entity within the template.")
     identity_ids: List[str] = Field([], description="The ids of the identities associated with this agent.")
 
     # An advanced configuration that makes it so this agent does not remember any previous messages
@@ -304,6 +306,15 @@ class CreateAgent(BaseModel, validate_assignment=True):  #
         return self
 
 
+class InternalTemplateAgentCreate(CreateAgent):
+    """Used for Letta Cloud"""
+
+    base_template_id: str = Field(..., description="The id of the base template.")
+    template_id: str = Field(..., description="The id of the template.")
+    deployment_id: str = Field(..., description="The id of the deployment.")
+    entity_id: str = Field(..., description="The id of the entity within the template.")
+
+
 class UpdateAgent(BaseModel):
     name: Optional[str] = Field(None, description="The name of the agent.")
     tool_ids: Optional[List[str]] = Field(None, description="The ids of the tools used by the agent.")

letta/schemas/archive.py

@@ -3,6 +3,7 @@ from typing import Dict, Optional
 
 from pydantic import Field
 
+from letta.schemas.enums import VectorDBProvider
 from letta.schemas.letta_base import OrmMetadataBase
 
 
@@ -12,6 +13,9 @@ class ArchiveBase(OrmMetadataBase):
     name: str = Field(..., description="The name of the archive")
     description: Optional[str] = Field(None, description="A description of the archive")
     organization_id: str = Field(..., description="The organization this archive belongs to")
+    vector_db_provider: VectorDBProvider = Field(
+        default=VectorDBProvider.NATIVE, description="The vector database provider used for this archive's passages"
+    )
     metadata: Optional[Dict] = Field(default_factory=dict, validation_alias="metadata_", description="Additional metadata")
 
 

letta/schemas/block.py

@@ -23,6 +23,10 @@ class BaseBlock(LettaBase, validate_assignment=True):
     # template data (optional)
     template_name: Optional[str] = Field(None, description="Name of the block if it is a template.", alias="name")
     is_template: bool = Field(False, description="Whether the block is a template (e.g. saved human/persona options).")
+    template_id: Optional[str] = Field(None, description="The id of the template.", alias="name")
+    base_template_id: Optional[str] = Field(None, description="The base template id of the block.")
+    deployment_id: Optional[str] = Field(None, description="The id of the deployment.")
+    entity_id: Optional[str] = Field(None, description="The id of the entity within the template.")
     preserve_on_migration: Optional[bool] = Field(False, description="Preserve the block on template migration.")
 
     # context window label
@@ -168,3 +172,12 @@ class CreatePersonaBlockTemplate(CreatePersona):
 
     is_template: bool = True
     label: str = "persona"
+
+
+class InternalTemplateBlockCreate(CreateBlock):
+    """Used for Letta Cloud"""
+
+    base_template_id: str = Field(..., description="The id of the base template.")
+    template_id: str = Field(..., description="The id of the template.")
+    deployment_id: str = Field(..., description="The id of the deployment.")
+    entity_id: str = Field(..., description="The id of the entity within the template.")

letta/schemas/embedding_config.py

@@ -43,7 +43,6 @@ class EmbeddingConfig(BaseModel):
 
     @classmethod
     def default_config(cls, model_name: Optional[str] = None, provider: Optional[str] = None):
-
         if model_name == "text-embedding-ada-002" and provider == "openai":
             return cls(
                 embedding_model="text-embedding-ada-002",

letta/schemas/enums.py

@@ -3,21 +3,22 @@ from enum import Enum, StrEnum
 
 class ProviderType(str, Enum):
     anthropic = "anthropic"
+    azure = "azure"
+    bedrock = "bedrock"
+    cerebras = "cerebras"
+    deepseek = "deepseek"
     google_ai = "google_ai"
     google_vertex = "google_vertex"
-    openai = "openai"
+    groq = "groq"
+    hugging_face = "hugging-face"
     letta = "letta"
-    deepseek = "deepseek"
-    cerebras = "cerebras"
     lmstudio_openai = "lmstudio_openai"
-    xai = "xai"
     mistral = "mistral"
     ollama = "ollama"
-    groq = "groq"
+    openai = "openai"
     together = "together"
-    azure = "azure"
     vllm = "vllm"
-    bedrock = "bedrock"
+    xai = "xai"
 
 
 class ProviderCategory(str, Enum):
@@ -31,6 +32,7 @@ class MessageRole(str, Enum):
     tool = "tool"
     function = "function"
     system = "system"
+    approval = "approval"
 
 
 class OptionState(str, Enum):
@@ -93,6 +95,7 @@ class ToolRuleType(str, Enum):
     max_count_per_step = "max_count_per_step"
     parent_last_tool = "parent_last_tool"
     required_before_exit = "required_before_exit"  # tool must be called before loop can exit
+    requires_approval = "requires_approval"
 
 
 class FileProcessingStatus(str, Enum):
@@ -170,3 +173,17 @@ class StepStatus(str, Enum):
     SUCCESS = "success"
     FAILED = "failed"
     CANCELLED = "cancelled"
+
+
+class VectorDBProvider(str, Enum):
+    """Supported vector database providers for archival memory"""
+
+    NATIVE = "native"
+    TPUF = "tpuf"
+
+
+class TagMatchMode(str, Enum):
+    """Tag matching behavior for filtering"""
+
+    ANY = "any"
+    ALL = "all"

letta/schemas/group.py

@@ -29,6 +29,10 @@ class Group(GroupBase):
     agent_ids: List[str] = Field(..., description="")
     description: str = Field(..., description="")
     project_id: Optional[str] = Field(None, description="The associated project id.")
+    # Template fields
+    template_id: Optional[str] = Field(None, description="The id of the template.")
+    base_template_id: Optional[str] = Field(None, description="The base template id.")
+    deployment_id: Optional[str] = Field(None, description="The id of the deployment.")
     shared_block_ids: List[str] = Field([], description="")
     # Pattern fields
     manager_agent_id: Optional[str] = Field(None, description="")
@@ -168,6 +172,14 @@ class GroupCreate(BaseModel):
     shared_block_ids: List[str] = Field([], description="")
 
 
+class InternalTemplateGroupCreate(GroupCreate):
+    """Used for Letta Cloud"""
+
+    base_template_id: str = Field(..., description="The id of the base template.")
+    template_id: str = Field(..., description="The id of the template.")
+    deployment_id: str = Field(..., description="The id of the deployment.")
+
+
 class GroupUpdate(BaseModel):
     agent_ids: Optional[List[str]] = Field(None, description="")
     description: Optional[str] = Field(None, description="")

letta/schemas/letta_message.py

@@ -25,6 +25,8 @@ class MessageType(str, Enum):
     hidden_reasoning_message = "hidden_reasoning_message"
     tool_call_message = "tool_call_message"
     tool_return_message = "tool_return_message"
+    approval_request_message = "approval_request_message"
+    approval_response_message = "approval_response_message"
 
 
 class LettaMessage(BaseModel):
@@ -249,6 +251,44 @@ class ToolReturnMessage(LettaMessage):
     stderr: Optional[List[str]] = None
 
 
+class ApprovalRequestMessage(LettaMessage):
+    """
+    A message representing a request for approval to call a tool (generated by the LLM to trigger tool execution).
+
+    Args:
+        id (str): The ID of the message
+        date (datetime): The date the message was created in ISO format
+        name (Optional[str]): The name of the sender of the message
+        tool_call (ToolCall): The tool call
+    """
+
+    message_type: Literal[MessageType.approval_request_message] = Field(
+        default=MessageType.approval_request_message, description="The type of the message."
+    )
+    tool_call: ToolCall = Field(..., description="The tool call that has been requested by the llm to run")
+
+
+class ApprovalResponseMessage(LettaMessage):
+    """
+    A message representing a response form the user indicating whether a tool has been approved to run.
+
+    Args:
+        id (str): The ID of the message
+        date (datetime): The date the message was created in ISO format
+        name (Optional[str]): The name of the sender of the message
+        approve: (bool) Whether the tool has been approved
+        approval_request_id: The ID of the approval request
+        reason: (Optional[str]) An optional explanation for the provided approval status
+    """
+
+    message_type: Literal[MessageType.approval_response_message] = Field(
+        default=MessageType.approval_response_message, description="The type of the message."
+    )
+    approve: bool = Field(..., description="Whether the tool has been approved")
+    approval_request_id: str = Field(..., description="The message ID of the approval request")
+    reason: Optional[str] = Field(None, description="An optional explanation for the provided approval status")
+
+
 class AssistantMessage(LettaMessage):
     """
     A message sent by the LLM in response to user input. Used in the LLM context.
@@ -272,7 +312,17 @@ class AssistantMessage(LettaMessage):
 
 # NOTE: use Pydantic's discriminated unions feature: https://docs.pydantic.dev/latest/concepts/unions/#discriminated-unions
 LettaMessageUnion = Annotated[
-    Union[SystemMessage, UserMessage, ReasoningMessage, HiddenReasoningMessage, ToolCallMessage, ToolReturnMessage, AssistantMessage],
+    Union[
+        SystemMessage,
+        UserMessage,
+        ReasoningMessage,
+        HiddenReasoningMessage,
+        ToolCallMessage,
+        ToolReturnMessage,
+        AssistantMessage,
+        ApprovalRequestMessage,
+        ApprovalResponseMessage,
+    ],
     Field(discriminator="message_type"),
 ]
 
@@ -287,6 +337,8 @@ def create_letta_message_union_schema():
             {"$ref": "#/components/schemas/ToolCallMessage"},
             {"$ref": "#/components/schemas/ToolReturnMessage"},
             {"$ref": "#/components/schemas/AssistantMessage"},
+            {"$ref": "#/components/schemas/ApprovalRequestMessage"},
+            {"$ref": "#/components/schemas/ApprovalResponseMessage"},
         ],
         "discriminator": {
             "propertyName": "message_type",
@@ -298,6 +350,8 @@ def create_letta_message_union_schema():
                 "tool_call_message": "#/components/schemas/ToolCallMessage",
                 "tool_return_message": "#/components/schemas/ToolReturnMessage",
                 "assistant_message": "#/components/schemas/AssistantMessage",
+                "approval_request_message": "#/components/schemas/ApprovalRequestMessage",
+                "approval_response_message": "#/components/schemas/ApprovalResponseMessage",
             },
         },
     }

letta/schemas/letta_message_content.py

@@ -17,6 +17,14 @@ class MessageContentType(str, Enum):
 class MessageContent(BaseModel):
     type: MessageContentType = Field(..., description="The type of the message.")
 
+    def to_text(self) -> Optional[str]:
+        """Extract text representation from this content type.
+
+        Returns:
+            Text representation of the content, None if no text available.
+        """
+        return None
+
 
 # -------------------------------
 # Text Content
@@ -27,6 +35,10 @@ class TextContent(MessageContent):
     type: Literal[MessageContentType.text] = Field(default=MessageContentType.text, description="The type of the message.")
     text: str = Field(..., description="The text content of the message.")
 
+    def to_text(self) -> str:
+        """Return the text content."""
+        return self.text
+
 
 # -------------------------------
 # Image Content
@@ -172,6 +184,13 @@ class ToolCallContent(MessageContent):
         ..., description="The parameters being passed to the tool, structured as a dictionary of parameter names to values."
     )
 
+    def to_text(self) -> str:
+        """Return a text representation of the tool call."""
+        import json
+
+        input_str = json.dumps(self.input, indent=2)
+        return f"Tool call: {self.name}({input_str})"
+
 
 class ToolReturnContent(MessageContent):
     type: Literal[MessageContentType.tool_return] = Field(
@@ -181,6 +200,11 @@ class ToolReturnContent(MessageContent):
     content: str = Field(..., description="The content returned by the tool execution.")
     is_error: bool = Field(..., description="Indicates whether the tool execution resulted in an error.")
 
+    def to_text(self) -> str:
+        """Return the tool return content."""
+        prefix = "Tool error: " if self.is_error else "Tool result: "
+        return f"{prefix}{self.content}"
+
 
 class ReasoningContent(MessageContent):
     type: Literal[MessageContentType.reasoning] = Field(
@@ -190,6 +214,10 @@ class ReasoningContent(MessageContent):
     reasoning: str = Field(..., description="The intermediate reasoning or thought process content.")
     signature: Optional[str] = Field(default=None, description="A unique identifier for this reasoning step.")
 
+    def to_text(self) -> str:
+        """Return the reasoning content."""
+        return self.reasoning
+
 
 class RedactedReasoningContent(MessageContent):
     type: Literal[MessageContentType.redacted_reasoning] = Field(

letta/schemas/letta_request.py

@@ -1,14 +1,14 @@
 from typing import List, Optional
 
-from pydantic import BaseModel, Field, HttpUrl
+from pydantic import BaseModel, Field, HttpUrl, field_validator
 
 from letta.constants import DEFAULT_MAX_STEPS, DEFAULT_MESSAGE_TOOL, DEFAULT_MESSAGE_TOOL_KWARG
 from letta.schemas.letta_message import MessageType
-from letta.schemas.message import MessageCreate
+from letta.schemas.message import MessageCreateUnion
 
 
 class LettaRequest(BaseModel):
-    messages: List[MessageCreate] = Field(..., description="The messages to be sent to the agent.")
+    messages: List[MessageCreateUnion] = Field(..., description="The messages to be sent to the agent.")
     max_steps: int = Field(
         default=DEFAULT_MAX_STEPS,
         description="Maximum number of steps the agent should take to process the request.",
@@ -36,11 +36,28 @@ class LettaRequest(BaseModel):
         description="If set to True, enables reasoning before responses or tool calls from the agent.",
     )
 
+    @field_validator("messages", mode="before")
+    @classmethod
+    def add_default_type_to_messages(cls, v):
+        """Handle union without discriminator - default to 'message' type if not specified"""
+        if isinstance(v, list):
+            for item in v:
+                if isinstance(item, dict):
+                    # If type is not present, determine based on fields
+                    if "type" not in item:
+                        # If it has approval-specific fields, it's an approval
+                        if "approval_request_id" in item or "approve" in item:
+                            item["type"] = "approval"
+                        else:
+                            # Default to message
+                            item["type"] = "message"
+        return v
+
 
 class LettaStreamingRequest(LettaRequest):
     stream_tokens: bool = Field(
         default=False,
-        description="Flag to determine if individual tokens should be streamed. Set to True for token streaming (requires stream_steps = True).",
+        description="Flag to determine if individual tokens should be streamed, rather than streaming per step.",
     )
     include_pings: bool = Field(
         default=False,

letta/schemas/letta_stop_reason.py

@@ -9,11 +9,13 @@ from letta.schemas.enums import JobStatus
 class StopReasonType(str, Enum):
     end_turn = "end_turn"
     error = "error"
+    invalid_llm_response = "invalid_llm_response"
     invalid_tool_call = "invalid_tool_call"
     max_steps = "max_steps"
     no_tool_call = "no_tool_call"
     tool_rule = "tool_rule"
     cancelled = "cancelled"
+    requires_approval = "requires_approval"
 
     @property
     def run_status(self) -> JobStatus:
@@ -21,9 +23,15 @@ class StopReasonType(str, Enum):
             StopReasonType.end_turn,
             StopReasonType.max_steps,
             StopReasonType.tool_rule,
+            StopReasonType.requires_approval,
         ):
             return JobStatus.completed
-        elif self in (StopReasonType.error, StopReasonType.invalid_tool_call, StopReasonType.no_tool_call):
+        elif self in (
+            StopReasonType.error,
+            StopReasonType.invalid_tool_call,
+            StopReasonType.no_tool_call,
+            StopReasonType.invalid_llm_response,
+        ):
             return JobStatus.failed
         elif self == StopReasonType.cancelled:
             return JobStatus.cancelled

letta/schemas/llm_config.py

@@ -51,7 +51,7 @@ class LLMConfig(BaseModel):
         description="The temperature to use when generating text with the model. A higher temperature will result in more random text.",
     )
     max_tokens: Optional[int] = Field(
-        4096,
+        None,
         description="The maximum number of tokens to generate. If not set, the model will use its default value.",
     )
     enable_reasoner: bool = Field(
@@ -71,9 +71,10 @@ class LLMConfig(BaseModel):
     )
     compatibility_type: Optional[Literal["gguf", "mlx"]] = Field(None, description="The framework compatibility type for the model.")
     verbosity: Optional[Literal["low", "medium", "high"]] = Field(
-        "medium",
+        None,
         description="Soft control for how verbose model output should be, used for GPT-5 models.",
     )
+    tier: Optional[str] = Field(None, description="The cost tier for the model (cloud only).")
 
     # FIXME hack to silence pydantic protected namespace warning
     model_config = ConfigDict(protected_namespaces=())
@@ -205,6 +206,7 @@ class LLMConfig(BaseModel):
                 model_endpoint="https://api.openai.com/v1",
                 model_wrapper=None,
                 context_window=128000,
+                reasoning_effort="minimal",
                 verbosity="medium",
                 max_tokens=16384,
             )
@@ -227,9 +229,9 @@ class LLMConfig(BaseModel):
 
     @classmethod
     def is_openai_reasoning_model(cls, config: "LLMConfig") -> bool:
-        return config.model_endpoint_type == "openai" and (
-            config.model.startswith("o1") or config.model.startswith("o3") or config.model.startswith("o4")
-        )
+        from letta.llm_api.openai_client import is_openai_reasoning_model
+
+        return config.model_endpoint_type == "openai" and is_openai_reasoning_model(config.model)
 
     @classmethod
     def is_anthropic_reasoning_model(cls, config: "LLMConfig") -> bool:
@@ -260,11 +262,18 @@ class LLMConfig(BaseModel):
     def apply_reasoning_setting_to_config(cls, config: "LLMConfig", reasoning: bool):
         if not reasoning:
             if cls.is_openai_reasoning_model(config):
-                logger.warning("Reasoning cannot be disabled for OpenAI o1/o3 models")
+                logger.warning("Reasoning cannot be disabled for OpenAI o1/o3/gpt-5 models")
                 config.put_inner_thoughts_in_kwargs = False
                 config.enable_reasoner = True
                 if config.reasoning_effort is None:
-                    config.reasoning_effort = "medium"
+                    # GPT-5 models default to minimal, others to medium
+                    if config.model.startswith("gpt-5"):
+                        config.reasoning_effort = "minimal"
+                    else:
+                        config.reasoning_effort = "medium"
+                # Set verbosity for GPT-5 models
+                if config.model.startswith("gpt-5") and config.verbosity is None:
+                    config.verbosity = "medium"
             elif config.model.startswith("gemini-2.5-pro"):
                 logger.warning("Reasoning cannot be disabled for Gemini 2.5 Pro model")
                 # Handle as non-reasoner until we support summary
@@ -290,7 +299,14 @@ class LLMConfig(BaseModel):
             elif cls.is_openai_reasoning_model(config):
                 config.put_inner_thoughts_in_kwargs = False
                 if config.reasoning_effort is None:
-                    config.reasoning_effort = "medium"
+                    # GPT-5 models default to minimal, others to medium
+                    if config.model.startswith("gpt-5"):
+                        config.reasoning_effort = "minimal"
+                    else:
+                        config.reasoning_effort = "medium"
+                # Set verbosity for GPT-5 models
+                if config.model.startswith("gpt-5") and config.verbosity is None:
+                    config.verbosity = "medium"
             else:
                 config.put_inner_thoughts_in_kwargs = True
 

letta/schemas/mcp.py

@@ -84,7 +84,6 @@ class MCPServer(BaseMCPServer):
 class UpdateSSEMCPServer(LettaBase):
     """Update an SSE MCP server"""
 
-    server_name: Optional[str] = Field(None, description="The name of the server")
     server_url: Optional[str] = Field(None, description="The URL of the server (MCP SSE client will connect to this URL)")
     token: Optional[str] = Field(None, description="The access token or API key for the MCP server (used for SSE authentication)")
     custom_headers: Optional[Dict[str, str]] = Field(None, description="Custom authentication headers as key-value pairs")
@@ -93,7 +92,6 @@ class UpdateSSEMCPServer(LettaBase):
 class UpdateStdioMCPServer(LettaBase):
     """Update a Stdio MCP server"""
 
-    server_name: Optional[str] = Field(None, description="The name of the server")
     stdio_config: Optional[StdioServerConfig] = Field(
         None, description="The configuration for the server (MCP 'local' client will run this command)"
     )
@@ -102,7 +100,6 @@ class UpdateStdioMCPServer(LettaBase):
 class UpdateStreamableHTTPMCPServer(LettaBase):
     """Update a Streamable HTTP MCP server"""
 
-    server_name: Optional[str] = Field(None, description="The name of the server")
     server_url: Optional[str] = Field(None, description="The URL path for the streamable HTTP server (e.g., 'example/mcp')")
     auth_header: Optional[str] = Field(None, description="The name of the authentication header (e.g., 'Authorization')")
     auth_token: Optional[str] = Field(None, description="The authentication token or API key value")

letta/schemas/memory.py

@@ -1,5 +1,6 @@
 import asyncio
 import logging
+from datetime import datetime
 from typing import TYPE_CHECKING, List, Optional
 
 from jinja2 import Template, TemplateSyntaxError
@@ -325,3 +326,16 @@ class RecallMemorySummary(BaseModel):
 
 class CreateArchivalMemory(BaseModel):
     text: str = Field(..., description="Text to write to archival memory.")
+    tags: Optional[List[str]] = Field(None, description="Optional list of tags to attach to the memory.")
+    created_at: Optional[datetime] = Field(None, description="Optional timestamp for the memory (defaults to current UTC time).")
+
+
+class ArchivalMemorySearchResult(BaseModel):
+    timestamp: str = Field(..., description="Timestamp of when the memory was created, formatted in agent's timezone")
+    content: str = Field(..., description="Text content of the archival memory passage")
+    tags: List[str] = Field(default_factory=list, description="List of tags associated with this memory")
+
+
+class ArchivalMemorySearchResponse(BaseModel):
+    results: List[ArchivalMemorySearchResult] = Field(..., description="List of search results matching the query")
+    count: int = Field(..., description="Total number of results returned")