agentscope.memory

The memory module.

class MemoryBase[source]

Bases: StateModule

The base class for memory in agentscope.

abstract async add(*args, **kwargs)[source]

Add items to the memory.

Parameters:

  • args (Any)

  • kwargs (Any)

Return type:

None

abstract async delete(*args, **kwargs)[source]

Delete items from the memory.

Parameters:

  • args (Any)

  • kwargs (Any)

Return type:

None

abstract async retrieve(*args, **kwargs)[source]

Retrieve items from the memory.

Parameters:

  • args (Any)

  • kwargs (Any)

Return type:

None

abstract async size()[source]

Get the size of the memory.

Return type:

int

abstract async clear()[source]

Clear the memory content.

Return type:

None

abstract async get_memory(*args, **kwargs)[source]

Get the memory content.

Parameters:

  • args (Any)

  • kwargs (Any)

Return type:

list[Msg]

abstract state_dict()[source]

Get the state dictionary of the memory.

Return type:

dict

abstract load_state_dict(state_dict, strict=True)[source]

Load the state dictionary of the memory.

Parameters:

  • state_dict (dict)

  • strict (bool)

Return type:

None

class InMemoryMemory[source]

Bases: MemoryBase

The in-memory memory class for storing messages.

__init__()[source]

Initialize the in-memory memory object.

Return type:

None

state_dict()[source]

Convert the current memory into JSON data format.

Return type:

dict

load_state_dict(state_dict, strict=True)[source]

Load the memory from JSON data.

Parameters:

  • state_dict (dict) – The state dictionary to load, which should have a “content” field.

  • strict (bool, defaults to True) – If True, raises an error if any key in the module is not found in the state_dict. If False, skips missing keys.

Return type:

None

async size()[source]

The size of the memory.

Return type:

int

async retrieve(*args, **kwargs)[source]

Retrieve items from the memory.

Parameters:

  • args (Any)

  • kwargs (Any)

Return type:

None

async delete(index)[source]

Delete the specified item by index(es).

Parameters:

index (Union[Iterable, int]) – The index to delete.

Return type:

None

async add(memories, allow_duplicates=False)[source]

Add message into the memory.

Parameters:

  • memories (Union[list[Msg], Msg, None]) – The message to add.

  • allow_duplicates (bool, defaults to False) – If allow adding duplicate messages (with the same id) into the memory.

Return type:

None

async get_memory()[source]

Get the memory content.

Return type:

list[Msg]

async clear()[source]

Clear the memory content.

Return type:

None

class LongTermMemoryBase[source]

Bases: StateModule

The long-term memory base class, which should be a time-series memory management system.

The record_to_memory and retrieve_from_memory methods are two tool functions for agent to manage the long-term memory voluntarily. You can choose not to implement these two functions.

The record and retrieve methods are for developers to use. For example, retrieving/recording memory at the beginning of each reply, and adding the retrieved memory to the system prompt.

async record(msgs, **kwargs)[source]

A developer-designed method to record information from the given input message(s) to the long-term memory.

Parameters:

  • msgs (list[Msg | None])

  • kwargs (Any)

Return type:

None

async retrieve(msg, **kwargs)[source]

A developer-designed method to retrieve information from the long-term memory based on the given input message(s). The retrieved information will be added to the system prompt of the agent.

Parameters:

  • msg (Msg | list[Msg] | None)

  • kwargs (Any)

Return type:

str

async record_to_memory(thinking, content, **kwargs)[source]

Use this function to record important information that you may need later. The target content should be specific and concise, e.g. who, when, where, do what, why, how, etc.

Parameters:

  • thinking (str) – Your thinking and reasoning about what to record

  • content (list[str]) – The content to remember, which is a list of strings.

  • kwargs (Any)

Return type:

ToolResponse

async retrieve_from_memory(keywords, **kwargs)[source]

Retrieve the memory based on the given keywords.

Parameters:

  • keywords (list[str]) – The keywords to search for in the memory, which should be specific and concise, e.g. the person’s name, the date, the location, etc.

  • kwargs (Any)

Returns:

A list of messages that match the keywords.

Return type:

list[Msg]

class Mem0LongTermMemory[source]

Bases: LongTermMemoryBase

A class that implements the LongTermMemoryBase interface using mem0.

__init__(agent_name=None, user_name=None, run_name=None, model=None, embedding_model=None, vector_store_config=None, mem0_config=None, default_memory_type=None, **kwargs)[source]

Initialize the Mem0LongTermMemory instance

Parameters:

  • agent_name (str | None, optional) – The name of the agent. Default is None.

  • user_name (str | None, optional) – The name of the user. Default is None.

  • run_name (str | None, optional) – The name of the run/session. Default is None.

  • model (ChatModelBase | None)

  • embedding_model (EmbeddingModelBase | None)

  • vector_store_config (Any | None)

  • mem0_config (Any | None)

  • default_memory_type (str | None)

  • kwargs (Any)

Return type:

None

Note

  1. At least one of agent_name, user_name, or run_name is required.

  2. During memory recording, these parameters become metadata for the stored memories.

  3. During memory retrieval, only memories with matching metadata values will be returned.

model (ChatModelBase | None, optional):

The chat model to use for the long-term memory. If mem0_config is provided, this will override the LLM configuration. If mem0_config is None, this is required.

embedding_model (EmbeddingModelBase | None, optional):

The embedding model to use for the long-term memory. If mem0_config is provided, this will override the embedder configuration. If mem0_config is None, this is required.

vector_store_config (VectorStoreConfig | None, optional):

The vector store config to use for the long-term memory. If mem0_config is provided, this will override the vector store configuration. If mem0_config is None and this is not provided, defaults to Qdrant with on_disk=True.

mem0_config (MemoryConfig | None, optional):

The mem0 config to use for the long-term memory. If provided, individual model/embedding_model/vector_store_config parameters will override the corresponding configurations in mem0_config. If None, a new MemoryConfig will be created using the provided parameters.

default_memory_type (str | None, optional):

The type of memory to use. Default is None, to create a semantic memory.

Raises:

ValueError – If mem0_config is None and either model or embedding_model is None.

Parameters:

  • agent_name (str | None)

  • user_name (str | None)

  • run_name (str | None)

  • model (ChatModelBase | None)

  • embedding_model (EmbeddingModelBase | None)

  • vector_store_config (Any | None)

  • mem0_config (Any | None)

  • default_memory_type (str | None)

  • kwargs (Any)

Return type:

None

async record_to_memory(thinking, content, **kwargs)[source]

Use this function to record important information that you may need later. The target content should be specific and concise, e.g. who, when, where, do what, why, how, etc.

Parameters:

  • thinking (str) – Your thinking and reasoning about what to record.

  • content (list[str]) – The content to remember, which is a list of strings.

  • kwargs (Any)

Return type:

ToolResponse

async retrieve_from_memory(keywords, limit=5, **kwargs)[source]

Retrieve the memory based on the given keywords.

Parameters:

  • keywords (list[str]) – The keywords to search for in the memory, which should be specific and concise, e.g. the person’s name, the date, the location, etc.

  • limit (int, optional) – The maximum number of memories to retrieve per search.

  • kwargs (Any)

Returns:

A ToolResponse containing the retrieved memories as JSON text.

Return type:

ToolResponse

async record(msgs, memory_type=None, infer=True, **kwargs)[source]

Record the content to the long-term memory.

Parameters:

  • msgs (list[Msg | None]) – The messages to record to memory.

  • memory_type (str | None, optional) – The type of memory to use. Default is None, to create a semantic memory. “procedural_memory” is explicitly used for procedural memories.

  • infer (bool, optional) – Whether to infer memory from the content. Default is True.

  • **kwargs (Any) – Additional keyword arguments for the mem0 recording.

Return type:

None

async retrieve(msg, limit=5, **kwargs)[source]

Retrieve the content from the long-term memory.

Parameters:

  • msg (Msg | list[Msg] | None) – The message to search for in the memory, which should be specific and concise, e.g. the person’s name, the date, the location, etc.

  • limit (int, optional) – The maximum number of memories to retrieve per search.

  • **kwargs (Any) – Additional keyword arguments.

Returns:

The retrieved memory

Return type:

str