线程

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

Oracle 线程

class `oracleagentmemory.core.OracleThread`

基础：IThread

由 Oracle 存储支持的线程。

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

注

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

创建新的 OracleThread 实例。

参数：
- store OracleMemoryStore- 用于保存嵌入式记录的共享存储后端。
- thread_id str- 线程标识符。如果未提供，将生成 UUID。
- user_id str- 与线程关联的用户标识符。如果省略，将生成 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 默认值，并保持启用上下文摘要。
- 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-
  
  应在此之后更新提取上下文摘要的消息数。设置为 -1 以使用新添加的完整消息批对每个 add_messages 调用仅汇总一次。默认值为 -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 时，汇总将根据 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。
- client（客户机）OracleAgentMemory | None

示例

from oracleagentmemory.core import OracleAgentMemory
import oracledb
db_pool = oracledb.SessionPool(
    user="YOUR DB USER",
    password="YOUR DB PASSWORD",
    dsn="YOUR DB CONNECT STRING",
)
client = OracleAgentMemory(connection=db_pool, embedder=embedder)
thread = client.create_thread(
    thread_id="c1",
    llm=llm,
    memory_extraction_config=MemoryExtractionConfig(enable_context_summary=True),
)
len(thread.add_messages([{"role": "user", "content": "I love pizza."}]))
1

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 时，存储将使用当前时间。当 ttl_anchor 为 TimeToLiveAnchor.TIMESTAMP 时，提供具体的 ISO-8601 时间戳值。没有时区的 ISO-8601 时间戳将视为 UTC。
- ttl_days int | None- 可选的生存时间持续时间（天）。省略此参数以使用模式默认的生存时间持续时间。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. MemoryRetentionConfig.max_ttl_days 以上的值将夹到该最大值并显示警告。
- ttl_anchor TimeToLiveAnchor- 可选的生存时间锚。使用 TimeToLiveAnchor.CREATED_AT 表示数据库创建时间，使用 TimeToLiveAnchor.TIMESTAMP 表示内存时间戳。时间戳锚定到期需要此内存的具体 ISO-8601 时间戳。没有时区的 ISO-8601 时间戳将视为 UTC。
- **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- 可选的调用方提供的内存标识符。如果省略，门店将生成 ID。
- metadata dict[str, Any] | None- 可与存储的内存一起保留的可选元数据。
- timestamp str | None- 用于保存此内存的可选时间戳。它表示创建内存的时间。省略或 None 时，存储将使用当前时间。
- ttl_days int | None- 可选的生存时间持续时间（天）。省略此参数以使用模式默认的生存时间，或者为未过期的内存传递 None。
- ttl_anchor TimeToLiveAnchor- 可选的生存时间锚。使用 TimeToLiveAnchor.CREATED_AT 或 TimeToLiveAnchor.TIMESTAMP。
- **store_kwargs ( Any )- 特定于实施的写入选项，转发到后备存储。
返回类型： str

method `add_messages`

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

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

参数：
- messages list[Message | MessageT]- 要附加的消息列表。消息可以是 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`（异步）

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

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

参数：
- messages（消息）list[Message | MessageT]
- 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_memory`

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

参数：memory_id str- 内存标识符。仅删除存储的 thread_id 与此线程完全匹配的类似内存的记录（memory、guideline、fact、preference）。
返回：已删除的记录数（0 或 1）。当标识符不存在或属于其他线程时，返回 0。
返回类型： int

示例

thread.delete_memory("456")
0

method `delete_message`

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

参数：message_id str- 消息标识符。仅删除其存储的 thread_id 与此线程完全匹配的消息。
退货：已删除的消息记录数（0 或 1）。当标识符不存在或属于其他线程时，返回 0。
返回类型： int

注

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

示例

thread.delete_message("123")
0

method `get_context_card`

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

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

参数：
- fallback_message_count int- 派生用于检索和呈现的回退摘要文本时要使用的最近消息数。如果省略，则将解析为 5。
- max_relevant_results int- 检索到的最大持久记录数。如果省略，除非提供 min_relevant_results_by_type，否则将解析为 5；在这种情况下，将解析为 5 的较大值和请求的每类型最小值的总和。
- max_recent_messages int- 要逐字嵌入的尾随原始消息的最大数量。如果省略，则将解析为 5。
- min_relevant_results_by_type Mapping[Literal['memory', 'guideline', 'fact', 'preference'], int] | None | ~oracleagentmemory._notset._NotSetMarker- 上下文卡中包含的相关类似内存记录的每类型可选最小值。首先搜索请求的类型，其余的 max_relevant_results 插槽将填充所有支持的类似内存的记录类型。支持的密钥包括 "memory"、"fact"、"guideline" 和 "preference"。
- **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- 检索到的最大持久记录数。如果省略，除非提供 min_relevant_results_by_type，否则将解析为 5；在这种情况下，将解析为 5 的较大值和请求的每类型最小值的总和。
- max_recent_messages int- 要逐字嵌入的尾随原始消息的最大数量。如果省略，则将解析为 5。
- min_relevant_results_by_type Mapping[Literal['memory', 'guideline', 'fact', 'preference'], int] | None | ~oracleagentmemory._notset._NotSetMarker- 上下文卡中包含的相关类似内存记录的每类型可选最小值。首先搜索请求的类型，其余的 max_relevant_results 插槽将填充所有支持的类似内存的记录类型。支持的密钥包括 "memory"、"fact"、"guideline" 和 "preference"。
- **kwargs ( Any )- 保留供将来的上下文卡选项使用。意外的关键字参数引发 TypeError。
返回：线程的上下文卡对象。
返回类型：OracleContextCard

示例

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

method `get_messages`

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

参数：
- start int | None- 启动索引（基于 0）。如果与 end 一起省略，将返回最近的有界窗口。
- end int | None- 结束索引（不含）。省略时，将返回包含最新消息的有边界窗口。传递 None 或 -1 以显式请求 start 之后的所有消息。
返回：按时间顺序排列的消息。
返回类型： 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`（异步）

异步返回原始线程消息。

参数：
- start int | None- 可选的开始索引。
- end int | None- 可选结束索引。
返回：原始消息对象。
返回类型： list[ Message ]

method `get_summary`

返回线程的最佳工作摘要。

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

参数：
- except_last int- 要从汇总中排除的最新消息数。
- token_budget int- 软令牌预算。省略时，将应用有界默认值。正值仅在格式化的摘要超过由 _estimate_tokens() 估计的预算时截断；然后返回的文本将限制为 int(token_budget * 3.5) 个字符。非正值将禁用输出边界。
- **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 int- 要从汇总中排除的最新消息数。
- token_budget int- 软令牌预算。省略时，将应用有界默认值。正值仅在格式化的摘要超过由 _estimate_tokens() 估计的预算时截断；然后返回的文本将限制为 int(token_budget * 3.5) 个字符。非正值将禁用输出边界。
- **kwargs ( Any )- 保留供将来的摘要选项使用。意外的关键字参数引发 TypeError。
返回：包含合成线程摘要文本的摘要对象。
返回类型：OracleSummary

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。
- record_types list[str]- 要包括的记录类型的可选列表，例如 "memory" 或 "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"},
    },
}
```
- 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。
- record_types list[str]- 要包括的记录类型的可选列表，例如 "memory" 或 "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"},
    },
}
```
- scope SearchScope- 可选的预生成搜索范围。请提供 scope 或显式标识符和完全匹配参数，而不是两者。
退货：按相关性降低排序的搜索结果。
返回类型： list[SearchResult]
引发：ValueError - 如果 scope 与显式标识符或精确匹配参数组合，如果 max_results 小于 1，或者如果 metadata_filter 不是字典或 None。

注

method `update_memory`

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

参数：
- memory_id str- 内存标识符。仅更新存储的 thread_id 与此线程完全匹配的类似内存的记录（memory、guideline、fact、preference）。
- content str- 可选替换内容。提供一个字符串以替换存储的内容。如果省略，将保留存储的内容。不支持传递 None；省略 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- 可选的到期刷新（天）。除非提供 ttl_anchor，否则省略此参数以保持当前失效不变。Pass None to use MemoryRetentionConfig.max_ttl_days when the retention configuration sets one, or to clear expiration when it does not. MemoryRetentionConfig.max_ttl_days 以上的值将夹到该最大值并显示警告。过期的内存对此线程 API 不可用，无法刷新。
- ttl_anchor TimeToLiveAnchor- 用于到期刷新的可选生存时间锚。将 TimeToLiveAnchor.CREATED_AT 用于内存创建时间，将 TimeToLiveAnchor.TIMESTAMP 用于在同一更新中提供的替换 timestamp，或者在省略 timestamp 时使用存储的事件时间戳。提供不带 ttl_days 的 ttl_anchor 将使用方案默认生存时间持续时间。在刷新期间省略 ttl_anchor 时，线程将使用 TimeToLiveAnchor.CREATED_AT。时间戳锚定刷新需要同一调用中的替换 ISO-8601 时间戳，或者需要采用该格式的现有存储事件时间戳。没有时区的 ISO-8601 时间戳将视为 UTC。
- **kwargs ( Any )- 意外关键字参数将被拒绝。
返回：更新的类似内存的记录标识符。
返回类型： str

method `update_memory_async`（异步）

异步更新类似内存的记录。

参数：
- memory_id str- 要更新的类似内存的记录标识符。
- content str- 可选替换内容。提供一个字符串以替换存储的内容。如果省略，将保留存储的内容。不支持传递 None；省略 content 以保留当前值，或者使用 delete_memory() 删除记录。
- metadata dict[str, Any] | None- 可选的替换元数据映射。省略时，将保留存储的元数据。如果提供，它将替换存储的元数据对象；此 API 不深入合并元数据。
- timestamp str | None- 此内存的可选新时间戳。它表示创建内存的时间。省略时，将保留存储的时间戳。传递 None 以清除保存的时间戳并使用在存储中创建记录的时间。
- ttl_days int | None- 可选的到期刷新（天）。将此参数与 ttl_anchor 一起省略，以保留当前的失效时间戳。传递 None 以清除到期。
- ttl_anchor TimeToLiveAnchor- 用于到期刷新的可选生存时间锚。提供不带 ttl_days 的 ttl_anchor 将使用方案默认生存时间持续时间。
- **kwargs ( Any )- 意外关键字参数将被拒绝。
返回：更新的类似内存的记录标识符。
返回类型： str

示例

from functools import partial
from oracleagentmemory._async_helpers import run_async_in_sync
memory_id = thread.add_memory("Original memory")
run_async_in_sync(
    partial(thread.update_memory_async, memory_id, content="Updated memory")
) == memory_id
True

method `update_message`

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

参数：
- message_id str- 消息标识符。仅更新其存储的 thread_id 与此线程完全匹配的消息。
- content str- 可选替换消息内容。提供一个字符串以替换存储的内容。如果省略，将保留存储的内容。不支持传递 None。
- metadata dict[str, Any] | None- 可选的替换元数据映射。省略时，将保留存储的元数据。如果提供，它将替换存储的元数据对象；此 API 不深入合并元数据。
- ttl_days int | None- 可选的到期刷新（天）。除非提供 ttl_anchor，否则省略此参数以保持当前失效不变。Pass None to use MemoryRetentionConfig.max_ttl_days when the retention configuration sets one, or to clear expiration when it does not. MemoryRetentionConfig.max_ttl_days 以上的值将夹到该最大值并显示警告。过期消息对此线程 API 不可用，无法刷新。
- 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- 可选替换消息内容。提供一个字符串以替换存储的内容。如果省略，将保留存储的内容。不支持传递 None。
- metadata dict[str, Any] | None- 可选的替换元数据映射。省略时，将保留存储的元数据。如果提供，它将替换存储的元数据对象；此 API 不深入合并元数据。
- ttl_days int | None- 可选的到期刷新（天）。除非提供 ttl_anchor，否则省略此参数以保持当前失效不变。Pass None to use MemoryRetentionConfig.max_ttl_days when the retention configuration sets one, or to clear expiration when it does not. MemoryRetentionConfig.max_ttl_days 以上的值将夹到该最大值并显示警告。过期消息对此线程 API 不可用，无法刷新。
- ttl_anchor TimeToLiveAnchor- 用于到期刷新的可选生存时间锚。将 TimeToLiveAnchor.CREATED_AT 用于消息创建时间，将 TimeToLiveAnchor.TIMESTAMP 用于存储的事件时间戳。提供不带 ttl_days 的 ttl_anchor 将使用方案默认生存时间持续时间。时间戳锚定刷新需要现有存储的 ISO-8601 消息时间戳。没有时区的 ISO-8601 时间戳将视为 UTC。
- **kwargs ( Any )- 意外关键字参数将被拒绝。
退货：更新的消息记录的标识符。
返回类型： str

注

示例

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

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 - 在较早的后台提取完成之前超时到期时引发。
返回类型：无

示例

await thread.wait_for_memory_extraction_async(timeout=10)

注：delete_message() 仅删除原始消息行。派生的记忆可能仍然可以搜索或显示在上下文卡中。使用 OracleAgentMemory.delete_thread() 可删除线程及其关联的消息和记忆。客户机级线程删除会等待已为该线程识别的先前接受的后台提取，但在删除过程中，它不是同一线程上其他操作的全局并发屏障。

消息

class `oracleagentmemory.apis.thread.Message`

基准：object

参数：
- role（角色）str
- 内容 str
- timestamp（时间戳）str | None
- metadata（元数据）dict[str, Any] | None
- id str | None

上下文卡

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'

线程

Oracle 线程

class oracleagentmemory.core.OracleThread

已过时

method add_memory

method add_memory_async（异步）

method add_messages

method add_messages_async（异步）

method delete_memory

method delete_message

method get_context_card

method get_context_card_async（异步）

method get_messages

method get_messages_async（异步）

method get_summary

method get_summary_async（异步）

method search

method search_async（异步）

method update_memory

method update_memory_async（异步）

method update_message

method update_message_async（异步）

method wait_for_memory_extraction

method wait_for_memory_extraction_async（异步）

消息

class oracleagentmemory.apis.thread.Message

上下文卡

class oracleagentmemory.apis.contextcard.ContextCard

property content（抽象）

class oracleagentmemory.core.contextcard.OracleContextCard

property（属性）content

property（属性）formatted_content

概要

class oracleagentmemory.apis.summary.Summary

property content（抽象）

class oracleagentmemory.core.summary.OracleSummary

property（属性）content

property（属性）formatted_content

class `oracleagentmemory.core.OracleThread`

method `add_memory`

method `add_memory_async`（异步）

method `add_messages`

method `add_messages_async`（异步）

method `delete_memory`

method `delete_message`

method `get_context_card`

method `get_context_card_async`（异步）

method `get_messages`

method `get_messages_async`（异步）

method `get_summary`

method `get_summary_async`（异步）

method `search`

method `search_async`（异步）

method `update_memory`

method `update_memory_async`（异步）

method `update_message`

method `update_message_async`（异步）

method `wait_for_memory_extraction`

method `wait_for_memory_extraction_async`（异步）

class `oracleagentmemory.apis.thread.Message`

class `oracleagentmemory.apis.contextcard.ContextCard`

property `content`（抽象）

class `oracleagentmemory.core.contextcard.OracleContextCard`

property（属性）`content`

property（属性）`formatted_content`

class `oracleagentmemory.apis.summary.Summary`

property `content`（抽象）

class `oracleagentmemory.core.summary.OracleSummary`

property（属性）`content`

property（属性）`formatted_content`