autogen_core.memory#

class ListMemory(name: str | None = None)[source]#

Bases: Memory

Simple chronological list-based memory implementation.

This memory implementation stores contents in a list and retrieves them in chronological order. It has an update_context method that updates model contexts by appending all stored memories.

The memory content can be directly accessed and modified through the content property, allowing external applications to manage memory contents directly.

Example

import asyncio
from autogen_core.memory import ListMemory, MemoryContent
from autogen_core.model_context import BufferedChatCompletionContext


async def main() -> None:
    # Initialize memory
    memory = ListMemory(name="chat_history")

    # Add memory content
    content = MemoryContent(content="User prefers formal language", mime_type="text/plain")
    await memory.add(content)

    # Directly modify memory contents
    memory.content = [MemoryContent(content="New preference", mime_type="text/plain")]

    # Create a model context
    model_context = BufferedChatCompletionContext(buffer_size=10)

    # Update a model context with memory
    await memory.update_context(model_context)

    # See the updated model context
    print(await model_context.get_messages())


asyncio.run(main())

Parameters:: name – Optional identifier for this memory instance

async add(content: MemoryContent, cancellation_token: CancellationToken | None = None) → None[source]#

Add new content to memory.

Parameters:

content – Memory content to store
cancellation_token – Optional token to cancel operation

async clear() → None[source]#: Clear all memory content.

async close() → None[source]#: Cleanup resources if needed.

property content: List[MemoryContent]#

Get the current memory contents.

Returns:: List[MemoryContent] – List of stored memory contents

property name: str#

Get the memory instance identifier.

Returns:: str – Memory instance name

async query(query: str | MemoryContent = '', cancellation_token: CancellationToken | None = None, **kwargs: Any) → MemoryQueryResult[source]#

Return all memories without any filtering.

Parameters:

query – Ignored in this implementation
cancellation_token – Optional token to cancel operation
**kwargs – Additional parameters (ignored)

Returns:

MemoryQueryResult containing all stored memories

async update_context(model_context: ChatCompletionContext) → UpdateContextResult[source]#

Update the model context by appending memory content.

This method mutates the provided model_context by adding all memories as a SystemMessage.

Parameters:: model_context – The context to update. Will be mutated if memories exist.
Returns:: UpdateContextResult containing the memories that were added to the context

class Memory[source]#

Bases: ABC

Protocol defining the interface for memory implementations.

A memory is the storage for data that can be used to enrich or modify the model context.

A memory implementation can use any storage mechanism, such as a list, a database, or a file system. It can also use any retrieval mechanism, such as vector search or text search. It is up to the implementation to decide how to store and retrieve data.

It is also a memory implementation’s responsibility to update the model context with relevant memory content based on the current model context and querying the memory store.

See ListMemory for an example implementation.

abstract async add(content: MemoryContent, cancellation_token: CancellationToken | None = None) → None[source]#

Add a new content to memory.

Parameters:

content – The memory content to add
cancellation_token – Optional token to cancel operation

abstract async clear() → None[source]#: Clear all entries from memory.

abstract async close() → None[source]#: Clean up any resources used by the memory implementation.

abstract async query(query: str | MemoryContent, cancellation_token: CancellationToken | None = None, **kwargs: Any) → MemoryQueryResult[source]#

Query the memory store and return relevant entries.

Parameters:

query – Query content item
cancellation_token – Optional token to cancel operation
**kwargs – Additional implementation-specific parameters

Returns:

MemoryQueryResult containing memory entries with relevance scores

abstract async update_context(model_context: ChatCompletionContext) → UpdateContextResult[source]#

Update the provided model context using relevant memory content.

Parameters:: model_context – The context to update.
Returns:: UpdateContextResult containing relevant memories

pydantic model MemoryContent[source]#

Bases: BaseModel

A memory content item.

Show JSON schema

{
   "title": "MemoryContent",
   "description": "A memory content item.",
   "type": "object",
   "properties": {
      "content": {
         "anyOf": [
            {
               "type": "string"
            },
            {
               "format": "binary",
               "type": "string"
            },
            {
               "type": "object"
            },
            {}
         ],
         "title": "Content"
      },
      "mime_type": {
         "anyOf": [
            {
               "$ref": "#/$defs/MemoryMimeType"
            },
            {
               "type": "string"
            }
         ],
         "title": "Mime Type"
      },
      "metadata": {
         "anyOf": [
            {
               "type": "object"
            },
            {
               "type": "null"
            }
         ],
         "default": null,
         "title": "Metadata"
      }
   },
   "$defs": {
      "MemoryMimeType": {
         "description": "Supported MIME types for memory content.",
         "enum": [
            "text/plain",
            "application/json",
            "text/markdown",
            "image/*",
            "application/octet-stream"
         ],
         "title": "MemoryMimeType",
         "type": "string"
      }
   },
   "required": [
      "content",
      "mime_type"
   ]
}

Fields:

content (str | bytes | Dict[str, Any] | autogen_core._image.Image)
metadata (Dict[str, Any] | None)
mime_type (autogen_core.memory._base_memory.MemoryMimeType | str)

field content: str | bytes | Dict[str, Any] | Image [Required]#: The content of the memory item. It can be a string, bytes, dict, or Image.

field metadata: Dict[str, Any] | None = None#: Metadata associated with the memory item.

field mime_type: MemoryMimeType | str [Required]#: The MIME type of the memory content.

class MemoryMimeType(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)[source]#

Bases: Enum

Supported MIME types for memory content.

BINARY = 'application/octet-stream'#

IMAGE = 'image/*'#

JSON = 'application/json'#

MARKDOWN = 'text/markdown'#

TEXT = 'text/plain'#

pydantic model MemoryQueryResult[source]#

Bases: BaseModel

Result of a memory query() operation.

Show JSON schema

{
   "title": "MemoryQueryResult",
   "description": "Result of a memory :meth:`~autogen_core.memory.Memory.query` operation.",
   "type": "object",
   "properties": {
      "results": {
         "items": {
            "$ref": "#/$defs/MemoryContent"
         },
         "title": "Results",
         "type": "array"
      }
   },
   "$defs": {
      "MemoryContent": {
         "description": "A memory content item.",
         "properties": {
            "content": {
               "anyOf": [
                  {
                     "type": "string"
                  },
                  {
                     "format": "binary",
                     "type": "string"
                  },
                  {
                     "type": "object"
                  },
                  {}
               ],
               "title": "Content"
            },
            "mime_type": {
               "anyOf": [
                  {
                     "$ref": "#/$defs/MemoryMimeType"
                  },
                  {
                     "type": "string"
                  }
               ],
               "title": "Mime Type"
            },
            "metadata": {
               "anyOf": [
                  {
                     "type": "object"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "title": "Metadata"
            }
         },
         "required": [
            "content",
            "mime_type"
         ],
         "title": "MemoryContent",
         "type": "object"
      },
      "MemoryMimeType": {
         "description": "Supported MIME types for memory content.",
         "enum": [
            "text/plain",
            "application/json",
            "text/markdown",
            "image/*",
            "application/octet-stream"
         ],
         "title": "MemoryMimeType",
         "type": "string"
      }
   },
   "required": [
      "results"
   ]
}

Fields:

results (List[autogen_core.memory._base_memory.MemoryContent])

field results: List[MemoryContent] [Required]#

pydantic model UpdateContextResult[source]#

Bases: BaseModel

Result of a memory update_context() operation.

Show JSON schema

{
   "title": "UpdateContextResult",
   "description": "Result of a memory :meth:`~autogen_core.memory.Memory.update_context` operation.",
   "type": "object",
   "properties": {
      "memories": {
         "$ref": "#/$defs/MemoryQueryResult"
      }
   },
   "$defs": {
      "MemoryContent": {
         "description": "A memory content item.",
         "properties": {
            "content": {
               "anyOf": [
                  {
                     "type": "string"
                  },
                  {
                     "format": "binary",
                     "type": "string"
                  },
                  {
                     "type": "object"
                  },
                  {}
               ],
               "title": "Content"
            },
            "mime_type": {
               "anyOf": [
                  {
                     "$ref": "#/$defs/MemoryMimeType"
                  },
                  {
                     "type": "string"
                  }
               ],
               "title": "Mime Type"
            },
            "metadata": {
               "anyOf": [
                  {
                     "type": "object"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "title": "Metadata"
            }
         },
         "required": [
            "content",
            "mime_type"
         ],
         "title": "MemoryContent",
         "type": "object"
      },
      "MemoryMimeType": {
         "description": "Supported MIME types for memory content.",
         "enum": [
            "text/plain",
            "application/json",
            "text/markdown",
            "image/*",
            "application/octet-stream"
         ],
         "title": "MemoryMimeType",
         "type": "string"
      },
      "MemoryQueryResult": {
         "description": "Result of a memory :meth:`~autogen_core.memory.Memory.query` operation.",
         "properties": {
            "results": {
               "items": {
                  "$ref": "#/$defs/MemoryContent"
               },
               "title": "Results",
               "type": "array"
            }
         },
         "required": [
            "results"
         ],
         "title": "MemoryQueryResult",
         "type": "object"
      }
   },
   "required": [
      "memories"
   ]
}

Fields:

memories (autogen_core.memory._base_memory.MemoryQueryResult)

field memories: MemoryQueryResult [Required]#