线程

此页提供了具体的 Oracle 线程句柄以及面向开发者的消息帮助程序类型。

Oracle 线程

class oracleagentmemory.core.OracleThread

基础：IThread

由 Oracle 存储支持的线程。

此实现嵌入并存储线程消息和手动添加的内存，然后支持对所有存储的记录进行相似性搜索。

注释

• 消息存储为单个记录（每条消息一条记录）。
• 可以将搜索限制为当前线程，也可以允许从任何线程返回结果（由客户机控制）。

创建新的 OracleThread 实例。

• 参数：
  • store OracleMemoryStore- 用于保存嵌入式记录的共享存储后端。
  • thread_id str- 线程标识符。如果未提供，将生成 UUID。
  • user_id str- 与线程关联的用户标识符。如果在 DB SchemaPolicy.NO_CHECK 运行时存储上省略，则使用活动的最终用户安全上下文的用户名。否则，将生成 UUID。
  • agent_id str- 与线程关联的代理标识符。如果省略，将生成 UUID。
  • metadata dict[str, Any] | None- 与线程关联的可选类似 JSON 的元数据。
  • persist_messages_in_config bool-_to_config 是否应包括最近的原始消息快照。使用数据库存储的线程自动设置为 False，以避免通过线程配置导出消息表内容。
  • LLM ILlm | None- 用于内存提取和上下文摘要更新的可选 LLM 适配器。如果提供，add_messages 将从每条添加的消息中提取相关内存，并将其存储为键入的内存记录（"memory"、"guideline"、"fact" 或 "preference"）。
  • memory_extraction_config MemoryExtractionConfig- 可选线程级内存提取配置。使用它可控制自动提取设置，例如提取模式、摘要行为、提取限制以及是否启用自动提取。传递此分组配置或过时的内嵌提取参数，而不是同时传递这两个参数。省略时，独立 OracleThread() 会为提取字段使用 SDK 默认值，并保持启用上下文摘要。省略的图像上下文为 DISABLED。
  • image_input_limit_config ImageInputLimitConfig- 此独立线程的可选原始映像和 LLM 映像请求限制。省略的字段使用 SDK 默认值。无法禁用验证。

  • memory_extraction_window int-

    提取期间要作为上下文提供给 LLM 的最新消息（包括新添加的消息）的数量。设置为 -1 以使用新添加的全部消息批量仅提取每个 add_messages 调用一次。默认值为 -1。

    已弃用

    自版本 26.6.0 起已废弃：此参数在 26.6.0 中已废弃，将在 27.1 中删除。请改用 memory_extraction_config。

  • context_summary_update_frequency int-

    自动刷新最新有效汇总后的消息数。启用内存提取后，将在每次到期提取后进行检查，因此以后可能会刷新。每次检查时值小于或等于 0 刷新。默认值为 -1。

    已弃用

    自版本 26.6.0 起已废弃：此参数在 26.6.0 中已废弃，将在 27.1 中删除。请改用 memory_extraction_config。

  • memory_extraction_frequency int-

    触发内存提取之后的消息数。设置为 -1 以使用新添加的全部消息批量仅提取每个 add_messages 调用一次。

    已弃用

    自版本 26.6.0 起已废弃：此参数在 26.6.0 中已废弃，将在 27.1 中删除。请改用 memory_extraction_config。

  • memory_extraction_token_limit int-

    用于内存提取和运行摘要更新的 LLM 提示的最大大小（以标记为单位）。较长的提示将被截断。如果为负值或 0，则禁用提示截断。

    已弃用

    自版本 26.6.0 起已废弃：此参数在 26.6.0 中已废弃，将在 27.1 中删除。请改用 memory_extraction_config。

  • context_card_token_limit int- 用于构建上下文卡中包括的摘要和主题列表的 LLM 提示符的最大输入令牌预算。默认值为 100_000；小于或等于 0 的值将禁用提示截断。
  • context_card_type_search_concurrency int- 使用 min_relevant_results_by_type 构建上下文卡时要同时运行的最大内存类记录搜索数。默认为 5。
  • max_message_token_length int-LLM 支持的内存提取和上下文摘要更新期间使用的每条消息的提示时副本的最大大小（以令牌为单位）。存储的消息内容保持不变。如果为负值或 0，则不执行即时时间缩短。如果提供了 LLM，则会汇总超大的提示副本，而不是截断。
  • message_shortening_input_token_limit int- 缩短超大提示副本时发送到 LLM 的消息摘录的最大大小（以令牌表示）。默认为 30_000 标记。如果为负值或 0，则在基于 LLM 的缩短期间不会应用出站绑定。

  • enable_context_summary bool-

    是否保留线程的紧凑摘要。启用并提供了 llm 时，OAM 将根据 context_summary_update_frequency 刷新它，并使用目标消息之前的摘要作为提取上下文。独立 OracleThread() 的默认值为 True。

    已弃用

    自版本 26.6.0 起已废弃：此参数在 26.6.0 中已废弃，将在 27.1 中删除。请改用 memory_extraction_config。

  • memory_extraction_custom_instructions str | None-

    附加到此线程的自动内存提取系统提示符的可选定制说明。

    已弃用

    自版本 26.6.0 起已废弃：此参数在 26.6.0 中已废弃，将在 27.1 中删除。请改用 memory_extraction_config。

  • memory_extraction_inherit_message_metadata bool | Sequence[str]-

    自动提取的内存是否从源消息继承元数据。传递 True 以继承所有消息元数据，传递顶层消息元数据键的非字符串序列以仅继承这些键，或者传递 False 以禁用继承。默认值为 True。如果一个提取通过使用多个源消息，则所选元数据必须与这些消息匹配。

    已弃用

    自版本 26.6.0 起已废弃：此参数在 26.6.0 中已废弃，将在 27.1 中删除。请改用 memory_extraction_config。

  • search_config MemorySearchConfig- 此线程的可选搜索配置。如果省略，搜索将使用固定的 top-k 搜索配置。
  • client（客户机）OracleAgentMemory | None

示例

from oracleagentmemory.core import MemoryExtractionConfig, OracleAgentMemory
client = OracleAgentMemory(connection=db_pool, embedder=embedder)
thread = client.create_thread(
    thread_id="c4",
    llm=llm,
    memory_extraction_config=MemoryExtractionConfig(enable_context_summary=True),
)
len(thread.add_messages([{"role": "user", "content": "I love pizza."}]))
1

method add_image

持久保存与此线程关联的一个图像。

description 存储为图像的可搜索文本。省略或 None 时，附加的 LLM 将生成标题。省略的范围值继承此线程的对应用户、代理和线程标识符。

• 参数：
  • image bytes- 要保留的原始映像字节数。
  • description str | None- 可选说明或标题。省略它以生成标题。
  • mime_type ImageMimeType- 用于映像持久性和标题生成的可选 MIME 类型。如果省略，SDK 将从映像字节检测并验证该类型。支持的检测类型包括 PNG、JPEG 和 WEBP。
  • image_id str- 可选标识符。省略时将生成一个。
  • user_id str | None- 可选范围断言。省略的值继承此线程的作用域；提供的值必须与它完全匹配。
  • agent_id str | None- 可选作用域断言。省略的值继承此线程的作用域；提供的值必须与它完全匹配。
  • thread_id str- 可选作用域断言。省略的值继承此线程的作用域；提供的值必须与它完全匹配。
  • metadata dict[str, Any] | None- 随映像一起存储的可选元数据。
  • timestamp str | None- 用于保存此映像的可选事件时间戳。省略此参数或传递 None 来存储 NULL 事件时间戳。读取映像时，其创建时间将作为有效时间戳返回。
  • ttl_days int | None- 可选的到期设置。
  • ttl_anchor TimeToLiveAnchor- 可选的到期设置。
  • store_kwargs Any- 其他特定于存储的选项。
• 返回：持久的图像标识符。
• 返回类型： str

method add_image_async（异步）

异步保存与此线程关联的一个映像。

description 存储为图像的可搜索文本。省略或 None 时，附加的 LLM 将生成标题。省略的范围值继承此线程的对应用户、代理和线程标识符。

• 参数：
  • image bytes- 要保留的原始映像字节数。
  • description str | None- 可选说明或标题。省略它以生成标题。
  • mime_type ImageMimeType- 用于映像持久性和标题生成的可选 MIME 类型。如果省略，SDK 将从映像字节检测并验证该类型。支持的检测类型包括 PNG、JPEG 和 WEBP。
  • image_id str- 可选标识符。省略时将生成一个。
  • user_id str | None- 可选范围断言。省略的值继承此线程的作用域；提供的值必须与它完全匹配。
  • agent_id str | None- 可选作用域断言。省略的值继承此线程的作用域；提供的值必须与它完全匹配。
  • thread_id str- 可选作用域断言。省略的值继承此线程的作用域；提供的值必须与它完全匹配。
  • metadata dict[str, Any] | None- 随映像一起存储的可选元数据。
  • timestamp str | None- 用于保存此映像的可选事件时间戳。省略此参数或传递 None 来存储 NULL 事件时间戳。读取映像时，其创建时间将作为有效时间戳返回。
  • ttl_days int | None- 可选的到期设置。
  • ttl_anchor TimeToLiveAnchor- 可选的到期设置。
  • store_kwargs Any- 其他特定于存储的选项。
• 返回：持久的图像标识符。
• 返回类型： str

method add_memory

添加手动内存条目并为其编制索引。

• 参数：
  • content str- 要存储为内存的文本内容。
  • memory_type Literal['memory', 'guideline', 'fact', 'preference'] | ~oracleagentmemory._notset._NotSetMarker- 要存储的内存类别。支持的值包括 "memory"、"fact"、"guideline" 和 "preference"。如果省略，内容将存储为常规 "memory"。
  • user_id str- 可选的用户标识符覆盖。
  • agent_id str- 可选代理标识符覆盖。
  • thread_id str- 可选线程标识符覆盖。
  • memory_id str- 可选的调用方为此内存行提供的稳定标识符。
  • metadata dict[str, Any] | None- 可与存储的内存一起保留的可选元数据。
  • timestamp str | None- 用于保存此内存的可选事件时间戳。省略此参数或传递 None 来存储 NULL 事件时间戳。读取记录时，其创建时间将作为有效时间戳返回。当 ttl_anchor 为 TimeToLiveAnchor.TIMESTAMP 时，提供具体的 ISO-8601 时间戳值。没有时区的 ISO-8601 时间戳将视为 UTC。
  • ttl_days int | None – Optional time-to-live duration in days. Omit this argument to use the schema default time-to-live duration. Pass None to use MemoryRetentionConfig.max_ttl_days when the retention configuration sets one, or to store a non-expiring memory when it does not. Values above MemoryRetentionConfig.max_ttl_days are clamped to that maximum with a warning.
  • ttl_anchor TimeToLiveAnchor- 可选的生存时间锚。使用 TimeToLiveAnchor.CREATED_AT 表示数据库创建时间，使用 TimeToLiveAnchor.TIMESTAMP 表示内存时间戳。时间戳锚定到期需要此内存的具体 ISO-8601 时间戳。没有时区的 ISO-8601 时间戳将视为 UTC。
  • status RecordStatus- 初始生命周期状态。省略以存储 RecordStatus.VALID。
  • autonomous_linking bool- 是否使用此线程的 LLM 创建从此新内存到相关存储内存的链接。如果 LLM 存在，则 "Omitted"（忽略）将启用它；通过 False 跳过。失败将保留存储器。
  • memory_id_to_link str- 一起创建从新内存到此现有线程拥有的内存的定向链路。省略的用户、代理和线程范围从该目标继承。省略两者以不创建显式链接。
  • link_type Literal['supersedes', 'contradicts', 'refines', 'supports', 'duplicates'] | ~oracleagentmemory._notset._NotSetMarker- 一起创建从新内存到此现有线程拥有的内存的定向链路。省略的用户、代理和线程范围从该目标继承。省略两者以不创建显式链接。
  • link_id str- 显式链路的可选标识符、时间戳和元数据。
  • link_timestamp str | None- 显式链路的可选标识符、时间戳和元数据。
  • link_metadata dict[str, Any] | None- 显式链路的可选标识符、时间戳和元数据。
  • **store_kwargs ( Any )- 转发到后备存储的特定于存储的写入选项。
• 返回：插入的内存记录的标识符。
• 返回类型： str

示例

thread.add_memory("Remember this preference", memory_id="mem-thread-docs")
'mem-thread-docs'

method add_memory_async（异步）

添加手动内存条目并异步为其编制索引。

• 参数：
  • content str- 要存储为内存的文本内容。
  • memory_type Literal['memory', 'guideline', 'fact', 'preference'] | ~oracleagentmemory._notset._NotSetMarker- 要存储的内存类别。支持的值包括 "memory"、"fact"、"guideline" 和 "preference"。如果省略，内容将存储为常规 "memory"。
  • user_id str- 可选的用户标识符覆盖。
  • agent_id str- 可选代理标识符覆盖。
  • thread_id str- 可选线程标识符覆盖。
  • memory_id str- 可选的调用方为此内存行提供的稳定标识符。
  • metadata dict[str, Any] | None- 可与存储的内存一起保留的可选元数据。
  • timestamp str | None- 用于保存此内存的可选事件时间戳。省略此参数或传递 None 来存储 NULL 事件时间戳。读取记录时，其创建时间将作为有效时间戳返回。当 ttl_anchor 为 TimeToLiveAnchor.TIMESTAMP 时，提供具体的 ISO-8601 时间戳值。没有时区的 ISO-8601 时间戳将视为 UTC。
  • ttl_days int | None – Optional time-to-live duration in days. Omit this argument to use the schema default time-to-live duration. Pass None to use MemoryRetentionConfig.max_ttl_days when the retention configuration sets one, or to store a non-expiring memory when it does not. Values above MemoryRetentionConfig.max_ttl_days are clamped to that maximum with a warning.
  • ttl_anchor TimeToLiveAnchor- 可选的生存时间锚。使用 TimeToLiveAnchor.CREATED_AT 表示数据库创建时间，使用 TimeToLiveAnchor.TIMESTAMP 表示内存时间戳。时间戳锚定到期需要此内存的具体 ISO-8601 时间戳。没有时区的 ISO-8601 时间戳将视为 UTC。
  • status RecordStatus- 初始生命周期状态。省略以存储 RecordStatus.VALID。
  • autonomous_linking bool- 是否使用此线程的 LLM 创建从此新内存到相关存储内存的链接。如果 LLM 存在，则 "Omitted"（忽略）将启用它；通过 False 跳过。失败将保留存储器。
  • memory_id_to_link str- 一起创建从新内存到此现有线程拥有的内存的定向链路。省略的用户、代理和线程范围从该目标继承。省略两者以不创建显式链接。
  • link_type Literal['supersedes', 'contradicts', 'refines', 'supports', 'duplicates'] | ~oracleagentmemory._notset._NotSetMarker- 一起创建从新内存到此现有线程拥有的内存的定向链路。省略的用户、代理和线程范围从该目标继承。省略两者以不创建显式链接。
  • link_id str- 显式链路的可选标识符、时间戳和元数据。
  • link_timestamp str | None- 显式链路的可选标识符、时间戳和元数据。
  • link_metadata dict[str, Any] | None- 显式链路的可选标识符、时间戳和元数据。
  • **store_kwargs ( Any )- 转发到后备存储的特定于存储的写入选项。
• 返回：插入的内存记录的标识符。
• 返回类型： str

示例

import asyncio
asyncio.run(thread.add_memory_async(
    "Remember this preference", memory_id="mem-thread-docs-async"
))
'mem-thread-docs-async'

method add_messages

将消息添加到主题并为其编制索引。

在后台提取模式下，此方法在插入原始消息并在后台尝试到期后台提取后返回。

在任一模式下自动提取之前，都会存储原始消息。如果以后提取或派生内存存储失败，原始消息将保留，而派生内存或摘要更新可能丢失。

• 参数：
  • messages Sequence[Message | ThreadMessageTypedDictT | Mapping[str, str | Sequence[Mapping[str, Any]] | Mapping[str, Any] | None]]- 要附加的消息列表。消息可以是 Message 对象或带有 role 和 content 的字典（以及可选的 id）。
  • metadata dict[str, Any] | None | list[dict[str, Any] | None]- 要持久保留的可选共享元数据或每消息元数据。省略时，将使用每个消息中嵌入的元数据。
  • ttl_days int | None | list[int | None]- 附加消息的可选生存时间（天）。省略此参数以使用模式默认的生存时间持续时间。传递 None 以在保留配置设置 MemoryRetentionConfig.max_ttl_days 时使用，或者在保留配置未设置时创建非过期消息。MemoryRetentionConfig.max_ttl_days 以上的值将夹到该最大值并显示警告。标量值应用于整个批。
  • ttl_anchor TimeToLiveAnchor | list[TimeToLiveAnchor]- 可选的生存时间锚。将 TimeToLiveAnchor.CREATED_AT 用于数据库创建时间，将 TimeToLiveAnchor.TIMESTAMP 用于每个消息时间戳。时间戳锚定到期需要每个受影响消息的具体 ISO-8601 时间戳。如果省略，消息将相对于 TimeToLiveAnchor.CREATED_AT 过期。没有时区的 ISO-8601 时间戳将视为 UTC。
  • **store_kwargs ( Any )- 转发到后备存储的特定于存储的写入选项。
• 返回：已插入消息记录的标识符。在后台提取模式下，返回这些标识符时，自动提取工作可能仍在运行。
• 返回类型： list[str]

注释

在 MemoryExtractionMode.BACKGROUND 中，原始消息在存储提取的内存之前会保留。如果后台提取没有排队，或者如果配置的队列容量等待达到其超时值，则插入的原始消息将保留存储，并且调用将继续而不提取内存，或者根据 background_extraction_queue_full_behavior 引发 TimeoutError。

示例

len(thread.add_messages([{"role": "user", "content": "Thread message from docs"}]))
1

method add_messages_async（异步）

异步向线程添加消息并为其编制索引。

在后台提取模式下，此方法在插入原始消息并在后台尝试到期后台提取后返回。

在任一模式下自动提取之前，都会存储原始消息。如果以后提取或派生内存存储失败，原始消息将保留，而派生内存或摘要更新可能丢失。

在 MemoryExtractionMode.BACKGROUND 中，原始消息在存储提取的内存之前会保留。如果后台提取没有排队，或者如果配置的队列容量等待达到其超时值，则插入的原始消息将保留存储，并且调用将继续而不提取内存，或者根据 background_extraction_queue_full_behavior 引发 TimeoutError。

• 参数：
  • messages（消息）Sequence[Message | ThreadMessageTypedDictT | Mapping[str, str | Sequence[Mapping[str, Any]] | Mapping[str, Any] | None]]
  • metadata（元数据）dict[str, Any] | None | list[dict[str, Any] | None]
  • ttl_days int | None | list[int | None]
  • ttl_anchor TimeToLiveAnchor | list[TimeToLiveAnchor]
  • store_kwargs Any
• 返回类型： list[str]

method delete_image

删除此线程拥有的一个图像。

• 参数：image_id str- 要删除的映像的标识符。
• 返回值：删除时为 1，否则为 0（图像不存在或属于其他线程）。
• 返回类型： int
• 引发：ValueError - 如果图像附加到消息。改为删除或更新父消息。

method delete_image_async（异步）

异步删除此线程拥有的一个映像。

• 参数：image_id str- 要删除的映像的标识符。
• 返回值：删除时为 1，否则为 0（图像不存在或属于其他线程）。
• 返回类型： int
• 引发：ValueError - 如果图像附加到消息。改为删除或更新父消息。

method delete_memory

按标识符从该精确线程中删除类似内存的记录（例如，内存、事实、首选项或准则）。

• 参数：memory_id str- 内存标识符。仅删除存储的 thread_id 与此线程完全匹配的类似内存的记录（memory、guideline、fact、preference）。
• 返回：已删除的记录数（0 或 1）。当标识符不存在或属于其他线程时，返回 0。
• 返回类型： int
• 引发：TimeoutError - 当先前接受此线程的后台提取未在 300 秒内完成时，在不删除记录的情况下引发。

注释

在删除记录之前，此方法将等待通过附加的代理内存组件接受此线程的早期后台提取。它不等待等待等待开始后接受的工作，也不等待其他组件或进程启动的工作。

示例

thread.delete_memory("456")
0

method delete_memory_async（异步）

以异步方式从该精确线程中删除类似内存的记录（例如，内存、事实、首选项或准则）。

• 参数：memory_id str- 内存标识符。仅删除存储的 thread_id 与此线程完全匹配的类似内存的记录（memory、guideline、fact、preference）。
• 返回：已删除的记录数（0 或 1）。当标识符不存在或属于其他线程时，返回 0。
• 返回类型： int
• 引发：TimeoutError - 当先前接受此线程的后台提取未在 300 秒内完成时，在不删除记录的情况下引发。

注释

此方法遵循 delete_memory() 所记录的后台提取等待和并发行为。

示例

import asyncio
asyncio.run(thread.delete_memory_async("456"))
0

method delete_message

按标识符从此确切线程中删除一条消息记录。

• 参数：message_id str- 消息标识符。仅删除其存储的 thread_id 与此线程完全匹配的消息。
• 退货：已删除的消息记录数（0 或 1）。当标识符不存在或属于其他线程时，返回 0。
• 返回类型： int
• 引发：TimeoutError - 当此线程早期接受的后台提取未在 300 秒内完成时，在不删除消息的情况下引发。

注释

在删除消息之前，此方法将等待通过连接的代理内存组件接受此线程的早期后台提取。它不等待等待等待开始后接受的工作，也不等待其他组件或进程启动的工作。

删除消息只会删除原始消息记录。派生记忆不会被删除，因为我们尚未跟踪从哪个消息中提取的记忆，因此它们可能仍然是可搜索的，或者仍然影响上下文卡的输出。使用 OracleAgentMemory.delete_thread() 可删除线程及其关联的消息和记忆。

示例

thread.delete_message("123")
0

method delete_message_async（异步）

按标识符异步删除此确切线程的消息记录。

• 参数：message_id str- 消息标识符。仅删除其存储的 thread_id 与此线程完全匹配的消息。
• 退货：已删除的消息记录数（0 或 1）。当标识符不存在或属于其他线程时，返回 0。
• 返回类型： int
• 引发：TimeoutError - 当此线程早期接受的后台提取未在 300 秒内完成时，在不删除消息的情况下引发。

注释

此方法遵循 delete_message() 所记录的后台提取等待和并发行为。

删除消息只会删除原始消息记录。派生记忆不会被删除，因为我们尚未跟踪从哪个消息中提取的记忆，因此它们可能仍然是可搜索的，或者仍然影响上下文卡的输出。使用 OracleAgentMemory.delete_thread() 可删除线程及其关联的消息和记忆。

示例

import asyncio
asyncio.run(thread.delete_message_async("123"))
0

method delete_record_link

按 ID 删除线程拥有的关系或完整的端点元组。

端点元组选择器必须使用存储的源到目标方向。

• 参数：
  • source_record_id str- 端点元组选择器的源标识符。
  • source_record_type str- 端点元组选择器的逻辑源记录类型。
  • target_record_id str- 端点元组选择器的目标标识符。
  • target_record_type str- 端点元组选择器的逻辑目标记录类型。
  • relation_type str- 端点元组选择器的源到目标标签。
  • relation_id str- 用于直接选择的关系标识符。仅提供此论点。
• 返回：已删除的关系数，可以是 0 或 1。
• 返回类型： int

示例

thread.delete_record_link(relation_id="relation-id")
1

method delete_record_link_async（异步）

异步删除此线程拥有的关系。

• 参数：
  • source_record_id str
  • source_record_type str
  • target_record_id str
  • target_record_type str
  • relation_type str
  • relation_id str
• 返回类型： int

method get_context_card

返回线程的上下文卡对象。

当 LLM 支持的实现可以执行远程网络 I/O 时，首选 get_context_card_async。

• 参数：
  • fallback_message_count int- 派生用于检索和呈现的回退摘要文本时要使用的最近消息数。如果省略，则将解析为 5。

  • max_relevant_results int-

    上下文卡的 <relevant_information> 部分中包含的最大相关记录数（例如，事实/首选项以及消息）。

    • 如果省略此值和 min_relevant_results_by_type，则 max_relevant_results 解析为 5。
    • 如果提供了 min_relevant_results_by_type，则 max_relevant_results 解析为 max(max_relevant_results, sum(min_relevant_results_by_type.values()))。
  • token_budget int | None- 上下文卡中已设置格式的相关结果的估计令牌计数的可选硬限制。省略时，将使用线程搜索配置。正值保持完整结果的排名顺序，而其累计估计值符合预算。如果第一个结果不合适，则不包含相关结果。非正值将禁用上限。
  • soft_token_budget int | None- 用于已设置格式的相关结果的估计标记计数的可选目标。省略时，将使用线程搜索配置。将保留达到或超过此目标的完整结果。非正值将禁用此目标。当输出还必须具有绝对限制时，将 token_budget 设置为更大的值。
  • max_recent_messages int- 要包括在上下文卡的 <recent_messages> 部分的最近对话消息的最大数量。如果省略，max_recent_messages 将解析为 0。

  • except_last_messages int-

    要从上下文卡中包括的生成的汇总和相关信息搜索中排除的尾随消息数。这样可以防止在 LLM 提示中单独提供的消息在上下文卡中重复。使用以下模式之一：

    • 外部原始尾巴（建议使用提示缓存）：

      get_context_card(except_last_messages=N, max_recent_messages=0) 提示包含上下文卡，后跟最后的 N 原始消息。

    • 自包含的上下文卡：

      get_context_card(except_last_messages=N, max_recent_messages=N) 上下文卡包含最后的 N 消息本身。

    非零时，max_recent_messages 必须为 0 或相同值。

  • min_relevant_results_by_type Mapping[Literal['message', 'memory', 'guideline', 'fact', 'preference'], int] | None | ~oracleagentmemory._notset._NotSetMarker- 上下文卡中包含的相关记录的每类型可选最小值。首先搜索请求的类型，其余的 max_relevant_results 插槽将填充所有支持的类似内存的记录类型。支持的密钥包括 "memory"、"fact"、"guideline"、"preference" 和 "message"。消息结果仅限于当前线程。

  • metadata_filter dict[str, Any] | None-

    搜索要在上下文卡中包括的类似内存的记录时，可选元数据筛选器映射用作范围筛选和记录类型筛选后的附加筛选器。metadata_filter 中的条目与 AND 语义组合。值不是字段级运算符字典的条目使用完全匹配语义：所请求的关键字必须存在于存储的记录元数据中。嵌套字典以递归方式匹配嵌套元数据对象。标量和列表值必须完全匹配；列表顺序和长度也必须匹配。省略此参数或传递 None 以在不进行元数据筛选的情况下进行搜索。示例包括 metadata_filter={"source": "chat"}（表示标量字段）、metadata_filter={"travel": {"need": "transit"}}（表示嵌套字段）和 metadata_filter={"tags": ["trip", "urgent"]}（表示完全匹配列表）。组合条件以要求所有条件：

    metadata_filter={
        "source": "chat",
        "travel": {"need": "transit"},
        "tags": ["trip", "urgent"],
    }

    要测试数组成员关系，请使用字段级运算符字典。"$array_contains" 匹配一个值或列表中的所有值。"$array_contains_any" 匹配列表中的至少一个值。"$not" 否定同一字段中的另一个字段级表达式，包括运算符字典或原始完全匹配值。如果正表达式失败（包括缺少的字段），则负数表达式匹配；负数数组成员资格也匹配非数组字段：

    metadata_filter={
        "source": "chat",
        "tags": {
            "$array_contains": "trip",
            "$not": {"$array_contains": "archived"},
        },
    }

  • include_invalid_results bool- 上下文卡中是否包括处于无效生命周期状态的相关记录。省略此参数或传递 True 以包含这些参数。传递 False 以将其排除。
  • **kwargs ( Any )- 保留供将来的上下文卡选项使用。意外的关键字参数引发 TypeError。
• 返回：上下文卡对象，其中包含基于最新消息的线程上下文摘要。使用 OracleContextCard.content 访问呈现的类似 XML 的文本。
• 返回类型：OracleContextCard

注释

这会将线程的缺省搜索范围与 exact_thread_match=False 一起使用，因此可能会包含来自同一用户/代理的其他线程的相关内存。

示例

thread.add_memory("User likes pizza", memory_id="mem-context-docs")
'mem-context-docs'
len(thread.add_messages([{"role": "user", "content": "Tell me about pizza"}]))
1
"User likes pizza" in thread.get_context_card().content
True
card = thread.get_context_card(
    max_relevant_results=4,
    min_relevant_results_by_type={"memory": 1},
)
len(card.relevant_results or []) <= 4
True

method get_context_card_async（异步）

异步返回线程的上下文卡对象。

• 参数：
  • fallback_message_count int- 派生用于检索和呈现的回退摘要文本时要使用的最近消息数。如果省略，则将解析为 5。

  • max_relevant_results int-

    上下文卡的 <relevant_information> 部分中包含的最大相关记录数（例如，事实/首选项以及消息）。

    • 如果省略此值和 min_relevant_results_by_type，则 max_relevant_results 解析为 5。
    • 如果提供了 min_relevant_results_by_type，则 max_relevant_results 解析为 max(max_relevant_results, sum(min_relevant_results_by_type.values()))。
  • token_budget int | None- 上下文卡中已设置格式的相关结果的估计令牌计数的可选硬限制。省略时，将使用线程搜索配置。正值保持完整结果的排名顺序，而其累计估计值符合预算。如果第一个结果不合适，则不包含相关结果。非正值将禁用上限。
  • soft_token_budget int | None- 用于已设置格式的相关结果的估计标记计数的可选目标。省略时，将使用线程搜索配置。将保留达到或超过此目标的完整结果。非正值将禁用此目标。当输出还必须具有绝对限制时，将 token_budget 设置为更大的值。
  • max_recent_messages int- 要包括在上下文卡的 <recent_messages> 部分的最近对话消息的最大数量。如果省略，max_recent_messages 将解析为 0。

  • except_last_messages int-

    要从上下文卡中包括的生成的汇总和相关信息搜索中排除的尾随消息数。这样可以防止在 LLM 提示中单独提供的消息在上下文卡中重复。使用以下模式之一：

    • 外部原始尾巴（建议使用提示缓存）：

      get_context_card(except_last_messages=N, max_recent_messages=0) 提示包含上下文卡，后跟最后的 N 原始消息。

    • 自包含的上下文卡：

      get_context_card(except_last_messages=N, max_recent_messages=N) 上下文卡包含最后的 N 消息本身。

    非零时，max_recent_messages 必须为 0 或相同值。

  • min_relevant_results_by_type Mapping[Literal['message', 'memory', 'guideline', 'fact', 'preference'], int] | None | ~oracleagentmemory._notset._NotSetMarker- 上下文卡中包含的相关记录的每类型可选最小值。首先搜索请求的类型，其余的 max_relevant_results 插槽将填充所有支持的类似内存的记录类型。支持的密钥包括 "memory"、"fact"、"guideline"、"preference" 和 "message"。消息结果仅限于当前线程。

  • metadata_filter dict[str, Any] | None-

    搜索要在上下文卡中包括的类似内存的记录时，可选元数据筛选器映射用作范围筛选和记录类型筛选后的附加筛选器。metadata_filter 中的条目与 AND 语义组合。值不是字段级运算符字典的条目使用完全匹配语义：所请求的关键字必须存在于存储的记录元数据中。嵌套字典以递归方式匹配嵌套元数据对象。标量和列表值必须完全匹配；列表顺序和长度也必须匹配。省略此参数或传递 None 以在不进行元数据筛选的情况下进行搜索。示例包括 metadata_filter={"source": "chat"}（表示标量字段）、metadata_filter={"travel": {"need": "transit"}}（表示嵌套字段）和 metadata_filter={"tags": ["trip", "urgent"]}（表示完全匹配列表）。组合条件以要求所有条件：

    metadata_filter={
        "source": "chat",
        "travel": {"need": "transit"},
        "tags": ["trip", "urgent"],
    }

    要测试数组成员关系，请使用字段级运算符字典。"$array_contains" 匹配一个值或列表中的所有值。"$array_contains_any" 匹配列表中的至少一个值。"$not" 否定同一字段中的另一个字段级表达式，包括运算符字典或原始完全匹配值。如果正表达式失败（包括缺少的字段），则负数表达式匹配；负数数组成员资格也匹配非数组字段：

    metadata_filter={
        "source": "chat",
        "tags": {
            "$array_contains": "trip",
            "$not": {"$array_contains": "archived"},
        },
    }

  • include_invalid_results bool- 上下文卡中是否包括处于无效生命周期状态的相关记录。省略此参数或传递 True 以包含这些参数。传递 False 以将其排除。
  • **kwargs ( Any )- 保留供将来的上下文卡选项使用。意外的关键字参数引发 TypeError。
• 返回：线程的上下文卡对象。
• 返回类型：OracleContextCard

示例

import asyncio
card = asyncio.run(thread.get_context_card_async(
    min_relevant_results_by_type={"preference": 1, "guideline": 1},
))
len(card.relevant_results or []) <= 5
True

method get_message

返回此主题一封邮件。

默认情况下，图像部分将返回其标识符和说明。传递 included_image_ids 以装入所选映像部分的字节数。将忽略不相关的标识符。

• 参数：
  • message_id str- 要检索的消息的标识符。消息必须属于此线程。
  • included_image_ids list[str]- 应装入其字节的附加映像标识符的可选列表。省略此参数或传递 None 以返回映像元数据而不加载字节。
• 返回：请求的消息，包括任何连接的图像部分。
• 返回类型：消息
• 引发：KeyError - 如果消息不存在或属于其他线程。

method get_message_async（异步）

异步返回一条线程拥有的消息。

included_image_ids（可选）选择应装入其字节的附加映像部分；省略或 None 仅返回映像元数据。

• 参数：
  • message_id str- 要检索的消息的标识符。消息必须属于此线程。
  • included_image_ids list[str]- 要水合的附加映像标识符的可选列表。
• 返回：请求的消息，包括任何连接的图像部分。
• 返回类型：消息
• 引发：KeyError - 如果消息不存在或属于其他线程。

method get_messages

返回此主题已存储的消息。

• 参数：
  • start int | None- 启动索引（基于 0）。如果与 end 一起省略，将返回最近的有界窗口。
  • end int | None- 结束索引（不含）。省略时，将返回包含最新消息的有边界窗口。传递 None 或 -1 以显式请求 start 之后的所有消息。
  • include_image_bytes bool- 是否为附加到返回消息的图像部分装入字节。省略此参数，或者传递 False 以返回图像元数据而不加载 BLOB 值。
• 返回：按时间顺序排列的消息。
• 返回类型： list[ Message ]

示例

len(thread.add_messages([{"role": "user", "content": "Stored message example"}]))
1
messages = thread.get_messages()
messages[-1].content
'Stored message example'

method get_messages_async（异步）

以异步方式从 add_messages 添加的线程获取未处理的消息。

• 参数：
  • start int | None- 启动索引（基于 0）。如果与 end 一起省略，将返回最近的有界窗口。
  • end int | None- 结束索引（不含）。省略时，将返回包含最新消息的有边界窗口。传递 None 或 -1 以显式请求 start 之后的所有消息。
  • include_image_bytes bool- 是否为附加到返回消息的图像部分装入字节。省略此参数，或者传递 False 以返回图像元数据而不加载 BLOB 值。
• 返回：按时间顺序排列的消息。
• 返回类型： list[ Message ]

示例

import asyncio
message_ids = asyncio.run(thread.add_messages_async(
    [{"role": "user", "content": "Stored message example"}]
))
len(message_ids)
1
messages = asyncio.run(thread.get_messages_async())
messages[-1].content
'Stored message example'

method get_summary

返回线程的摘要。

全线程请求可重用或刷新持久概要。带有 except_last 的请求在不更改持久的全线程摘要的情况下汇总该前缀。

当 LLM 支持的实现可以执行远程网络 I/O 时，首选 get_summary_async。

• 参数：
  • except_last int- 要从汇总中排除的最新消息数。
  • token_budget int- 软令牌预算。省略时，将应用有界默认值。只有在格式化的汇总超过预算时，正值才会截断。非正值将禁用基于预算的截断；成绩单回退保留上限为 4,000 个字符。
  • **kwargs ( Any )- 保留供将来的摘要选项使用。意外的关键字参数引发 TypeError。
• 返回：包含合成线程摘要文本的摘要对象。
• 返回类型：OracleSummary

示例

len(thread.add_messages([{"role": "assistant", "content": "Summary source message"}]))
1
summary = thread.get_summary()
bool(summary.content)
True

method get_summary_async（异步）

异步返回线程的摘要。

全线程请求可重用或刷新持久概要。带有 except_last 的请求在不更改持久的全线程摘要的情况下汇总该前缀。

• 参数：
  • except_last int- 要从汇总中排除的最新消息数。
  • token_budget int- 软令牌预算。省略时，将应用有界默认值。只有在格式化的汇总超过预算时，正值才会截断。非正值将禁用基于预算的截断；成绩单回退保留上限为 4,000 个字符。
  • **kwargs ( Any )- 保留供将来的摘要选项使用。意外的关键字参数引发 TypeError。
• 返回：包含合成线程摘要文本的摘要对象。
• 返回类型：OracleSummary

method link_records

在此线程拥有的两个记录之间创建定向关系。

目前，两个端点必须是类似内存的记录："memory"、"fact"、"guideline" 或 "preference"。内置关系类型为 "supersedes" ("is_superseded_by")、"contradicts"、"refines" ("is_refined_by")、"supports" ("is_supported_by") 和 "duplicates"。"contradicts" 和 "duplicates" 反向使用相同的标签。

这两个端点必须属于此确切线程。一个端点对只能存储一个方向。opposite_relation_type 在从目标遍历到源时命名关系；例如，new "supersedes" old 在该方向上变为 old "is_superseded_by" new。

• 参数：
  • source_record_id str- 线程拥有的源记录的标识符。
  • source_record_type str- 源记录的逻辑类型。
  • target_record_id str- 线程拥有的目标记录的标识符。
  • target_record_type str- 目标记录的逻辑类型。
  • relation_type str- 源到目标关系标签。
  • opposite_relation_type str- 可选的反向遍历标签。对于内置内存关系类型，省略使用其预定义的反向标签；对于自定义关系类型，省略在两个方向上使用相同的标签。
  • relation_id str- 可选的稳定关系标识符。省略它以生成一个。
  • timestamp str | None- 存储在关系上的可选时间戳。
  • metadata dict[str, Any] | None- 可选的关系元数据。
• 返回：已创建关系的标识符。
• 返回类型： str

示例

thread.link_records(
    "fact-1", "fact", "memory-1", "memory", "supports"
)
'relation-id'

method link_records_async（异步）

异步创建此线程拥有的记录之间的关系。

目前，两个端点必须是类似内存的记录："memory"、"fact"、"guideline" 或 "preference"。内置关系类型为 "supersedes" ("is_superseded_by")、"contradicts"、"refines" ("is_refined_by")、"supports" ("is_supported_by") 和 "duplicates"。"contradicts" 和 "duplicates" 反向使用相同的标签。

• 参数：
  • source_record_id str
  • source_record_type str
  • target_record_id str
  • target_record_type str
  • relation_type str
  • opposite_relation_type str
  • relation_id str
  • timestamp（时间戳）str | None
  • metadata（元数据）dict[str, Any] | None
• 返回类型： str

method list_images

列出此线程拥有的图像记录。

默认情况下，返回的记录包含图像元数据。仅当提供 include_bytes=True 和 image_id 时才装入原始字节。

• 参数：
  • image_id str- 用于过滤映像的可选标识符。省略时，不应用标识符筛选器。
  • metadata_filter dict[str, Any] | None- 应用于映像元数据的可选过滤器。
  • include_bytes bool- 是否装入原始字节。这需要 image_id。
  • limit int | None- 可选的最大记录数。传递 None 以禁用存储的默认限制。
• 返回：按存储顺序匹配图像。
• 返回类型： list[ ImageRecord ]

method list_images_async（异步）

异步列出此线程拥有的映像记录。

默认情况下，返回的记录包含图像元数据。仅当提供 include_bytes=True 和 image_id 时才装入原始字节。此线程的作用域会自动应用。

• 参数：
  • image_id str- 用于过滤映像的可选标识符。省略时，不应用标识符筛选器。
  • metadata_filter dict[str, Any] | None- 应用于映像元数据的可选过滤器。
  • include_bytes bool- 是否装入原始字节。这需要 image_id。
  • limit int | None- 可选的最大记录数。传递 None 以禁用存储的默认限制。
• 返回：按存储顺序匹配图像。
• 返回类型： list[ ImageRecord ]

method search

同步搜索与查询相关的记录。

• 参数：
  • query str- 自然语言查询字符串。
  • user_id str | None- 可选的用户范围覆盖。省略的值将继承线程的默认用户范围。
  • agent_id str | None- 可选代理范围覆盖。省略的值继承线程的缺省代理范围。
  • thread_id str | None- 可选线程范围覆盖。省略的值将继承线程的当前线程标识符。
  • exact_user_match bool- 用户匹配是否应严格。
  • exact_agent_match bool- 代理匹配是否应严格。
  • exact_thread_match bool- 线程匹配是否应严格。
  • max_results int- 返回的最大可选结果数量。提供时，它必须至少为 1。省略此参数时使用缺省值 10。如果存在较少的非失效匹配记录，则调用返回的次数可能少于 max_results。
  • token_budget int- 最终格式化结果的估计令牌计数的可选硬限制。省略时，将使用解析的搜索配置。正值保持完整结果的排名顺序，而其累计估计值符合预算。如果第一个结果不合适，则不返回任何结果。非正值将禁用此输出边界。
  • soft_token_budget int- 用于最终格式化结果的估计标记计数的可选目标。省略时，将使用解析的搜索配置。将保留达到或超过此目标的完整结果。非正值将禁用此目标。当输出还必须具有绝对限制时，将 token_budget 设置为更大的值。
  • record_types list[str]- 要包括的记录类型的可选列表，例如 "memory"、"message" 或 "image"。

  • metadata_filter dict[str, Any] | None-

    在范围和记录类型筛选之后用作附加筛选器的可选元数据筛选器映射。metadata_filter 中的条目与 AND 语义组合。值不是字段级运算符字典的条目使用完全匹配语义：所请求的关键字必须存在于存储的记录元数据中。嵌套字典以递归方式匹配嵌套元数据对象。标量和列表值必须完全匹配；列表顺序和长度也必须匹配。省略此参数或传递 None 以在不进行元数据筛选的情况下进行搜索。示例包括 metadata_filter={"source": "chat"}（表示标量字段）、metadata_filter={"travel": {"need": "transit"}}（表示嵌套字段）和 metadata_filter={"tags": ["trip", "urgent"]}（表示完全匹配列表）。组合条件以要求所有条件：

    metadata_filter={
        "source": "chat",
        "travel": {"need": "transit"},
        "tags": ["trip", "urgent"],
    }

    要测试数组成员关系，请使用字段级运算符字典。"$array_contains" 匹配一个值或列表中的所有值。"$array_contains_any" 匹配列表中的至少一个值。"$not" 否定同一字段中的另一个字段级表达式，包括运算符字典或原始完全匹配值。如果正表达式失败（包括缺少的字段），则负数表达式匹配；负数数组成员资格也匹配非数组字段：

    metadata_filter={
        "source": "chat",
        "tags": {
            "$array_contains": "trip",
            "$not": {"$array_contains": "archived"},
        },
    }

  • include_invalid_results bool- 结果是否包括处于无效状态的记录。省略此参数或传递 True 以包含这些参数。传递 False 以将其排除。
  • num_hops int- 从每个直接内存结果跟踪的内存链路边缘数。支持从 0 到 5 的值；仅省略直接结果。将保留直接消息、图像和配置文件结果，但不会以图形展开。
  • max_linked_results int- 附加到每个直接结果的所有跃点的最大链接内存。忽略 100 的缺省值；传递 0 以不返回链接的上下文。
  • scope SearchScope- 可选的预生成搜索范围。请提供 scope 或显式标识符和完全匹配参数，而不是两者。
• 退货：按相关性降低排序的搜索结果。
• 返回类型： list[SearchResult]
• 引发：ValueError - 如果 scope 与显式标识符或精确匹配参数组合，如果 max_results 小于 1，或者如果 metadata_filter 不是字典或 None。

注释

省略的范围字段继承此线程的默认搜索范围：精确的用户和代理匹配加上此线程的当前 user_id、agent_id 和 thread_id。默认线程搜索有意离开 exact_thread_match=False，因此它可能会从同一用户/代理的其他线程返回相关记录。传递 exact_thread_match=True 以将结果限制为当前线程。显式 None 范围值仍遵循已解析的确切匹配规则：exact_*_match=False 保持该维不受约束，而 exact_*_match=True 仅匹配存储的 None 值。

显式 max_results 值必须至少为 1；省略该参数时使用默认值 10。这是上限：当筛选器限制性太强、存在较少的匹配记录或由于特定于实施的搜索行为时，调用返回的结果可能会少于 max_results。

method search_async（异步）

异步搜索与查询相关的记录。

• 参数：
  • query str- 自然语言查询字符串。
  • user_id str | None- 可选的用户范围覆盖。省略的值将继承线程的默认用户范围。
  • agent_id str | None- 可选代理范围覆盖。省略的值继承线程的缺省代理范围。
  • thread_id str | None- 可选线程范围覆盖。省略的值将继承线程的当前线程标识符。
  • exact_user_match bool- 用户匹配是否应严格。
  • exact_agent_match bool- 代理匹配是否应严格。
  • exact_thread_match bool- 线程匹配是否应严格。
  • max_results int- 返回的最大可选结果数量。提供时，它必须至少为 1。省略此参数时使用缺省值 10。
  • token_budget int- 最终格式化结果的估计令牌计数的可选硬限制。省略时，将使用解析的搜索配置。正值保持完整结果的排名顺序，而其累计估计值符合预算。如果第一个结果不合适，则不返回任何结果。非正值将禁用此输出边界。
  • soft_token_budget int- 用于最终格式化结果的估计标记计数的可选目标。省略时，将使用解析的搜索配置。将保留达到或超过此目标的完整结果。非正值将禁用此目标。当输出还必须具有绝对限制时，将 token_budget 设置为更大的值。
  • record_types list[str]- 要包括的记录类型的可选列表，例如 "memory"、"message" 或 "image"。

  • metadata_filter dict[str, Any] | None-

    在范围和记录类型筛选之后用作附加筛选器的可选元数据筛选器映射。metadata_filter 中的条目与 AND 语义组合。值不是字段级运算符字典的条目使用完全匹配语义：所请求的关键字必须存在于存储的记录元数据中。嵌套字典以递归方式匹配嵌套元数据对象。标量和列表值必须完全匹配；列表顺序和长度也必须匹配。省略此参数或传递 None 以在不进行元数据筛选的情况下进行搜索。示例包括 metadata_filter={"source": "chat"}（表示标量字段）、metadata_filter={"travel": {"need": "transit"}}（表示嵌套字段）和 metadata_filter={"tags": ["trip", "urgent"]}（表示完全匹配列表）。组合条件以要求所有条件：

    metadata_filter={
        "source": "chat",
        "travel": {"need": "transit"},
        "tags": ["trip", "urgent"],
    }

    要测试数组成员关系，请使用字段级运算符字典。"$array_contains" 匹配一个值或列表中的所有值。"$array_contains_any" 匹配列表中的至少一个值。"$not" 否定同一字段中的另一个字段级表达式，包括运算符字典或原始完全匹配值。如果正表达式失败（包括缺少的字段），则负数表达式匹配；负数数组成员资格也匹配非数组字段：

    metadata_filter={
        "source": "chat",
        "tags": {
            "$array_contains": "trip",
            "$not": {"$array_contains": "archived"},
        },
    }

  • include_invalid_results bool- 结果是否包括处于无效状态的记录。省略此参数或传递 True 以包含这些参数。传递 False 以将其排除。
  • num_hops int- 从每个直接内存结果跟踪的内存链路边缘数。支持从 0 到 5 的值；仅省略直接结果。将保留直接消息、图像和配置文件结果，但不会以图形展开。
  • max_linked_results int- 附加到每个直接结果的所有跃点的最大链接内存。忽略 100 的缺省值；传递 0 以不返回链接的上下文。
  • scope SearchScope- 可选的预生成搜索范围。请提供 scope 或显式标识符和完全匹配参数，而不是两者。
• 退货：按相关性降低排序的搜索结果。
• 返回类型： list[SearchResult]
• 引发：ValueError - 如果 scope 与显式标识符或精确匹配参数组合，如果 max_results 小于 1，或者如果 metadata_filter 不是字典或 None。

注释

省略的范围字段继承此线程的默认搜索范围：精确的用户和代理匹配加上此线程的当前 user_id、agent_id 和 thread_id。默认线程搜索有意离开 exact_thread_match=False，因此它可能会从同一用户/代理的其他线程返回相关记录。传递 exact_thread_match=True 以将结果限制为当前线程。显式 None 范围值仍遵循已解析的确切匹配规则：exact_*_match=False 保持该维不受约束，而 exact_*_match=True 仅匹配存储的 None 值。

显式 max_results 值必须至少为 1；省略该参数时使用默认值 10。这是上限：当筛选器限制性太强、存在较少的匹配记录或由于特定于实施的搜索行为时，调用返回的结果可能会少于 max_results。

method update_image

更新此线程拥有的一个图像。

省略 image 以保留现有字节。如果提供了 image，则必须随其提供 mime_type。省略 description 以保留现有说明。传递 None 以使用配置的 LLM 生成新说明；非空说明会直接替换该说明。附加到消息的图像的到期必须通过 update_message() 进行更改。

• 返回：更新的图像标识符。
• 返回类型： str
• 引发：ValueError - 如果为附加到消息的图像提供了到期设置。
• 参数：
  • image_id str
  • image（图像）bytes
  • description（说明）str | None
  • mime_type ImageMimeType
  • metadata（元数据）dict[str, Any] | None
  • timestamp（时间戳）str | None
  • ttl_days int | None
  • ttl_anchor TimeToLiveAnchor
  • kwargs Any

method update_image_async（异步）

异步更新此线程拥有的一个映像。

省略 image 以保留现有字节。如果提供了 image，则必须随其提供 mime_type。省略 description 以保留现有说明。传递 None 以使用配置的 LLM 生成新说明；非空说明会直接替换该说明。元数据、时间戳和到期设置在提供时会更新。附加到消息的图像的到期必须通过 update_message_async() 进行更改。

• 返回：更新的图像标识符。
• 返回类型： str
• 引发：ValueError - 如果为附加到消息的图像提供了到期设置。
• 参数：
  • image_id str
  • image（图像）bytes
  • description（说明）str | None
  • mime_type ImageMimeType
  • metadata（元数据）dict[str, Any] | None
  • timestamp（时间戳）str | None
  • ttl_days int | None
  • ttl_anchor TimeToLiveAnchor
  • kwargs Any

method update_memory

更新此确切线程拥有的类似内存的记录。

• 参数：
  • memory_id str- 内存标识符。仅更新存储的 thread_id 与此线程完全匹配的类似内存的记录（memory、guideline、fact、preference）。
  • content str- 可选替换内容。提供一个字符串以替换存储的内容。如果省略，将保留存储的内容。省略 content 以保留当前值，或者使用 delete_memory() 删除记录。
  • metadata dict[str, Any] | None- 可选的替换元数据映射。省略时，将保留存储的元数据。如果提供，它将替换存储的元数据对象；此 API 不深入合并元数据。
  • timestamp str | None- 此内存的可选新时间戳。它表示创建内存的时间。省略时，将保留存储的时间戳。传递 None 以清除保存的时间戳并使用在存储中创建记录的时间。当 ttl_anchor 为 TimeToLiveAnchor.TIMESTAMP 时，替换时间戳必须是 ISO-8601 字符串。没有时区的 ISO-8601 时间戳将视为 UTC。
  • ttl_days int | None – Optional expiration refresh in days. Omit this argument to leave the current expiration unchanged unless ttl_anchor is provided. Pass None to use MemoryRetentionConfig.max_ttl_days when the retention configuration sets one, or to clear expiration when it does not. Values above MemoryRetentionConfig.max_ttl_days are clamped to that maximum with a warning. Expired memories are unavailable to this thread API and cannot be refreshed.
  • ttl_anchor TimeToLiveAnchor- 用于到期刷新的可选生存时间锚。将 TimeToLiveAnchor.CREATED_AT 用于内存创建时间，将 TimeToLiveAnchor.TIMESTAMP 用于在同一更新中提供的替换 timestamp，或者在省略 timestamp 时使用存储的事件时间戳。提供不带 ttl_days 的 ttl_anchor 将使用方案默认生存时间持续时间。在刷新期间省略 ttl_anchor 时，线程将使用 TimeToLiveAnchor.CREATED_AT。时间戳锚定刷新需要同一调用中的替换 ISO-8601 时间戳，或者需要采用该格式的现有存储事件时间戳。没有时区的 ISO-8601 时间戳将视为 UTC。
  • status RecordStatus- 此类似内存记录的可选替换生命周期状态。省略它以保留当前状态。
  • **kwargs ( Any )- 意外关键字参数将被拒绝。
• 返回：更新的类似内存的记录标识符。
• 返回类型： str

method update_memory_async（异步）

异步更新此确切线程拥有的类似内存的记录。

• 参数：
  • memory_id str- 内存标识符。仅更新存储的 thread_id 与此线程完全匹配的类似内存的记录（memory、guideline、fact、preference）。
  • content str- 可选替换内容。提供一个字符串以替换存储的内容。如果省略，将保留存储的内容。省略 content 以保留当前值，或者使用 delete_memory() 删除记录。
  • metadata dict[str, Any] | None- 可选的替换元数据映射。省略时，将保留存储的元数据。如果提供，它将替换存储的元数据对象；此 API 不深入合并元数据。
  • timestamp str | None- 此内存的可选新时间戳。它表示创建内存的时间。省略时，将保留存储的时间戳。传递 None 以清除保存的时间戳并使用在存储中创建记录的时间。当 ttl_anchor 为 TimeToLiveAnchor.TIMESTAMP 时，替换时间戳必须是 ISO-8601 字符串。没有时区的 ISO-8601 时间戳将视为 UTC。
  • ttl_days int | None – Optional expiration refresh in days. Omit this argument to leave the current expiration unchanged unless ttl_anchor is provided. Pass None to use MemoryRetentionConfig.max_ttl_days when the retention configuration sets one, or to clear expiration when it does not. Values above MemoryRetentionConfig.max_ttl_days are clamped to that maximum with a warning. Expired memories are unavailable to this thread API and cannot be refreshed.
  • ttl_anchor TimeToLiveAnchor- 用于到期刷新的可选生存时间锚。将 TimeToLiveAnchor.CREATED_AT 用于内存创建时间，将 TimeToLiveAnchor.TIMESTAMP 用于在同一更新中提供的替换 timestamp，或者在省略 timestamp 时使用存储的事件时间戳。提供不带 ttl_days 的 ttl_anchor 将使用方案默认生存时间持续时间。在刷新期间省略 ttl_anchor 时，线程将使用 TimeToLiveAnchor.CREATED_AT。时间戳锚定刷新需要同一调用中的替换 ISO-8601 时间戳，或者需要采用该格式的现有存储事件时间戳。没有时区的 ISO-8601 时间戳将视为 UTC。
  • status RecordStatus- 此类似内存记录的可选替换生命周期状态。省略它以保留当前状态。
  • **kwargs ( Any )- 意外关键字参数将被拒绝。
• 返回：更新的类似内存的记录标识符。
• 返回类型： str

示例

import asyncio
memory_id = asyncio.run(thread.add_memory_async("Original memory"))
(
    asyncio.run(thread.update_memory_async(
        memory_id, content="Updated memory"
    ))
    == memory_id
)
True

method update_message

更新此确切线程拥有的原始消息记录。

• 参数：
  • message_id str- 消息标识符。仅更新其存储的 thread_id 与此线程完全匹配的消息。
  • content str | list[Mapping[str, Any]]- 可选替换消息内容。提供字符串以替换存储的内容，或按顺序排列的文本和图像内容部分。如果省略，将保留存储的内容。使用空字符串将其替换为空文本内容。
  • metadata dict[str, Any] | None- 可选的替换元数据映射。省略时，将保留存储的元数据。如果提供，它将替换存储的元数据对象；此 API 不深入合并元数据。
  • ttl_days int | None – Optional expiration refresh in days. Omit this argument to leave the current expiration unchanged unless ttl_anchor is provided. Pass None to use MemoryRetentionConfig.max_ttl_days when the retention configuration sets one, or to clear expiration when it does not. Values above MemoryRetentionConfig.max_ttl_days are clamped to that maximum with a warning. Expired messages are unavailable to this thread API and cannot be refreshed.
  • ttl_anchor TimeToLiveAnchor- 用于到期刷新的可选生存时间锚。将 TimeToLiveAnchor.CREATED_AT 用于消息创建时间，将 TimeToLiveAnchor.TIMESTAMP 用于存储的事件时间戳。提供不带 ttl_days 的 ttl_anchor 将使用方案默认生存时间持续时间。在刷新期间省略 ttl_anchor 时，线程将使用 TimeToLiveAnchor.CREATED_AT。时间戳锚定刷新需要现有存储的 ISO-8601 消息时间戳。没有时区的 ISO-8601 时间戳将视为 UTC。
  • **kwargs ( Any )- 意外关键字参数将被拒绝。
• 退货：更新的消息记录的标识符。
• 返回类型： str

注释

省略的字段将从存储的记录中保留。存储的角色和时间戳保持不变。编辑内容将更新原始消息历史记录，并且启用自动提取时，可能会导致 SDK 从已编辑消息和早期历史记录中重新提取内存。在 INLINE 模式下，该提取将在此方法返回之前完成。在 BACKGROUND 模式下，此方法将在原始消息更新成功并尝试后台提取后返回。此后续工作不会影响后续 add_messages() 调用使用的正常提取频率。现有提取的记忆仍然存在，而从编辑的内容中新提取的记忆可以添加。由于原始消息更新和任何以后的提取内存写入不会以原子方式发生，因此如果后台工作不排队，如果配置的队列容量等待达到其超时，或者稍后提取工作失败，则提取的内存仍可以反映较早的消息内容。此外，请注意，当源消息的 TTL 更改时，现有提取的内存会保留其原始到期时间。

示例

message_id = thread.add_messages([{"role": "user", "content": "Draft message"}])[0]
thread.update_message(message_id, content="Edited message") == message_id
True

method update_message_async（异步）

异步更新此确切线程拥有的原始消息记录。

• 参数：
  • message_id str- 消息标识符。仅更新其存储的 thread_id 与此线程完全匹配的消息。
  • content str | list[Mapping[str, Any]]- 可选替换消息内容。提供字符串以替换存储的内容，或按顺序排列的文本和图像内容部分。如果省略，将保留存储的内容。使用空字符串将其替换为空文本内容。
  • metadata dict[str, Any] | None- 可选的替换元数据映射。省略时，将保留存储的元数据。如果提供，它将替换存储的元数据对象；此 API 不深入合并元数据。
  • ttl_days int | None – Optional expiration refresh in days. Omit this argument to leave the current expiration unchanged unless ttl_anchor is provided. Pass None to use MemoryRetentionConfig.max_ttl_days when the retention configuration sets one, or to clear expiration when it does not. Values above MemoryRetentionConfig.max_ttl_days are clamped to that maximum with a warning. Expired messages are unavailable to this thread API and cannot be refreshed.
  • ttl_anchor TimeToLiveAnchor- 用于到期刷新的可选生存时间锚。将 TimeToLiveAnchor.CREATED_AT 用于消息创建时间，将 TimeToLiveAnchor.TIMESTAMP 用于存储的事件时间戳。提供不带 ttl_days 的 ttl_anchor 将使用方案默认生存时间持续时间。时间戳锚定刷新需要现有存储的 ISO-8601 消息时间戳。没有时区的 ISO-8601 时间戳将视为 UTC。
  • **kwargs ( Any )- 意外关键字参数将被拒绝。
• 退货：更新的消息记录的标识符。
• 返回类型： str

注释

省略的字段将从存储的记录中保留。存储的角色和时间戳保持不变。编辑内容将更新原始消息历史记录，并且启用自动提取时，可能会导致 SDK 从已编辑消息和早期历史记录中重新提取内存。在 INLINE 模式下，该提取将在此方法返回之前完成。在 BACKGROUND 模式下，此方法将在原始消息更新成功并尝试后台提取后返回。此后续工作不会影响后续 add_messages() 调用使用的正常提取频率。现有提取的记忆仍然存在，而从编辑的内容中新提取的记忆可以添加。由于原始消息更新和任何以后的提取内存写入不会以原子方式发生，因此如果后台工作不排队，如果配置的队列容量等待达到其超时，或者稍后提取工作失败，则提取的内存仍可以反映较早的消息内容。此外，请注意，当源消息的 TTL 更改时，现有提取的内存会保留其原始到期时间。

示例

import asyncio
message_ids = asyncio.run(thread.add_messages_async(
    [{"role": "user", "content": "Draft message"}]
))
(
    asyncio.run(thread.update_message_async(
        message_ids[0], content="Edited message"
    ))
    == message_ids[0]
)
True

method update_record_link

更新其端点归此线程所有的关系。

省略的值会保留。当 relation_type 更改为内置内存关系类型时，其固定反向标签将替换 opposite_relation_type。

• 参数：
  • relation_id str- 线程拥有的关系的标识符。
  • relation_type str- 可选替换源到目标标签。
  • opposite_relation_type str- 可选替换反向遍历标签。省略它以保留存储的标签。
  • timestamp str | None- 可选替换时间戳。传递 None 以将其清除。
  • metadata dict[str, Any] | None- 可选的替换元数据。它将替换存储的对象。
• 返回：0 或 1 的已更新关系数。
• 返回类型： int

示例

thread.update_record_link("relation-id", relation_type="supports")
1

method update_record_link_async（异步）

异步更新其端点属于此线程的关系。

• 参数：
  • relation_id str
  • relation_type str
  • opposite_relation_type str
  • timestamp（时间戳）str | None
  • metadata（元数据）dict[str, Any] | None
• 返回类型： int

method wait_for_memory_extraction

等待此线程的早期后台内存提取。

此方法等待由早期的 add_messages()、add_messages_async()、update_message() 或 update_message_async() 调用在此线程上通过同一代理内存组件启动的后台提取。如果其中一个调用已在完成，则此方法包括在等待之前启动的提取。

此等待开始后启动的提取、其他代理内存组件启动的提取，或者在另一个进程中运行的提取，方法不会等待提取。此等待的提取失败计数为已完成。

• 参数：timeout float | None- 可选的最大等待秒数。默认为 300。传递 None 以等待此线程的暂挂提取完成。
• 引发：TimeoutError - 在较早的后台提取完成之前超时到期时引发。
• 返回类型：无

示例

thread.wait_for_memory_extraction(timeout=10)

method wait_for_memory_extraction_async（异步）

异步等待更早的后台内存提取。

此方法遵循与 wait_for_memory_extraction() 相同的行为。

• 参数：timeout float | None- 可选的最大等待秒数。默认为 300。传递 None 以无限期等待。
• 引发：TimeoutError - 在较早的后台提取完成之前超时到期时引发。
• 返回类型：无

示例

import asyncio
asyncio.run(thread.wait_for_memory_extraction_async(timeout=10))

注：delete_message() 仅删除原始消息行。派生的记忆可能仍然可以搜索或显示在上下文卡中。使用 OracleAgentMemory.delete_thread() 可删除线程及其关联的消息和记忆。通过线程句柄删除消息和内存将等待已由该线程的附加客户机接受的早期后台提取。对于等待开始后接受的其他客户端实例、进程或工作，这不是全局并发屏障。

消息和消息内容

class oracleagentmemory.apis.message.Message

基准：object

线程和 LLM 适配器共享的内存中消息。

• 参数：
  • role str- 消息角色。线程消息允许使用定制角色名称。
  • content str | collections.abc.Sequence[oracleagentmemory.apis.message.MessageContent]-TextContent 和 ImageContent 部分的消息文本或有序序列。内容序列不能为空，并且存储为不可变元组。
  • timestamp str | None- 与消息关联的可选时间戳。
  • metadata dict[str, Any] | None- 与消息关联的可选与 JSON 兼容的元数据。
  • id str | None- 可选的稳定消息标识符。当添加消息时，存储会生成一个没有标识符的消息。

class oracleagentmemory.apis.message.MessageContent

基础：ABC

结构化消息内容的基类。

• 参数：
  • id str- 此内容部分的稳定标识符。省略时自动生成。
  • timestamp str | None- 与此内容部分关联的可选时间戳。

class oracleagentmemory.apis.message.TextContent

基础：MessageContent

多模式消息中的文本部分。

• 参数：
  • text str- 此内容部分携带的文本。
  • id str- 从 MessageContent 继承的稳定标识符。省略时自动生成。
  • timestamp str | None- 从 MessageContent 继承的可选时间戳。

class oracleagentmemory.apis.message.ImageContent

基础：MessageContent

多模式消息中的图像部分。

• 参数：
  • bytes bytes | None- 映像数据（如果可用）。当消息包含图像元数据而不加载图像字节时，允许使用 None。
  • mime_type oracleagentmemory.apis.message.ImageMimeType- 映像 MIME 类型。
  • description str | None- 描述图像的可选文本。None 时，高级映像和消息 API 可能会使用配置的 LLM 生成说明。
  • id str- 从 MessageContent 继承的稳定标识符。省略时自动生成。
  • timestamp str | None- 从 MessageContent 继承的可选时间戳。

class oracleagentmemory.apis.message.ImageMimeType

基础：str、Enum

图像内容支持的 MIME 类型。

不支持动画 PNG 和 WebP。

JPEG = ‘ image/JPEG ’

PNG = ‘ image/PNG ’

WEBP = ‘ image/WEBP ’

上下文卡

class oracleagentmemory.apis.contextcard.ContextCard

基础：ABC

抽象线程 API 返回的上下文卡对象。

property content（抽象）

• 返回类型： str
• 说明：返回呈现的上下文卡文本。

class oracleagentmemory.core.contextcard.OracleContextCard

基础：ContextCard

Oracle 线程返回的上下文卡。

• 参数：
  • summary str- 卡中嵌入的摘要文本。
  • 主题 Sequence[str] | None- 与线程关联的可选检索主题。
  • relevant_results Sequence[SearchResult] | None- 卡中包括的可选检索持久记录。
  • recent_messages Sequence[Message] | None- 最近呈现到卡中的可选原始消息。
  • message_format str- 呈现 recent_messages 时使用的内部模板。

property（属性）content

• 返回类型： str

• 说明：返回呈现的上下文卡文本。

• 返回：类似 XML 的呈现上下文卡文本，适用于提示汇编。
• 返回类型： str

示例

card = OracleContextCard(summary="ctx")
"<summary>" in card.content and "ctx" in card.content
True

property（属性）formatted_content

• 返回类型： str

• 说明：返回提示构建流中使用的呈现的上下文卡文本。

• 返回：类似 XML 的呈现上下文卡文本。
• 返回类型： str

示例

OracleContextCard(summary="").formatted_content
''
card = OracleContextCard(summary="ctx", topics=["travel"])
"<topics>" in card.formatted_content
True

概要

class oracleagentmemory.apis.summary.Summary

基础：ABC

抽象线程 API 返回的线程概要对象。

property content（抽象）

• 返回类型： str
• 说明：返回综合的汇总文本。

class oracleagentmemory.core.summary.OracleSummary

基础：Summary

Oracle 线程返回的概要。

• 参数：content str- 从线程记录中合成的总结文本。

示例

summary = OracleSummary(content="Plan the Rome itinerary.")
summary.content
'Plan the Rome itinerary.'
str(summary)
'Plan the Rome itinerary.'

property（属性）content

• 返回类型： str

• 说明：返回综合的汇总文本。

• 返回：线程的摘要文本。
• 返回类型： str

示例

OracleSummary(content="Keep the tea preference in mind.").content
'Keep the tea preference in mind.'

property（属性）formatted_content

• 返回类型： str

• 说明：返回在提示构建流中使用的呈现的摘要文本。

• 返回：呈现的摘要文本。
• 返回类型： str

示例

OracleSummary(content="Thread recap").formatted_content
'Thread recap'