camel.memories 包

本页内容

camel.memories 包#

子包#

子模块#

camel.memories.agent_memories 模块#

class camel.memories.agent_memories.ChatHistoryMemory(context_creator: BaseContextCreator, storage: BaseKeyValueStorage | None = None, window_size: int | None = None, agent_id: str | None = None)[来源]#

基类:AgentMemory

ChatHistoryBlock的代理内存包装器。

Parameters:
  • context_creator (BaseContextCreator) – 一个模型上下文创建器。

  • storage (BaseKeyValueStorage, optional) – 用于存储聊天历史的后端存储。如果为None,将使用InMemoryKeyValueStorage。(默认值: None)

  • window_size (int, optional) – 要检索的最近聊天消息数量。如果未提供,将检索整个聊天历史记录。(默认: None)

  • agent_id (str, optional) – 与聊天历史记录关联的代理ID。

property agent_id: str | None#
clear() None[来源]#

清除内存中的所有消息。

get_context_creator() BaseContextCreator[来源]#

获取上下文创建器。

Returns:

模型上下文创建器。

Return type:

BaseContextCreator

retrieve() List[ContextRecord][来源]#

从内存中获取记录列表以创建模型上下文。

Returns:

用于创建模型上下文的记录列表。

Return type:

列表[ContextRecord]

write_records(records: List[MemoryRecord]) None[来源]#

将记录写入内存,追加到现有记录之后。

Parameters:

records (List[MemoryRecord]) – 要添加到内存中的记录。

class camel.memories.agent_memories.LongtermAgentMemory(context_creator: BaseContextCreator, chat_history_block: ChatHistoryBlock | None = None, vector_db_block: VectorDBBlock | None = None, retrieve_limit: int = 3, agent_id: str | None = None)[来源]#

基类:AgentMemory

一个实现AgentMemory抽象基类的方案,用于通过VectorDBMemory增强ChatHistoryMemory。

Parameters:
  • context_creator (BaseContextCreator) – 一个模型上下文创建器。

  • chat_history_block (Optional[ChatHistoryBlock], optional) – 一个聊天历史记录块。如果为None,将使用ChatHistoryBlock。 (默认值: None)

  • vector_db_block (可选[VectorDBBlock], 可选) – 一个向量数据库块。如果为None,将使用VectorDBBlock。 (默认: None)

  • retrieve_limit (int, optional) – 要添加到上下文中的最大消息数量。(默认值: 3)

  • agent_id (str, optional) – 与聊天历史记录和向量数据库中存储的消息相关联的代理ID。

property agent_id: str | None#
clear() None[来源]#

从内存中移除所有记录。

get_context_creator() BaseContextCreator[来源]#

返回内存使用的上下文创建器。

Returns:

内存使用的上下文创建器。

Return type:

BaseContextCreator

retrieve() List[ContextRecord][来源]#

从聊天历史和向量数据库中检索上下文记录。

Returns:

从以下两者获取的上下文记录列表

聊天历史和向量数据库。

Return type:

列表[ContextRecord]

write_records(records: List[MemoryRecord]) None[来源]#

将提供的聊天消息转换为向量表示,并将其写入向量数据库。

Parameters:

records (List[MemoryRecord]) – 要添加到向量数据库的消息。

class camel.memories.agent_memories.VectorDBMemory(context_creator: BaseContextCreator, storage: BaseVectorStorage | None = None, retrieve_limit: int = 3, agent_id: str | None = None)[来源]#

基类:AgentMemory

VectorDBBlock的代理内存包装器。该内存会查询存储在向量数据库中的消息。请注意,最新的消息不会被添加到上下文中。

Parameters:
  • context_creator (BaseContextCreator) – 一个模型上下文创建器。

  • storage (BaseVectorStorage, optional) – 向量存储。如果为None,将使用QdrantStorage。 (默认值: None)

  • retrieve_limit (int, optional) – 要添加到上下文中的最大消息数量。(默认值: 3)

  • agent_id (str, optional) – 与存储在向量数据库中的消息相关联的代理ID。

property agent_id: str | None#
clear() None[来源]#

从向量数据库内存中移除所有记录。

get_context_creator() BaseContextCreator[来源]#

获取上下文创建器。

Returns:

模型上下文创建器。

Return type:

BaseContextCreator

retrieve() List[ContextRecord][来源]#

从内存中获取记录列表以创建模型上下文。

Returns:

用于创建模型上下文的记录列表。

Return type:

列表[ContextRecord]

write_records(records: List[MemoryRecord]) None[来源]#

将记录写入内存,追加到现有记录之后。

Parameters:

records (List[MemoryRecord]) – 要添加到内存中的记录。

camel.memories.base 模块#

class camel.memories.base.AgentMemory[来源]#

基类:MemoryBlock, ABC

代表一种特殊形式的MemoryBlock,专为与代理直接集成而设计。两个关键的抽象函数"retrieve"和"get_context_creator"用于根据存储在AgentMemory中的内存记录生成模型上下文。

abstract property agent_id: str | None#
get_context() Tuple[List[ChatCompletionDeveloperMessageParam | ChatCompletionSystemMessageParam | ChatCompletionUserMessageParam | ChatCompletionAssistantMessageParam | ChatCompletionToolMessageParam | ChatCompletionFunctionMessageParam], int][来源]#

从内存中获取适合agent大小的聊天上下文。

Returns:

一个包含构建的元组

以OpenAIMessage格式的上下文和总令牌数。

Return type:

(List[OpenAIMessage], int)

abstract get_context_creator() BaseContextCreator[来源]#

获取上下文创建器。

Returns:

模型上下文创建器。

Return type:

BaseContextCreator

abstract retrieve() List[ContextRecord][来源]#

从内存中获取记录列表以创建模型上下文。

Returns:

用于创建模型上下文的记录列表。

Return type:

列表[ContextRecord]

class camel.memories.base.BaseContextCreator[来源]#

基类: ABC

一个抽象基类,定义了上下文创建策略的接口。

该类为从上下文记录列表生成对话内容的不同策略提供了基础框架。主要目标是创建一个符合指定令牌数量限制的上下文,允许子类定义它们的具体实现方法。

子类应实现token_counter、:obj: token_limit以及create_context方法,以提供特定的上下文创建逻辑。

token_counter#

一个负责统计消息中令牌(token)数量的令牌计数器实例。

Type:

BaseTokenCounter

token_limit#

生成上下文中允许的最大token数量。

Type:

int

abstract create_context(records: List[ContextRecord]) Tuple[List[ChatCompletionDeveloperMessageParam | ChatCompletionSystemMessageParam | ChatCompletionUserMessageParam | ChatCompletionAssistantMessageParam | ChatCompletionToolMessageParam | ChatCompletionFunctionMessageParam], int][来源]#

一个从聊天历史创建对话上下文的抽象方法。

根据提供的记录构建上下文。具体实现方式及token计数的管理应由实现该方法的子类提供。输出消息的顺序应与输入顺序保持一致。

Parameters:

records (List[ContextRecord]) – 用于生成上下文的上下文记录列表。

Returns:

一个包含构建的元组

OpenAIMessage格式的上下文和总令牌计数。

Return type:

元组[列表[OpenAIMessage], 整数]

abstract property token_counter: BaseTokenCounter#
abstract property token_limit: int#
class camel.memories.base.MemoryBlock[来源]#

基类: ABC

抽象类是智能体记忆系统中的基础组件。该类配备了"写入"和"清除"功能。但有意未定义检索接口,因为待检索数据的结构在不同类型的内存块中可能各不相同。

abstract clear() None[来源]#

清除内存中的所有消息。

write_record(record: MemoryRecord) None[来源]#

将记录写入内存,追加到现有记录之后。

Parameters:

record (MemoryRecord) – 要添加到内存中的记录。

abstract write_records(records: List[MemoryRecord]) None[来源]#

将记录写入内存,追加到现有记录之后。

Parameters:

records (List[MemoryRecord]) – 要添加到内存中的记录。

camel.memories.records 模块#

class camel.memories.records.ContextRecord(*, memory_record: ~camel.memories.records.MemoryRecord, score: float, timestamp: float = <factory>)[来源]#

基类:BaseModel

内存检索的结果。

memory_record: MemoryRecord#
model_config: ClassVar[ConfigDict] = {}#

模型的配置,应该是一个符合[ConfigDict][pydantic.config.ConfigDict]的字典。

score: float#
timestamp: float#
class camel.memories.records.MemoryRecord(*, message: ~camel.messages.base.BaseMessage, role_at_backend: ~camel.types.enums.OpenAIBackendRole, uuid: ~uuid.UUID = <factory>, extra_info: ~typing.Dict[str, str] = <factory>, timestamp: float = <factory>, agent_id: str = '')[来源]#

基类:BaseModel

CAMEL内存系统中的基本消息存储单元。

message#

记录的主要内容。

Type:

BaseMessage

role_at_backend#

一个枚举值,表示该消息在OpenAI后端所扮演的角色。请注意,该值与CAMEL角色扮演系统中使用的RoleType不同。

Type:

OpenAIBackendRole

uuid#

此记录的唯一通用标识符。 用于在内存系统中唯一标识该记录。 如果未提供,将自动分配一个随机UUID。

Type:

UUID,可选

extra_info#

一个包含额外键值对的字典,用于提供更多信息。如果未提供,它将是一个空的Dict

Type:

Dict[str, str], 可选

timestamp#

记录创建时的时间戳。

Type:

浮点数,可选

agent_id#

与该内存关联的代理标识符。

Type:

字符串

agent_id: str#
extra_info: Dict[str, str]#
classmethod from_dict(record_dict: Dict[str, Any]) MemoryRecord[来源]#

从输入字典中重建一个MemoryRecord

Parameters:

record_dict (Dict[str, Any]) – 由to_dict()生成的字典。

message: BaseMessage#
model_config: ClassVar[ConfigDict] = {'arbitrary_types_allowed': True}#

模型的配置,应该是一个符合[ConfigDict][pydantic.config.ConfigDict]的字典。

role_at_backend: OpenAIBackendRole#
timestamp: float#
to_dict() Dict[str, Any][来源]#

MemoryRecord转换为字典以便进行序列化。

to_openai_message() ChatCompletionDeveloperMessageParam | ChatCompletionSystemMessageParam | ChatCompletionUserMessageParam | ChatCompletionAssistantMessageParam | ChatCompletionToolMessageParam | ChatCompletionFunctionMessageParam[来源]#

将记录转换为OpenAIMessage对象。

uuid: UUID#

模块内容#

class camel.memories.AgentMemory[来源]#

基类:MemoryBlock, ABC

代表一种特殊形式的MemoryBlock,专为与代理直接集成而设计。两个关键的抽象函数"retrieve"和"get_context_creator"用于根据存储在AgentMemory中的内存记录生成模型上下文。

abstract property agent_id: str | None#
get_context() Tuple[List[ChatCompletionDeveloperMessageParam | ChatCompletionSystemMessageParam | ChatCompletionUserMessageParam | ChatCompletionAssistantMessageParam | ChatCompletionToolMessageParam | ChatCompletionFunctionMessageParam], int][来源]#

从内存中获取适合agent大小的聊天上下文。

Returns:

一个包含构建的元组

OpenAIMessage格式的上下文和总令牌计数。

Return type:

(List[OpenAIMessage], int)

abstract get_context_creator() BaseContextCreator[来源]#

获取上下文创建器。

Returns:

模型上下文创建器。

Return type:

BaseContextCreator

abstract retrieve() List[ContextRecord][来源]#

从内存中获取记录列表以创建模型上下文。

Returns:

用于创建模型上下文的记录列表。

Return type:

列表[ContextRecord]

class camel.memories.BaseContextCreator[来源]#

基类: ABC

一个抽象基类,定义了上下文创建策略的接口。

该类为从上下文记录列表生成对话内容的不同策略提供了基础框架。主要目标是创建一个符合指定令牌数量限制的上下文,允许子类定义它们的具体实现方法。

子类应实现token_counter、:obj: token_limit以及create_context方法,以提供特定的上下文创建逻辑。

token_counter#

一个负责统计消息中令牌(token)数量的令牌计数器实例。

Type:

BaseTokenCounter

token_limit#

生成上下文中允许的最大token数量。

Type:

int

abstract create_context(records: List[ContextRecord]) Tuple[List[ChatCompletionDeveloperMessageParam | ChatCompletionSystemMessageParam | ChatCompletionUserMessageParam | ChatCompletionAssistantMessageParam | ChatCompletionToolMessageParam | ChatCompletionFunctionMessageParam], int][来源]#

一个从聊天历史创建对话上下文的抽象方法。

根据提供的记录构建上下文。具体实现方式及token计数的管理应由实现该方法的子类提供。输出消息的顺序应与输入顺序保持一致。

Parameters:

records (List[ContextRecord]) – 用于生成上下文的上下文记录列表。

Returns:

一个包含构建的元组

OpenAIMessage格式的上下文和总令牌计数。

Return type:

元组[列表[OpenAIMessage], 整数]

abstract property token_counter: BaseTokenCounter#
abstract property token_limit: int#
class camel.memories.ChatHistoryBlock(storage: BaseKeyValueStorage | None = None, keep_rate: float = 0.9)[来源]#

基类:MemoryBlock

一个实现MemoryBlock抽象基类的实现,用于维护聊天历史记录。

该内存模块帮助管理对话历史记录,采用键值存储后端,可由用户提供或使用默认的内存存储。它提供了一种窗口化的方式来检索聊天历史记录,允许用户指定他们想要获取的最近消息数量。

Parameters:
  • storage (BaseKeyValueStorage, optional) – 用于存储聊天历史的存储机制。如果为None,将使用InMemoryKeyValueStorage。(默认值: None)

  • keep_rate (float, optional) – 在历史消息中,最后一条消息的分数为1.0,每向后回溯一步,消息分数会乘以keep_rate。较高的keep_rate值会在创建上下文时保留更多历史消息。

clear() None[来源]#

清除内存中的所有聊天消息。

retrieve(window_size: int | None = None) List[ContextRecord][来源]#

根据窗口大小从内存中检索适合代理的记录,如果未指定窗口大小,则获取整个聊天历史记录。

Parameters:

window_size (int, optional) – 指定要检索的最近聊天消息数量。如果未提供,将检索整个聊天历史记录。(默认: None)

Returns:

检索到的记录列表。

Return type:

列表[ContextRecord]

write_records(records: List[MemoryRecord]) None[来源]#

将内存记录写入内存。此外,还会对消息执行验证检查。

Parameters:

records (List[MemoryRecord]) – 要添加到内存中的内存记录。

class camel.memories.ChatHistoryMemory(context_creator: BaseContextCreator, storage: BaseKeyValueStorage | None = None, window_size: int | None = None, agent_id: str | None = None)[来源]#

基类:AgentMemory

ChatHistoryBlock 的代理内存包装器。

Parameters:
  • context_creator (BaseContextCreator) – 一个模型上下文创建器。

  • storage (BaseKeyValueStorage, optional) – 用于存储聊天历史的后端存储。如果为None,将使用InMemoryKeyValueStorage。(默认值: None)

  • window_size (int, optional) – 要检索的最近聊天消息数量。如果未提供,将检索整个聊天历史记录。(默认: None)

  • agent_id (str, optional) – 与聊天历史记录关联的代理ID。

property agent_id: str | None#
clear() None[来源]#

清除内存中的所有消息。

get_context_creator() BaseContextCreator[来源]#

获取上下文创建器。

Returns:

模型上下文创建器。

Return type:

BaseContextCreator

retrieve() List[ContextRecord][来源]#

从内存中获取记录列表以创建模型上下文。

Returns:

用于创建模型上下文的记录列表。

Return type:

列表[ContextRecord]

write_records(records: List[MemoryRecord]) None[来源]#

将记录写入内存,追加到现有记录之后。

Parameters:

records (List[MemoryRecord]) – 要添加到内存中的记录。

class camel.memories.ContextRecord(*, memory_record: ~camel.memories.records.MemoryRecord, score: float, timestamp: float = <factory>)[来源]#

基类:BaseModel

内存检索的结果。

memory_record: MemoryRecord#
model_config: ClassVar[ConfigDict] = {}#

模型的配置,应该是一个符合[ConfigDict][pydantic.config.ConfigDict]的字典。

score: float#
timestamp: float#
class camel.memories.LongtermAgentMemory(context_creator: BaseContextCreator, chat_history_block: ChatHistoryBlock | None = None, vector_db_block: VectorDBBlock | None = None, retrieve_limit: int = 3, agent_id: str | None = None)[来源]#

基类:AgentMemory

一个AgentMemory抽象基类的实现,用于通过VectorDBMemory增强ChatHistoryMemory。

Parameters:
  • context_creator (BaseContextCreator) – 一个模型上下文创建器。

  • chat_history_block (可选[ChatHistoryBlock], 可选) – 一个聊天历史记录块。如果为None,将使用ChatHistoryBlock。 (默认值: None)

  • vector_db_block (可选[VectorDBBlock], 可选) – 一个向量数据库块。如果为None,将使用VectorDBBlock。 (默认值: None)

  • retrieve_limit (int, optional) – 要添加到上下文中的最大消息数量。(默认值: 3)

  • agent_id (str, optional) – 与聊天历史记录和向量数据库中存储的消息相关联的代理ID。

property agent_id: str | None#
clear() None[来源]#

从内存中移除所有记录。

get_context_creator() BaseContextCreator[来源]#

返回内存使用的上下文创建器。

Returns:

内存使用的上下文创建器。

Return type:

BaseContextCreator

retrieve() List[ContextRecord][来源]#

从聊天历史和向量数据库中检索上下文记录。

Returns:

从以下两者获取的上下文记录列表

聊天历史和向量数据库。

Return type:

列表[ContextRecord]

write_records(records: List[MemoryRecord]) None[来源]#

将提供的聊天消息转换为向量表示,并将其写入向量数据库。

Parameters:

records (List[MemoryRecord]) – 要添加到向量数据库的消息。

class camel.memories.MemoryBlock[来源]#

基类: ABC

抽象类是智能体记忆系统中的基础组件。该类配备了"写入"和"清除"功能。但有意未定义检索接口,因为待检索数据的结构在不同类型的内存块中可能各不相同。

abstract clear() None[来源]#

清除内存中的所有消息。

write_record(record: MemoryRecord) None[来源]#

将记录写入内存,追加到现有记录之后。

Parameters:

record (MemoryRecord) – 要添加到内存中的记录。

abstract write_records(records: List[MemoryRecord]) None[来源]#

将记录写入内存,追加到现有记录之后。

Parameters:

records (List[MemoryRecord]) – 要添加到内存中的记录。

class camel.memories.MemoryRecord(*, message: ~camel.messages.base.BaseMessage, role_at_backend: ~camel.types.enums.OpenAIBackendRole, uuid: ~uuid.UUID = <factory>, extra_info: ~typing.Dict[str, str] = <factory>, timestamp: float = <factory>, agent_id: str = '')[来源]#

基类:BaseModel

CAMEL内存系统中的基本消息存储单元。

message#

记录的主要内容。

Type:

BaseMessage

role_at_backend#

一个枚举值,表示该消息在OpenAI后端扮演的角色。请注意,该值与CAMEL角色扮演系统中使用的RoleType不同。

Type:

OpenAIBackendRole

uuid#

此记录的唯一通用标识符。 用于在内存系统中唯一标识该记录。 如果未提供,将自动分配一个随机UUID。

Type:

UUID,可选

extra_info#

一个包含额外键值对的字典,用于提供更多信息。如果未提供,它将是一个空的Dict

Type:

Dict[str, str], 可选

timestamp#

记录创建时的时间戳。

Type:

浮点数,可选

agent_id#

与该内存关联的代理标识符。

Type:

字符串

agent_id: str#
extra_info: Dict[str, str]#
classmethod from_dict(record_dict: Dict[str, Any]) MemoryRecord[来源]#

从输入字典中重建一个MemoryRecord

Parameters:

record_dict (Dict[str, Any]) – 由to_dict()生成的字典。

message: BaseMessage#
model_config: ClassVar[ConfigDict] = {'arbitrary_types_allowed': True}#

模型的配置,应该是一个符合[ConfigDict][pydantic.config.ConfigDict]的字典。

role_at_backend: OpenAIBackendRole#
timestamp: float#
to_dict() Dict[str, Any][来源]#

MemoryRecord转换为字典以便进行序列化。

to_openai_message() ChatCompletionDeveloperMessageParam | ChatCompletionSystemMessageParam | ChatCompletionUserMessageParam | ChatCompletionAssistantMessageParam | ChatCompletionToolMessageParam | ChatCompletionFunctionMessageParam[来源]#

将记录转换为OpenAIMessage对象。

uuid: UUID#
class camel.memories.ScoreBasedContextCreator(token_counter: BaseTokenCounter, token_limit: int)[来源]#

基类: BaseContextCreator

上下文创建策略的默认实现,继承自BaseContextCreator

该类提供了一种策略,用于从聊天历史记录列表中生成对话上下文,同时确保上下文的token总数不超过指定限制。如果token总数超过限制,则会根据消息的分数进行修剪。

Parameters:
  • token_counter (BaseTokenCounter) – 一个负责计算消息中token数量的实例。

  • token_limit (int) – 生成上下文中允许的最大token数量。

create_context(records: List[ContextRecord]) Tuple[List[ChatCompletionDeveloperMessageParam | ChatCompletionSystemMessageParam | ChatCompletionUserMessageParam | ChatCompletionAssistantMessageParam | ChatCompletionToolMessageParam | ChatCompletionFunctionMessageParam], int][来源]#

在遵守token限制的前提下,从聊天历史记录构建对话上下文。

关键策略: 1. 系统消息始终优先并保留 2. 截断操作会先移除低分消息 3. 最终输出保持时间顺序并存入历史记忆

每条消息的分数会根据keep_rate递减。消息越新,分数越高。

Parameters:

records (List[ContextRecord]) - 带有分数和时间戳的上下文记录列表。

Returns:

  • OpenAI消息的有序列表

  • 最终上下文的总令牌计数

Return type:

元组[列表[OpenAIMessage], 整数]

Raises:

RuntimeError - 如果仅系统消息就超出token限制

property token_counter: BaseTokenCounter#
property token_limit: int#
class camel.memories.VectorDBBlock(storage: BaseVectorStorage | None = None, embedding: BaseEmbedding | None = None)[来源]#

基类:MemoryBlock

一个实现MemoryBlock抽象基类的实现,用于在向量数据库中维护和检索使用向量嵌入的信息。

Parameters:
  • storage (Optional[BaseVectorStorage], optional) – 向量数据库的存储机制。如果未提供,默认为内存中的Qdrant。(默认值: None)

  • embedding (可选[BaseEmbedding], 可选) - 用于将聊天消息转换为向量表示的嵌入机制。如果未提供,默认为OpenAiEmbedding。(默认值: None)

clear() None[来源]#

从向量数据库内存中移除所有记录。

retrieve(keyword: str, limit: int = 3) List[ContextRecord][来源]#

根据关键词内容从向量数据库中检索相似记录。

Parameters:
  • keyword (str) – 该字符串将被转换为向量表示形式以查询数据库。

  • limit (int, optional) – 要检索的相似消息的最大数量。(默认: 3).

Returns:

向量数据库中检索出的与current_state相似度相关的内存记录列表。

Return type:

列表[ContextRecord]

write_records(records: List[MemoryRecord]) None[来源]#

将提供的聊天消息转换为向量表示,并将其写入向量数据库。

Parameters:

records (List[MemoryRecord]) – 要添加到内存中的内存记录。

class camel.memories.VectorDBMemory(context_creator: BaseContextCreator, storage: BaseVectorStorage | None = None, retrieve_limit: int = 3, agent_id: str | None = None)[来源]#

基类:AgentMemory

VectorDBBlock的代理内存包装器。该内存会查询存储在向量数据库中的消息。请注意,最新的消息不会被添加到上下文中。

Parameters:
  • context_creator (BaseContextCreator) – 一个模型上下文创建器。

  • storage (BaseVectorStorage, optional) – 一个向量存储。如果为None,将使用QdrantStorage。 (默认: None)

  • retrieve_limit (int, optional) – 要添加到上下文中的最大消息数量。(默认值: 3)

  • agent_id (str, optional) – 与存储在向量数据库中的消息相关联的代理ID。

property agent_id: str | None#
clear() None[来源]#

从向量数据库内存中移除所有记录。

get_context_creator() BaseContextCreator[来源]#

获取上下文创建器。

Returns:

模型上下文创建器。

Return type:

BaseContextCreator

retrieve() List[ContextRecord][来源]#

从内存中获取记录列表以创建模型上下文。

Returns:

用于创建模型上下文的记录列表。

Return type:

列表[ContextRecord]

write_records(records: List[MemoryRecord]) None[来源]#

将记录写入内存,追加到现有记录之后。

Parameters:

records (List[MemoryRecord]) – 要添加到内存中的记录。