线程

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

Oracle 线程

class oracleagentmemory.core.OracleThread

基础：IThread

由 Oracle 存储支持的线程。

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

注

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

创建新的线程句柄。

• 参数：
  • store OracleMemoryStore- 用于保存嵌入式记录的共享存储后端。
  • thread_id str- 线程标识符。如果未提供，将生成 UUID。
  • user_id str- 与线程关联的用户标识符。如果省略，将生成 UUID。
  • agent_id str- 与线程关联的代理标识符。如果省略，将生成 UUID。
  • persist_messages_in_config bool-_to_config 是否应包括最近的原始消息快照。使用数据库存储的线程自动设置为 False，以避免通过线程配置导出消息表内容。
  • LLM ILlm | None- 用于内存提取和上下文摘要更新的可选 LLM 适配器。如果提供，add_messages 将从每条添加的消息中提取相关记忆并将其存储为 record_type="memory"。
  • memory_extraction_window int- 提取期间要作为 LLM 上下文提供的最新消息（包括新添加的消息）的数量。设置为 -1 以使用新添加的全部消息批量仅提取每个 add_messages 调用一次。默认值为 -1。
  • context_summary_update_frequency int- 在消息数之后应更新上下文摘要。设置为 -1 以使用新添加的完整消息批对每个 add_messages 调用仅汇总一次。重复使用相同的节奏在记录写入期间刷新线程汇总元数据。
  • memory_extraction_frequency int- 触发内存提取后的消息数。设置为 -1 以使用新添加的全部消息批量仅提取每个 add_messages 调用一次。
  • memory_extraction_token_limit int- 内存提取中使用的提示的最大大小（以令牌表示）。较长的提示将被截断。如果为负数或 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 与此线程完全匹配的内存。
• 返回：已删除的记录数（0 或 1）。当标识符不存在或属于其他线程时，返回 0。
• 返回类型： int

示例

thread.delete_memory("456")
0

method delete_message

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

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

注

成功删除会清除派生的线程概要状态，因此后续的摘要和上下文卡调用将从剩余的成绩单中重建。派生记忆不会自动删除，因为提取的记忆当前不会持久保留每消息来源。

示例

thread.delete_message("123")
0

method get_context_card

返回线程的类似 XML 的上下文卡。

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

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

注

这会将线程的缺省搜索范围与 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()
True

method get_context_card_async（异步）

异步返回线程的类似 XML 的上下文卡。

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

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。
• 返回：包含汇总的一条助手消息，如果线程没有消息，则列表为空。
• 返回类型： list[ Message ]

示例

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

method get_summary_async（异步）

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

• 参数：
  • except_last int- 要从汇总中排除的最新消息数。
  • token_budget int- 软令牌预算。省略时，将应用有界默认值。正值仅在格式化的摘要超过 _estimate_tokens() 估计的预算时截断；然后返回的文本将限制为 int(token_budget * 3.5) 个字符。非正值将禁用输出边界。
  • **kwargs ( Any )- 保留供将来的摘要选项使用。意外的关键字参数引发 TypeError。
• 返回：包含概要的一条助手消息，如果线程没有消息，则列表为空。
• 返回类型： list[ Message ]

消息

class oracleagentmemory.apis.thread.Message

基准：object

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