线程

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

Oracle 线程

class oracleagentmemory.core.OracleThread

基础：IThread

由 Oracle 存储支持的线程。

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

注

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

创建新的线程句柄。

• 参数：
  • 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_window int- 提取期间要作为 LLM 上下文提供的最新消息（包括新添加的消息）的数量。设置为 -1 以使用新添加的全部消息批量仅提取每个 add_messages 调用一次。默认值为 -1。
  • context_summary_update_frequency int- 应在提取上下文摘要更新后的消息数。设置为 -1 以使用新添加的完整消息批对每个 add_messages 调用仅汇总一次。默认值为 -1。
  • memory_extraction_frequency int- 触发内存提取后的消息数。设置为 -1 以使用新添加的全部消息批量仅提取每个 add_messages 调用一次。
  • memory_extraction_token_limit int- 用于内存提取和运行摘要更新的 LLM 提示的最大大小（以令牌为单位）。较长的提示将被截断。如果为负数或 0，则禁用提示截断。
  • context_card_token_limit int- 用于上下文卡汇总的 LLM 提示的最大大小（以令牌为单位）。默认为 100_000 标记。较长的提示将被截断。如果为负数或 0，则禁用提示截断。
  • 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 进行更新。当前摘要在提取记忆时作为上下文提供。
  • client（客户机）Any | None

示例

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

method add_memory

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

• 参数：
  • content str- 要存储为内存的文本内容。
  • user_id str- 可选的用户标识符覆盖。
  • agent_id str- 可选代理标识符覆盖。
  • thread_id str- 可选线程标识符覆盖。
  • memory_id str- 可选的调用方为此内存行提供的稳定标识符。
  • **store_kwargs ( Any )- 转发到后备存储的特定于存储的写入选项。
• 返回：插入的内存记录的标识符。
• 返回类型： str

示例

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

method add_messages

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

• 参数：
  • messages list[Message | MessageT]- 要附加的消息列表。消息可以是带有 role 和 content 的 Message 对象或字典（以及可选的 id）。
  • **store_kwargs ( Any )- 转发到后备存储的特定于存储的写入选项。
• 返回：已插入消息记录的标识符。
• 返回类型： list[str]

示例

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

method add_messages_async（异步）

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

• 参数：
  • messages（消息）list[Message | MessageT]
  • 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- 派生用于检索和呈现的回退摘要文本时要使用的最近消息数。
  • max_relevant_results int- 检索到的最大持久记录数。
  • max_recent_messages int- 要逐字嵌入的尾随原始消息的最大数量。
  • **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

method get_context_card_async（异步）

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

• 参数：
  • fallback_message_count int- 派生用于检索和呈现的回退摘要文本时要使用的最近消息数。
  • max_relevant_results int- 检索到的最大持久记录数。
  • max_recent_messages int- 要逐字嵌入的尾随原始消息的最大数量。
  • **kwargs ( Any )- 保留供将来的上下文卡选项使用。意外的关键字参数引发 TypeError。
• 返回：线程的上下文卡对象。
• 返回类型：OracleContextCard

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_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

注：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'