代理内存

本页介绍具体的 Oracle AI Agent Memory 实施。

Oracle 代理内存

注：OracleAgentMemory.delete_thread() 是线程范围级联清除支持的路径。它将删除线程以及关联的消息、持久存储和托管检索数据。这比 OracleThread.delete_message() 更宽，后者仅删除原始消息行。客户端级删除将等待相关的早期后台提取：线程删除将等待该线程，内存删除将等待存储目标的线程（如果存在），用户或代理删除将等待已知拥有的线程（无论是否启用了级联清除）。这些等待仅涵盖同一客户机在等待开始之前接受的工作。

class oracleagentmemory.core.OracleAgentMemory

基础：IAgentMemory

由 Oracle DB 或呼叫方提供的存储支持的代理内存客户机。

创建内存客户机。

• 参数：
  • store OracleMemoryStore- 可选的预配置存储实例。如果提供，客户机将直接使用此存储，而不是实例化自己的存储。当调用者需要 OracleAgentMemory 公开的构造器选项之外的存储配置时，这非常有用。
  • connection object- 可选的 Oracle DB 连接/池。如果提供，则使用数据库存储。通过原始连接可为此客户机实例启用单会话模式，因此并发请求应改用连接池。省略时，调用者必须传递显式 store。
  • embedder IEmbedder | str- 嵌入器实现实例或 LiteLLM 嵌入模型标识符。如果省略，则不附加嵌入。然后，仅向量数据库搜索需要通过较低级别的存储 API 进行预计算向量，而关键字数据库搜索可以直接从查询文本运行。混合数据库搜索需要 OracleDBEmbedder 实例，因此托管混合索引和主嵌入器使用相同的数据库内模型。
  • LLM ILlm- 线程用于内存提取和/或上下文汇总的可选 LLM 适配器。默认情况下，从此客户机创建或加载的线程需要 LLM，因此可以挖掘最近的消息以获得持久的内存。在此处传递 llm，稍后在 create_thread 中提供，或者使用 memory_extraction_config=MemoryExtractionConfig(extract_memories=False) 禁用自动提取。
  • memory_extraction_config MemoryExtractionConfig- 可选的客户机级内存提取配置。使用它来控制自动内存提取设置，例如提取模式、摘要行为和提取限制。省略的字段使用 SDK 默认值。特别是，省略的映像上下文为 DISABLED。
  • image_input_limit_config ImageInputLimitConfig- 可选的客户机级原始映像和 LLM 映像请求限制。省略的字段使用 SDK 默认值，并由线程继承，除非线程提供覆盖。无法禁用验证。
  • schema_policy SchemaPolicy | str- 仅当从 connection 构造数据库存储时才使用的数据库方案设置策略。默认值为 SchemaPolicy.REQUIRE_EXISTING。首次在现有方案上启用关键字或混合搜索时，或者打开受支持的较早已发布的托管方案时，请使用 SchemaPolicy.CREATE_IF_NECESSARY，以便 SDK 可以应用非破坏性方案升级并添加所需的文本搜索对象。应改为重新创建已声明当前发行版配置的开发或部分更新的方案。设置 schema_owner 时，仅允许使用 SchemaPolicy.REQUIRE_EXISTING。这样可以防止托管方案 DDL，包括创建方案、升级、重新创建和首次创建混合索引；在以不带 schema_owner 的数据库用户身份连接时执行这些操作。它不会使客户端成为只读：普通内存的读取和写入使用用户授予的数据库权限。
  • memory_store_id str- 仅当从 connection 构造数据库存储时才使用的托管数据库内存存储的稳定 ID。重用同一 ID 重新打开同一托管存储。ID 联接到带下划线的托管数据库对象名称，因此它必须以字母开头，仅包含字母、数字和下划线，并且最多 16 个字符。数据库存储将其规范化为大写，因此大写不会创建其他存储标识。传递 this 或 table_name_prefix，而不是两者。如果省略，则在同时省略 table_name_prefix 时，数据库存储将使用 table_name_prefix 或无前缀默认值。

  • table_name_prefix str-

    仅当从 connection 构造数据库存储时才使用的可选数据库表/索引前缀。传递 this 或 memory_store_id，而不是两者。

    已弃用

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

  • schema_owner str- 现有托管内存存储的可选方案所有者。省略此选项以使用连接用户的方案。当 connection（原始数据库连接或连接池）属于已授予其他用户所拥有的表的应用程序数据库用户时，使用该命令。此选项仅用于对已创建的托管内存存储的运行时访问，并且需要 SchemaPolicy.REQUIRE_EXISTING。在以方案所有者身份连接时创建、升级或重新创建托管内存存储，并忽略此选项。传递一个无引号的标识符；小写输入将规范化为大写，并且不支持带引号的区分大小写的模式所有者。如果传递预配置的 store，请改为在该存储上配置 schema_owner。向应用程序数据库用户授予 CREATE SESSION 和所需的对象权限；有关确切授权，请参见故障排除指南的 Database Users and Privileges 部分。或者，在运行时方案中公开同名的托管对象视图并省略 schema_owner；这仅受 SchemaPolicy.REQUIRE_EXISTING 支持。
  • search_strategy SearchStrategy-SearchStrategy 值，用于从 connection 构造数据库存储时选择 DB-search 后端。使用 SearchStrategy.VECTOR（默认值）进行仅向量检索，使用 SearchStrategy.HYBRID 在存储的搜索文本上查询托管的 Oracle 混合向量索引，使用 SearchStrategy.KEYWORD 在没有向量融合的情况下按关键字/文本匹配对存储的搜索文本进行排名。KEYWORD 不需要嵌入。HYBRID 要求 embedder 为 OracleDBEmbedder。当与现有方案一起使用不兼容的策略时，客户机启动失败，因为该方案可能不包含策略所需的存储搜索状态。省略 schema_policy=SchemaPolicy.REQUIRE_EXISTING 和此参数时，数据库存储尽力从托管元数据中检测到方案的存储搜索模式，并在可用时使用该模式。
  • search_index_sync SearchIndexSyncMode- 选择 SearchStrategy.HYBRID 和 SearchStrategy.KEYWORD 的托管搜索索引刷新行为的 SearchIndexSyncMode 值。SearchIndexSyncMode.ON_COMMIT 是默认值，使写入事务处理提交后立即可搜索记录。SearchIndexSyncMode.MANUAL 将刷新保留为显式数据库端同步操作。SearchIndexSyncMode.AUTO 允许 Oracle 异步刷新托管混合索引，并且仅支持 SearchStrategy.HYBRID；关键字搜索拒绝 AUTO。

  • extract_memories bool-

    True 时，此客户机创建或装入的线程需要 LLM，并且自动内存提取仍处于启用状态。设置为 False 可禁用自动内存提取，并允许这些线程在没有 LLM 的情况下运行。默认值为 True，因此缺少提取 LLM 会快速失败。

    已弃用

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

  • memory_extraction_custom_instructions str-

    对于此客户机创建或装入的线程，附加到自动内存提取系统提示符的可选定制说明。传递给 create_thread、get_thread 或 update_thread 的每线程值优先。

    已弃用

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

  • memory_retention_config MemoryRetentionConfig- 仅当从 connection 构造数据库存储时才使用的可选内存保留配置。MemoryRetentionConfig.default_ttl_days 将应用于写入调用省略 ttl_days 的新消息和内存。MemoryRetentionConfig.max_ttl_days 将显式每记录持续时间夹在配置的最大值之上，并发出警告，如果设置，则使 ttl_days=None 使用该最大值，而不是创建非过期记录。使用 SchemaPolicy.CREATE_IF_NECESSARY 时，显式配置会刷新现有最新托管方案上存储的元数据，但不会更新现有到期日期；省略该配置会保留现有设置。如果显式配置将 default_ttl_days 或 max_ttl_days 留在 NOT_SET_MARKER，SDK 将在比较或存储方案元数据之前将该属性解析为其默认值 (None)。根据记录中存储的预期信息、应用程序保留它的原因以及任何应用程序或监管保留承诺选择此配置。
  • search_config MemorySearchConfig- 由新线程和装入的线程继承的可选客户机级搜索配置。如果省略，搜索将使用固定的 top-k 搜索配置。
  • pruner_llm ILlm- 可选 LLM，用于启用客户机范围的结果修剪。设置后，直接客户机搜索和继承的线程搜索默认使用 FAST 评估模式进行修剪。具有已存储搜索配置的现有线程在重新打开时保留该配置。使用 search_config=PruningMemorySearchConfig(...) 定制修剪行为。pruner_llm 不能与 search_config 组合。

警告：SchemaPolicy.CREATE_IF_NECESSARY 可能比普通客户端启动贵，因为它可能会在初始化成功之前应用托管方案 DDL 和尽力重写数据。在旧托管方案包含多个行时，将首次打开的托管方案计划为迁移或维护操作。

如果方案设置必须创建托管的过期记录清除作业，但数据库用户缺少调度程序 - 作业权限，则初始化将警告并继续。过期的消息和记忆不会被读取和搜索隐藏，但是在具有 CREATE JOB 或等效调度程序权限的用户创建作业之前，这些消息和记忆不会被物理清除。

当 SchemaPolicy.CREATE_IF_NECESSARY 首次在现有方案上创建托管混合索引时，Oracle 会扫描存储的搜索文本，并从配置的数据库内模型构建托管混合索引状态。客户机启动将等待该 DDL 完成，因此，请计划第一次将混合升级作为大型方案的迁移或维护操作。SearchIndexSyncMode 控制索引存在后正在进行的维护；它不会使第一个索引构建异步。

• 引发：ValueError - 如果提供了冲突的存储配置，例如传递 store 和 connection、不带数据库连接的特定于数据库的选项，或者同时忽略 store 和 connection。
• 参数：
  • store OracleMemoryStore
  • connection（连接）object
  • embedder（嵌入式）IEmbedder | str
  • llm ILlm
  • memory_extraction_config MemoryExtractionConfig
  • image_input_limit_config ImageInputLimitConfig
  • schema_policy SchemaPolicy | str
  • memory_store_id str
  • table_name_prefix str
  • schema_owner str
  • search_strategy SearchStrategy
  • search_index_sync SearchIndexSyncMode
  • extract_memories bool
  • memory_extraction_custom_instructions str
  • memory_retention_config MemoryRetentionConfig
  • search_config MemorySearchConfig
  • pruner_llm ILlm

示例

要访问由其他数据库用户创建的方案，请为应用程序数据库用户配置 memory_rw_pool，并将 memory_schema_owner 设置为所有者用户的无引号数据库名称。

from oracleagentmemory.core import (
    MemoryExtractionConfig,
    SearchIndexSyncMode,
    OracleAgentMemory,
    SchemaPolicy,
    SearchStrategy,
)
client = OracleAgentMemory(
    connection=db_pool,
    embedder=embedder,
    llm=llm,
)
read_only_client = OracleAgentMemory(
    connection=db_pool,
    embedder=embedder,
    memory_extraction_config=MemoryExtractionConfig(extract_memories=False),
)
pruned_search_client = OracleAgentMemory(
    connection=db_pool,
    embedder=embedder,
    memory_extraction_config=MemoryExtractionConfig(extract_memories=False),
    pruner_llm=llm,
)
shared_client = OracleAgentMemory(
    connection=memory_rw_pool,
    embedder=embedder,
    llm=llm,
    schema_owner=memory_schema_owner,
)

使用数据库内嵌入模型利用 Oracle 混合索引搜索：

from oracleagentmemory.core.embedders import OracleDBEmbedder
db_embedder = OracleDBEmbedder(
    connection=db_pool,
    model="DOC_MODEL",
    embedding_dimension=768,
)
hybrid_client = OracleAgentMemory(
    connection=db_pool,
    embedder=db_embedder,
    schema_policy=SchemaPolicy.CREATE_IF_NECESSARY,
    search_strategy=SearchStrategy.HYBRID,
    search_index_sync=SearchIndexSyncMode.ON_COMMIT,
    memory_store_id=memory_store_id,
)

method add_agent

将座席概要信息记录添加到门店。

• 参数：
  • agent_id str- 代理标识符。
  • information str- 关于代理的自由格式信息。
  • metadata dict[str, Any] | None- 存储在代理配置文件行上的可选元数据映射。
• 返回：存储的代理配置文件的标识符。
• 返回类型： str

注释

代理概要信息记录存储在客户端级存储中，并有意取消范围。返回的记录标识符与应用程序用作 agent_id 的公共标识符相同。

示例

from oracleagentmemory.core import OracleAgentMemory
client = OracleAgentMemory(
    connection=db_pool,
    embedder=embedder,
    llm=llm,
)
client.add_agent(
    "a1",
    "Support assistant",
    metadata={"source": "catalog"},
)
'a1'

method add_agent_async（异步）

将代理概要信息记录异步添加到门店。

• 参数：
  • agent_id str- 代理标识符。
  • information str- 关于代理的自由格式信息。
  • metadata dict[str, Any] | None- 存储在代理配置文件行上的可选元数据映射。
• 返回：存储的代理配置文件的标识符。
• 返回类型： str

注释

代理概要信息记录存储在客户端级存储中，并有意取消范围。返回的记录标识符与应用程序用作 agent_id 的公共标识符相同。

示例

from oracleagentmemory.core import OracleAgentMemory
client = OracleAgentMemory(
    connection=db_pool,
    embedder=embedder,
    llm=llm,
)
import asyncio
asyncio.run(client.add_agent_async(
    "a1",
    "Support assistant",
    metadata={"source": "catalog"},
))
'a1'

method add_image

向客户端添加图像记录。

• 参数：
  • image bytes- 要存储为映像的映像字节数。
  • description str | None- 与映像关联的可选说明。省略它或传递 None 以使用配置的 LLM 生成一个 LLM。
  • mime_type ImageMimeType- 映像的 MIME 类型。支持的值由 ImageMimeType 提供。如果省略，SDK 将从映像字节检测并验证该类型。支持的检测类型包括 PNG、JPEG 和 WEBP。
  • image_id str- 可选的调用方提供的稳定标识符。如果省略，将生成一个。
  • user_id str | None- 可选用户所有者。请至少提供 user_id、agent_id 或 thread_id 中的一个；这三个不能都是 None。
  • agent_id str | None- 与映像关联的可选代理标识符。
  • thread_id str- 与映像关联的可选线程标识符。
  • metadata dict[str, Any] | None- 与映像行一起保留的可选元数据。
  • timestamp str | None- 用于保存此映像的可选事件时间戳。省略此参数或传递 None 来存储 NULL 事件时间戳。读取映像时，其创建时间将作为有效时间戳返回。
  • ttl_days int | None- 可选的生存时间持续时间（天）。省略此参数以使用模式默认的生存时间持续时间。传递 None 以存储不会过期的映像。
  • ttl_anchor TimeToLiveAnchor- 可选的生存时间锚。将 TimeToLiveAnchor.CREATED_AT 用于数据库创建时间，将 TimeToLiveAnchor.TIMESTAMP 用于映像时间戳。
  • **store_kwargs ( Any )- 特定于实施的写入选项，转发到后备存储。
• 返回：已插入图像记录的标识符。
• 返回类型： str

示例

image_id = client.add_image(
    b"image-bytes",
    description="Image description",
    mime_type=ImageMimeType.PNG,
    image_id="img-1",
    user_id="user-1",
)
image_id
'img-1'

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- 所有者范围标识符。必须至少有一个非 None。提供 thread_id 时，其存储的用户和代理所有权具有权威性；省略的用户和代理值是继承的。
  • agent_id str | None- 所有者范围标识符。必须至少有一个非 None。提供 thread_id 时，其存储的用户和代理所有权具有权威性；省略的用户和代理值是继承的。
  • thread_id str- 所有者范围标识符。必须至少有一个非 None。提供 thread_id 时，其存储的用户和代理所有权具有权威性；省略的用户和代理值是继承的。
  • 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- 与存储的内存关联的可选范围标识符。如果省略了 user_id，并且数据库连接带有最终用户安全上下文，则存储将使用该上下文的用户名。
  • agent_id str- 与存储的内存关联的可选作用域标识符。如果省略了 user_id，并且数据库连接带有最终用户安全上下文，则存储将使用该上下文的用户名。
  • thread_id str- 与存储的内存关联的可选作用域标识符。如果省略了 user_id，并且数据库连接带有最终用户安全上下文，则存储将使用该上下文的用户名。
  • memory_id str- 可选的调用方为此内存行提供的稳定标识符。
  • metadata dict[str, Any] | None- 可与存储的内存一起保留的可选元数据。
  • timestamp str | None- 用于保存此内存的可选事件时间戳。省略此参数或传递 None 来存储 NULL 事件时间戳。读取记录时，其创建时间将作为有效时间戳返回。如果 ttl_anchor 为 TimeToLiveAnchor.TIMESTAMP，则不带时区的 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 时间戳将视为 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

示例

from oracleagentmemory.core import OracleAgentMemory
client = OracleAgentMemory(
    connection=db_pool,
    embedder=embedder,
    llm=llm,
)
memory_id = client.add_memory("User likes pizza", memory_id="mem-1")
memory_id
'mem-1'

method add_memory_async（异步）

在内存系统中异步添加内存。

• 参数：
  • content str- 要持久保留的内存内容。
  • memory_type Literal['memory', 'guideline', 'fact', 'preference'] | ~oracleagentmemory._notset._NotSetMarker- 要存储的内存类别。支持的值包括 "memory"、"fact"、"guideline" 和 "preference"。如果省略，内容将存储为常规 "memory"。
  • user_id str- 与存储的内存关联的可选范围标识符。如果省略了 user_id，并且数据库连接带有最终用户安全上下文，则存储将使用该上下文的用户名。
  • agent_id str- 与存储的内存关联的可选作用域标识符。如果省略了 user_id，并且数据库连接带有最终用户安全上下文，则存储将使用该上下文的用户名。
  • thread_id str- 与存储的内存关联的可选作用域标识符。如果省略了 user_id，并且数据库连接带有最终用户安全上下文，则存储将使用该上下文的用户名。
  • memory_id str- 可选的调用方为此内存行提供的稳定标识符。
  • metadata dict[str, Any] | None- 可与存储的内存一起保留的可选元数据。
  • timestamp str | None- 用于保存此内存的可选事件时间戳。省略此参数或传递 None 来存储 NULL 事件时间戳。读取记录时，其创建时间将作为有效时间戳返回。如果 ttl_anchor 为 TimeToLiveAnchor.TIMESTAMP，则不带时区的 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 时间戳将视为 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

示例

from oracleagentmemory.core import OracleAgentMemory
client = OracleAgentMemory(
    connection=db_pool,
    embedder=embedder,
    llm=llm,
)
import asyncio
memory_id = asyncio.run(client.add_memory_async(
    "User likes pizza", memory_id="mem-1"
))
memory_id
'mem-1'

method add_user

将用户概要信息记录添加到门店。

• 参数：
  • user_id str- 用户标识符。
  • information str- 关于用户的自由格式信息。
  • metadata dict[str, Any] | None- 存储在用户配置文件行上的可选元数据映射。
• 返回：存储的用户配置文件的标识符。
• 返回类型： str

注释

用户概要信息记录存储在客户端级存储中，并且有意取消范围。返回的记录标识符与应用程序用作 user_id 的公共标识符相同。

示例

from oracleagentmemory.core import OracleAgentMemory
client = OracleAgentMemory(
    connection=db_pool,
    embedder=embedder,
    llm=llm,
)
client.add_user(
    "u1",
    "Prefers concise answers.",
    metadata={"source": "crm"},
)
'u1'

method add_user_async（异步）

将用户概要信息记录异步添加到门店。

• 参数：
  • user_id str- 用户标识符。
  • information str- 关于用户的自由格式信息。
  • metadata dict[str, Any] | None- 存储在用户配置文件行上的可选元数据映射。
• 返回：存储的用户配置文件的标识符。
• 返回类型： str

注释

用户概要信息记录存储在客户端级存储中，并且有意取消范围。返回的记录标识符与应用程序用作 user_id 的公共标识符相同。

示例

from oracleagentmemory.core import OracleAgentMemory
client = OracleAgentMemory(
    connection=db_pool,
    embedder=embedder,
    llm=llm,
)
import asyncio
asyncio.run(client.add_user_async(
    "u1",
    "Prefers concise answers.",
    metadata={"source": "crm"},
))
'u1'

method close

关闭代理内存组件。

关闭将停止接受新的后台工作，包括内存提取和图像描述生成，并等待待定工作完成到配置的超时。如果该超时到期，即使某些工作仍未完成，close() 也会返回。方法是幂等的。

• 参数：timeout float | None- 等待已接受的后台工作完成的最大可选秒数。默认为 300。传递 None 以无限期等待。
• 返回类型：无

示例

client = OracleAgentMemory(
    connection=db_pool,
    embedder=embedder,
    schema_policy=SchemaPolicy.CREATE_IF_NECESSARY,
    memory_extraction_config=MemoryExtractionConfig(extract_memories=False),
)
client.close()

method close_async（异步）

异步关闭代理内存组件。

此方法遵循与 close() 相同的关闭行为。如果超时到期，则可以在后台工作仍在运行时返回。

• 参数：timeout float | None- 等待已接受的后台工作完成的最大可选秒数。默认为 300。传递 None 以无限期等待。
• 返回类型：无

示例

import asyncio
asyncio.run(client.close_async())

method create_thread

创建并注册主题。

• 参数：
  • thread_id str- 线程标识符。如果省略，将生成一个新的。
  • user_id str- 附加到此线程记录的用户标识符。如果省略，并且数据库连接带有最终用户安全上下文，则使用该上下文的用户名。否则，将生成新标识符。
  • agent_id str- 附加到此线程记录的代理标识符。如果省略，将生成一个新的。
  • metadata dict[str, Any] | None- 类 JSON 的可选元数据保留在对话线程中。
  • LLM ILlm- 此线程的可选 LLM 覆盖。如果省略，则使用在构建时配置的客户机级 LLM。缺省情况下，客户机或线程必须提供 LLM，以便可以运行自动内存提取。在此处或客户端上设置 memory_extraction_config=MemoryExtractionConfig(extract_memories=False) 以选择退出该要求。
  • max_message_token_length int- 内存提取和上下文摘要更新期间截断或汇总之前的最大提示时间消息大小。存储的消息内容保持不变。省略时，默认为 15_000 标记。
  • message_shortening_input_token_limit int- 缩短超大提示时间消息复制时发送到 LLM 的消息摘录的最大大小（以令牌表示）。省略时，默认为 30_000 标记。
  • memory_extraction_config MemoryExtractionConfig- 可选的每线程内存提取配置。提供的字段将覆盖客户机配置。省略的映像上下文使用客户机值，然后使用 DISABLED。解析的配置与线程一起存储，因此以后加载会保留创建时行为。
  • image_input_limit_config ImageInputLimitConfig- 可选的每线程原始映像和 LLM 映像请求限制。省略的字段从客户机配置继承。解析的限制随线程一起存储。
  • search_config MemorySearchConfig- 线程的可选搜索配置。如果省略，则使用客户机级配置。
  • context_card_token_limit int- 用于构建上下文卡中包括的摘要和主题列表的 LLM 提示符的最大输入令牌预算。如果省略，则默认为 100_000。
  • context_card_type_search_concurrency int- 使用 min_relevant_results_by_type 构建上下文卡时要同时运行的最大内存类记录搜索数。如果省略，则默认为 5。

  • extract_memories bool-

    用于自动内存提取的可选每线程覆盖。当 True 时，此线程需要 LLM，因此可以运行自动提取。设置为 False 可对此线程禁用自动提取并允许在没有 LLM 的情况下执行操作。省略时，将使用客户机级 extract_memories 设置。

    已弃用

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

  • memory_extraction_window int-

    内存提取期间要包含的最近消息数。设置为 -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 调用执行一次提取。如果省略，则默认为 -1。

    已弃用

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

  • memory_extraction_token_limit int-

    用于内存提取和运行摘要更新的 LLM 提示的最大大小（以标记为单位）。如果省略，则默认为 100_000。

    已弃用

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

  • memory_extraction_custom_instructions str-

    附加到此线程的内存提取系统提示符的可选定制说明。如果提供，解析的值将保留在线程运行时配置中。

    已弃用

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

  • memory_extraction_inherit_message_metadata bool | Sequence[str]-

    从源消息复制到自动提取的存储器上的元数据的可选每线程覆盖。

    已弃用

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

  • enable_context_summary bool-

    是否为此线程保留正在运行的上下文摘要。

    已弃用

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

  • **kwargs ( Any )- 其他特定于实现的线程选项。
• 返回：OracleThread 实例。
• 返回类型：OracleThread
• 引发：ValueError - 如果没有 LLM 可用于自动内存提取，并且线程和客户机未配置 memory_extraction_config=MemoryExtractionConfig(extract_memories=False)。

示例

from oracleagentmemory.core import OracleAgentMemory
client = OracleAgentMemory(
    connection=db_pool,
    embedder=embedder,
    llm=llm,
)
thread = client.create_thread(thread_id="c1", user_id="u1")
thread.thread_id
'c1'

method create_thread_async（异步）

异步创建并注册线程。

• 参数：
  • thread_id str- 线程标识符。如果省略，将生成一个新的。
  • user_id str- 附加到此线程记录的用户标识符。如果省略，并且数据库连接带有最终用户安全上下文，则使用该上下文的用户名。否则，将生成新标识符。
  • agent_id str- 附加到此线程记录的代理标识符。如果省略，将生成一个新的。
  • metadata dict[str, Any] | None- 类 JSON 的可选元数据保留在对话线程中。
  • LLM ILlm- 此线程的可选 LLM 覆盖。如果省略，则使用在构建时配置的客户机级 LLM。缺省情况下，客户机或线程必须提供 LLM，以便可以运行自动内存提取。在此处或客户端上设置 memory_extraction_config=MemoryExtractionConfig(extract_memories=False) 以选择退出该要求。
  • max_message_token_length int- 内存提取和上下文摘要更新期间截断或汇总之前的最大提示时间消息大小。存储的消息内容保持不变。省略时，默认为 15_000 标记。
  • message_shortening_input_token_limit int- 缩短超大提示时间消息复制时发送到 LLM 的消息摘录的最大大小（以令牌表示）。省略时，默认为 30_000 标记。
  • memory_extraction_config MemoryExtractionConfig- 可选的每线程内存提取配置。提供的字段将覆盖客户机配置。省略的映像上下文使用客户机值，然后使用 DISABLED。解析的配置与线程一起存储，因此以后加载会保留创建时行为。
  • image_input_limit_config ImageInputLimitConfig- 可选的每线程原始映像和 LLM 映像请求限制。省略的字段从客户机配置继承。解析的限制随线程一起存储。
  • search_config MemorySearchConfig- 线程的可选搜索配置。如果省略，则使用客户机级配置。
  • context_card_token_limit int- 用于构建上下文卡中包括的摘要和主题列表的 LLM 提示符的最大输入令牌预算。如果省略，则默认为 100_000。
  • context_card_type_search_concurrency int- 使用 min_relevant_results_by_type 构建上下文卡时要同时运行的最大内存类记录搜索数。如果省略，则默认为 5。

  • extract_memories bool-

    用于自动内存提取的可选每线程覆盖。当 True 时，此线程需要 LLM，因此可以运行自动提取。设置为 False 可对此线程禁用自动提取并允许在没有 LLM 的情况下执行操作。省略时，将使用客户机级 extract_memories 设置。

    已弃用

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

  • memory_extraction_window int-

    内存提取期间要包含的最近消息数。设置为 -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 调用执行一次提取。如果省略，则默认为 -1。

    已弃用

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

  • memory_extraction_token_limit int-

    用于内存提取和运行摘要更新的 LLM 提示的最大大小（以标记为单位）。如果省略，则默认为 100_000。

    已弃用

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

  • memory_extraction_custom_instructions str-

    附加到此线程的内存提取系统提示符的可选定制说明。如果提供，解析的值将保留在线程运行时配置中。

    已弃用

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

  • memory_extraction_inherit_message_metadata bool | Sequence[str]-

    从源消息复制到自动提取的存储器上的元数据的可选每线程覆盖。

    已弃用

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

  • enable_context_summary bool-

    是否为此线程保留正在运行的上下文摘要。

    已弃用

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

  • **kwargs ( Any )- 其他特定于实现的线程选项。
• 返回：OracleThread 实例。
• 返回类型：OracleThread
• 引发：ValueError - 如果没有 LLM 可用于自动内存提取，并且线程和客户机未配置 memory_extraction_config=MemoryExtractionConfig(extract_memories=False)。

示例

from oracleagentmemory.core import OracleAgentMemory
client = OracleAgentMemory(
    connection=db_pool,
    embedder=embedder,
    llm=llm,
)
import asyncio
thread = asyncio.run(client.create_thread_async(
    thread_id="c1", user_id="u1"
))
thread.thread_id
'c1'

method delete_agent

按标识符删除代理概要记录。

• 参数：
  • agent_id str- 应删除其配置文件的代理标识符。
  • cascade bool- 当 True（缺省值）时，还将删除限定到此代理的记录。这包括删除拥有的线程本身、使用这些线程删除的消息和类似内存的记录，以及所有剩余的直接代理范围的记录，例如消息、内存、准则、事实或首选项。当匹配的代理概要文件行已经缺失时，此范围清除仍会运行。设置为 False 以仅删除概要信息记录。
• 返回值：已删除的代理概要文件行数（0 或 1）。在级联清除期间删除了作用域行时，这可能仍为 0。
• 返回类型： int
• 引发：TimeoutError - 在内部删除等待超时之前，当已知的已拥有线程的已接受后台提取未完成时引发。

注释

在删除配置文件之前，此方法最多等待 300 秒，以便通过此代理内存组件已知的所有线程可以接受更早的后台提取。无论是否启用级联清除，此等待均适用。级联清理作为一项操作在后备存储内计划和执行。该方法不会等待等待等待开始后接受的工作，也不会等待其他代理内存组件或进程启动的工作。不支持在删除过程中同时使用操作者范围。

示例

from oracleagentmemory.core import OracleAgentMemory
client = OracleAgentMemory(
    connection=db_pool,
    embedder=embedder,
    llm=llm,
)
client.add_agent("a-delete", "Support assistant")
'a-delete'
client.delete_agent("a-delete")
1

method delete_agent_async（异步）

异步删除按标识符列出的代理概要信息记录。

• 参数：
  • agent_id str- 应删除其配置文件的代理标识符。
  • cascade bool- 当 True（缺省值）时，还将删除限定到此代理的记录。这包括删除拥有的线程本身、使用这些线程删除的消息和类似内存的记录，以及所有剩余的直接代理范围的记录，例如消息、内存、准则、事实或首选项。当匹配的代理概要文件行已经缺失时，此范围清除仍会运行。设置为 False 以仅删除概要信息记录。
• 返回值：已删除的代理概要文件行数（0 或 1）。在级联清除期间删除了作用域行时，这可能仍为 0。
• 返回类型： int
• 引发：TimeoutError - 如果已知拥有线程的早期接受后台提取未在 300 秒内完成，则引发而不删除配置文件。

注释

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

示例

from oracleagentmemory.core import OracleAgentMemory
client = OracleAgentMemory(
    connection=db_pool,
    embedder=embedder,
    llm=llm,
)
import asyncio
asyncio.run(client.add_agent_async("a-delete", "Support assistant"))
'a-delete'
asyncio.run(client.delete_agent_async("a-delete"))
1

method delete_image

按标识符删除图像记录。

• 参数：image_id str- 要删除的图像记录的标识符。
• 退货：已删除的图像记录数。
• 返回类型： int
• 引发：ValueError - 如果图像附加到消息。改为删除或更新父消息。

method delete_image_async（异步）

通过配置的存储删除一个独立映像。

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

method delete_memory

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

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

注释

在删除线程范围的记录之前，此方法会解析其存储的线程，并等待通过此代理内存组件接受的早期后台提取。它不会等待不相关的线程、等待开始后接受的工作，或者由其他代理内存组件或进程启动的工作。没有线程范围和未知标识符的记录不会导致提取等待。

示例

client = OracleAgentMemory(
    connection=db_pool,
    embedder=embedder,
    llm=llm,
)
memory_id = client.add_memory("Temporary memory", memory_id="mem-delete")
client.delete_memory(memory_id)
1

method delete_memory_async（异步）

异步删除类似内存的记录。

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

注释

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

示例

import asyncio
memory_id = asyncio.run(client.add_memory_async(
    "Temporary memory", memory_id="mem-delete"
))
asyncio.run(client.delete_memory_async(memory_id))
1

method delete_record_link

按标识符删除关系或完成端点元组。

未提供 relation_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

示例

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

method delete_record_link_async（异步）

按 ID 异步删除关系或完成端点元组。

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

method delete_thread

删除与线程标识符关联的所有记录。

• 参数：thread_id str- 要删除的线程标识符。
• 返回数：已删除的对话线程数（0 或 1）。
• 返回类型： int
• 引发：TimeoutError - 在内部删除等待超时之前未完成此线程早期接受的后台提取时引发。

注释

Use this operation when you need retention-complete removal of a thread. The backing store deletes the thread together with associated thread-scoped messages, durable memories, and managed retrieval data. This differs from OracleThread.delete_message(), which removes only the raw message record and does not cascade to derived memories created from that message. Before deleting the thread, this method waits for earlier background extraction already accepted for that thread through this agent memory component. It does not wait for background work accepted after that wait begins or for work started by another agent memory component or process. Concurrent use of the same thread while deletion is in progress is unsupported.

示例

from oracleagentmemory.core import OracleAgentMemory
client = OracleAgentMemory(
    connection=db_pool,
    embedder=embedder,
    llm=llm,
)
thread = client.create_thread(thread_id="c-delete")
client.delete_thread(thread.thread_id)
1

method delete_thread_async（异步）

异步删除与线程标识符关联的所有记录。

• 参数：thread_id str- 要删除的线程标识符。
• 返回数：已删除的对话线程数（0 或 1）。
• 返回类型： int
• 引发：TimeoutError - 在内部删除等待超时之前未完成此线程早期接受的后台提取时引发。

注释

Use this operation when you need retention-complete removal of a thread. The backing store deletes the thread together with associated thread-scoped messages, durable memories, and managed retrieval data. This differs from OracleThread.delete_message(), which removes only the raw message record and does not cascade to derived memories created from that message. Before deleting the thread, this method waits for earlier background extraction already accepted for that thread through this agent memory component. It does not wait for background work accepted after that wait begins or for work started by another agent memory component or process. Concurrent use of the same thread while deletion is in progress is unsupported.

示例

from oracleagentmemory.core import OracleAgentMemory
client = OracleAgentMemory(
    connection=db_pool,
    embedder=embedder,
    llm=llm,
)
import asyncio
thread = asyncio.run(client.create_thread_async(thread_id="c-delete"))
asyncio.run(client.delete_thread_async(thread.thread_id))
1

method delete_user

按标识符删除用户概要记录。

• 参数：
  • user_id str- 应删除其配置文件的用户标识符。
  • cascade bool- 当 True（缺省值）时，还将删除限定到此用户的记录。这包括删除拥有的线程本身、使用这些线程删除的消息和类似内存的记录，以及任何剩余的直接用户范围记录，例如消息、内存、准则、事实或首选项。当匹配的用户配置文件行已经缺失时，此范围清除仍会运行。设置为 False 以仅删除概要信息记录。
• 返回值：已删除的用户配置文件行数（0 或 1）。在级联清除期间删除了作用域行时，这可能仍为 0。
• 返回类型： int
• 引发：TimeoutError - 在内部删除等待超时之前，当已知的已拥有线程的已接受后台提取未完成时引发。

注释

在删除配置文件之前，此方法最多等待 300 秒，以便通过此代理内存组件已知的所有线程可以接受更早的后台提取。无论是否启用级联清除，此等待均适用。级联清理作为一项操作在后备存储内计划和执行。该方法不会等待等待等待开始后接受的工作，也不会等待其他代理内存组件或进程启动的工作。不支持在删除过程中同时使用操作者范围。

示例

from oracleagentmemory.core import OracleAgentMemory
client = OracleAgentMemory(
    connection=db_pool,
    embedder=embedder,
    llm=llm,
)
client.add_user("u-delete", "Prefers concise answers.")
'u-delete'
client.delete_user("u-delete")
1

method delete_user_async（异步）

异步删除按标识符列出的用户概要记录。

• 参数：
  • user_id str- 应删除其配置文件的用户标识符。
  • cascade bool- 当 True（缺省值）时，还将删除限定到此用户的记录。这包括删除拥有的线程本身、使用这些线程删除的消息和类似内存的记录，以及任何剩余的直接用户范围记录，例如消息、内存、准则、事实或首选项。当匹配的用户配置文件行已经缺失时，此范围清除仍会运行。设置为 False 以仅删除概要信息记录。
• 返回值：已删除的用户配置文件行数（0 或 1）。在级联清除期间删除了作用域行时，这可能仍为 0。
• 返回类型： int
• 引发：TimeoutError - 如果已知拥有线程的早期接受后台提取未在 300 秒内完成，则引发而不删除配置文件。

注释

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

示例

from oracleagentmemory.core import OracleAgentMemory
client = OracleAgentMemory(
    connection=db_pool,
    embedder=embedder,
    llm=llm,
)
import asyncio
asyncio.run(client.add_user_async("u-delete", "Prefers concise answers."))
'u-delete'
asyncio.run(client.delete_user_async("u-delete"))
1

method get_thread

检索以前创建的线程。

• 参数：
  • thread_id str- 创建线程时使用的标识符。
  • LLM ILlm- 重新打开的线程的可选 LLM 覆盖。省略时，将使用在构建时配置的客户机级 LLM。
  • max_message_token_length int- 内存提取和上下文摘要更新期间截断或汇总之前的最大提示时间消息大小的可选覆盖。存储的消息内容保持不变。
  • message_shortening_input_token_limit int- 在缩短超大提示时间消息复制时发送到 LLM 的消息摘录的最大大小（以令牌表示）的可选覆盖。
  • memory_extraction_config MemoryExtractionConfig- 返回的 OracleThread 实例的可选分组提取配置。提供的字段将覆盖已保存的线程值。省略的图像上下文使用保存的线程值，然后是客户机值，再是 DISABLED。覆盖仅适用于返回的 OracleThread 实例，不会写回存储的对话线程配置。
  • image_input_limit_config ImageInputLimitConfig- 可选的原始映像和 LLM 映像请求限制覆盖。省略的字段继承存储的线程限制。此覆盖仅适用于返回的线程，不会保留。
  • search_config MemorySearchConfig- 返回的 OracleThread 的可选搜索配置。省略时，将使用存储的或客户机级别的配置。此覆盖仅适用于返回的线程。
  • context_card_token_limit int- 返回的 OracleThread 实例的可选覆盖。它设置用于构建上下文卡中包括的汇总和主题列表的 LLM 提示的输入令牌预算。
  • context_card_type_search_concurrency int- 返回的 OracleThread 实例的可选覆盖。它设置在使用 min_relevant_results_by_type 构建上下文卡时要同时运行的类似内存的记录搜索数。

  • extract_memories bool-

    在重新打开的线程上自动提取内存的可选覆盖。省略时，将使用客户机级 extract_memories 设置。

    已弃用

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

  • memory_extraction_window int-

    内存提取期间使用的最近消息数的可选覆盖。

    已弃用

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

  • context_summary_update_frequency int-

    自动刷新前最新的有效汇总后的消息的可选改写。

    已弃用

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

  • memory_extraction_frequency int-

    内存提取更新频率的可选覆盖。

    已弃用

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

  • memory_extraction_token_limit int-

    用于内存提取和运行摘要更新的 LLM 提示的最大大小（以令牌为单位）的可选覆盖。

    已弃用

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

  • memory_extraction_custom_instructions str | None-

    自定义内存提取指令的可选覆盖。通过 None 将清除返回的 OracleThread 实例的线程级别定制指令，而不更新存储的对话线程配置；配置客户机级别默认值时仍适用。

    已弃用

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

  • memory_extraction_inherit_message_metadata bool | Sequence[str]-

    从源消息复制到自动提取的存储器上的元数据的可选覆盖。覆盖仅适用于返回的 OracleThread 实例。

    已弃用

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

  • enable_context_summary bool-

    用于重新打开的线程是否应保留正在运行的上下文摘要的可选覆盖。

    已弃用

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

• 返回：基于存储元数据重建的 OracleThread 实例。
• 返回类型：OracleThread
• 增加：
  • KeyError - 如果此客户机实例不知道线程 ID。
  • ValueError - 如果没有 LLM 可用于自动内存提取，并且客户机未配置 memory_extraction_config=MemoryExtractionConfig(extract_memories=False)。

注释

显式每次调用覆盖优先。省略运行时覆盖时，重新打开的线程将在可用时使用持久运行时配置，然后再回退到 SDK 默认值。

示例

from oracleagentmemory.core import OracleAgentMemory
client = OracleAgentMemory(
    connection=db_pool,
    embedder=embedder,
    llm=llm,
)
created = client.create_thread(thread_id="c2", user_id="u1")
loaded = client.get_thread("c2")
loaded.user_id
'u1'

method get_thread_async（异步）

异步检索以前创建的线程。

• 参数：
  • thread_id str- 创建线程时使用的标识符。
  • LLM ILlm- 重新打开的线程的可选 LLM 覆盖。省略时，将使用在构建时配置的客户机级 LLM。
  • max_message_token_length int- 内存提取和上下文摘要更新期间截断或汇总之前的最大提示时间消息大小的可选覆盖。存储的消息内容保持不变。
  • message_shortening_input_token_limit int- 在缩短超大提示时间消息复制时发送到 LLM 的消息摘录的最大大小（以令牌表示）的可选覆盖。
  • memory_extraction_config MemoryExtractionConfig- 返回的 OracleThread 实例的可选分组提取配置。提供的字段将覆盖已保存的线程值。省略的图像上下文使用保存的线程值，然后是客户机值，再是 DISABLED。覆盖仅适用于返回的 OracleThread 实例，不会写回存储的对话线程配置。
  • image_input_limit_config ImageInputLimitConfig- 可选的原始映像和 LLM 映像请求限制覆盖。省略的字段继承存储的线程限制。此覆盖仅适用于返回的线程，不会保留。
  • search_config MemorySearchConfig- 返回的 OracleThread 的可选搜索配置。省略时，将使用存储的或客户机级别的配置。此覆盖仅适用于返回的线程。
  • context_card_token_limit int- 返回的 OracleThread 实例的可选覆盖。它设置用于构建上下文卡中包括的汇总和主题列表的 LLM 提示的输入令牌预算。
  • context_card_type_search_concurrency int- 返回的 OracleThread 实例的可选覆盖。它设置在使用 min_relevant_results_by_type 构建上下文卡时要同时运行的类似内存的记录搜索数。

  • extract_memories bool-

    在重新打开的线程上自动提取内存的可选覆盖。省略时，将使用客户机级 extract_memories 设置。

    已弃用

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

  • memory_extraction_window int-

    内存提取期间使用的最近消息数的可选覆盖。

    已弃用

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

  • context_summary_update_frequency int-

    自动刷新前最新的有效汇总后的消息的可选改写。

    已弃用

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

  • memory_extraction_frequency int-

    内存提取更新频率的可选覆盖。

    已弃用

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

  • memory_extraction_token_limit int-

    用于内存提取和运行摘要更新的 LLM 提示的最大大小（以令牌为单位）的可选覆盖。

    已弃用

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

  • memory_extraction_custom_instructions str | None-

    自定义内存提取指令的可选覆盖。通过 None 将清除返回的 OracleThread 实例的线程级别定制指令，而不更新存储的对话线程配置；配置客户机级别默认值时仍适用。

    已弃用

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

  • memory_extraction_inherit_message_metadata bool | Sequence[str]-

    从源消息复制到自动提取的存储器上的元数据的可选覆盖。覆盖仅适用于返回的 OracleThread 实例。

    已弃用

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

  • enable_context_summary bool-

    用于重新打开的线程是否应保留正在运行的上下文摘要的可选覆盖。

    已弃用

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

• 返回：基于存储元数据重建的 OracleThread 实例。
• 返回类型：OracleThread
• 增加：
  • KeyError - 如果此客户机实例不知道线程 ID。
  • ValueError - 如果没有 LLM 可用于自动内存提取，并且客户机未配置 memory_extraction_config=MemoryExtractionConfig(extract_memories=False)。

注释

显式每次调用覆盖优先。省略运行时覆盖时，重新打开的线程将在可用时使用持久运行时配置，然后再回退到 SDK 默认值。

示例

from oracleagentmemory.core import OracleAgentMemory
client = OracleAgentMemory(
    connection=db_pool,
    embedder=embedder,
    llm=llm,
)
import asyncio
created = asyncio.run(client.create_thread_async(
    thread_id="c2", user_id="u1"
))
loaded = asyncio.run(client.get_thread_async("c2"))
loaded.user_id
'u1'

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- 反向遍历此关系时要使用的可选标签。对于内置内存关系类型，省略此项以存储预定义的反向标签（例如，"supports" 变为 "is_supported_by"）。对于自定义关系类型，省略在两个方向上使用相同的标签。
  • relation_id str- 可选的稳定关系标识符。省略它以生成一个。
  • timestamp str | None- 与关系关联的可选时间戳。
  • metadata dict[str, Any] | None- 关系上存储的可选元数据。
• 返回：已创建关系的标识符。
• 返回类型： str

示例

client.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_agents

列出持久的代理概要信息记录。

• 参数：
  • metadata_filter dict[str, Any] | None- 元数据过滤器应用于代理配置文件元数据。省略时，不应用元数据筛选。传递 None 以仅列出没有存储元数据的配置文件。
  • limit int | None- 要返回的可选最大记录数。省略后，后备存储可能会应用其默认列表上限。传递 None 以禁用该上限。
• 返回：后备存储返回的代理概要信息记录。
• 返回类型： list[ AgentProfileRecord ]

示例

from oracleagentmemory.core import OracleAgentMemory
client = OracleAgentMemory(
    connection=db_pool,
    embedder=embedder,
    llm=llm,
)
client.add_agent("a1", "Support assistant", metadata={"source": "catalog"})
'a1'
[record.id for record in client.list_agents(metadata_filter={"source": "catalog"})]
['a1']

method list_agents_async（异步）

异步列出持久化的代理概要信息记录。

• 参数：
  • metadata_filter dict[str, Any] | None- 元数据过滤器应用于代理配置文件元数据。省略时，不应用元数据筛选。传递 None 以仅列出没有存储元数据的配置文件。
  • limit int | None- 要返回的可选最大记录数。省略后，后备存储可能会应用其默认列表上限。传递 None 以禁用该上限。
• 返回：后备存储返回的代理概要信息记录。
• 返回类型： list[ AgentProfileRecord ]

示例

import anyio
from oracleagentmemory.core import OracleAgentMemory
client = OracleAgentMemory(
    connection=db_pool,
    embedder=embedder,
    llm=llm,
)
async def main():
    await client.add_agent_async(
        "a1",
        "Support assistant",
        metadata={"source": "catalog"},
    )
    records = await client.list_agents_async(metadata_filter={"source": "catalog"})
    return [record.id for record in records]
anyio.run(main)
['a1']

method list_images

列表保留了独立映像记录。

• 参数：
  • image_id str- 用于缩小后备存储所返回记录的可选映像标识符。省略时，不应用标识符筛选器。标识符筛选器在 limit 之前应用。
  • user_id str | None- 可选的确切用户过滤器。如果省略，将返回任何用户的图像。传递 None 以仅列出没有用户范围的映像。至少需要一个非 None 用户、代理或线程范围。
  • agent_id str | None- 可选的精确代理过滤器。省略时，将返回任何代理的图像。传递 None 以仅列出没有代理范围的映像。
  • thread_id str | None- 可选的确切线程过滤器。省略时，将返回任何线程的图像。传递 None 以仅列出没有线程范围的映像。
  • metadata_filter dict[str, Any] | None- 应用于映像元数据的元数据过滤器。省略时，不应用元数据筛选。传递 None 以仅列出没有存储元数据的映像。
  • include_bytes bool- 是否在每个返回的记录中装入映像字节。省略或 False 时，不会加载映像字节。仅使用 image_id 和至少一个精确的用户、代理或线程范围筛选器将此值设置为 True。
  • limit int | None- 从后备存储请求的最大记录数（可选）。如果省略，存储可能会应用其默认列表上限。传递 None 以禁用该上限。
• 退货：匹配由后备存储排序的图像记录。
• 返回类型： list[ ImageRecord ]

示例

images = client.list_images(user_id="u1", limit=10)
[image.id for image in images]
['img-1']

method list_images_async（异步）

列表以异步方式持久保存独立映像记录。

• 参数：
  • image_id str- 用于缩小后备存储所返回记录的可选映像标识符。省略时，不应用标识符筛选器。标识符筛选器在 limit 之前应用。
  • user_id str | None- 可选的确切用户过滤器。如果省略，将返回任何用户的图像。传递 None 以仅列出没有用户范围的映像。至少需要一个非 None 用户、代理或线程范围。
  • agent_id str | None- 可选的精确代理过滤器。省略时，将返回任何代理的图像。传递 None 以仅列出没有代理范围的映像。
  • thread_id str | None- 可选的确切线程过滤器。省略时，将返回任何线程的图像。传递 None 以仅列出没有线程范围的映像。
  • metadata_filter dict[str, Any] | None- 应用于映像元数据的元数据过滤器。省略时，不应用元数据筛选。传递 None 以仅列出没有存储元数据的映像。
  • include_bytes bool- 是否在每个返回的记录中装入映像字节。省略或 False 时，不会加载映像字节。仅使用 image_id 和至少一个精确的用户、代理或线程范围筛选器将此值设置为 True。
  • limit int | None- 从后备存储请求的最大记录数（可选）。如果省略，存储可能会应用其默认列表上限。传递 None 以禁用该上限。
• 退货：匹配由后备存储排序的图像记录。
• 返回类型： list[ ImageRecord ]

示例

images = await client.list_images_async(
    user_id="u1",
    limit=10,
)
[image.id for image in images]
['img-1']

method list_memories

列出持久性类似内存的记录。

• 参数：
  • user_id str | None- 可选的确切用户过滤器。如果省略，将返回任何用户的内存。传递 None 以仅列出没有用户范围的内存。
  • agent_id str | None- 可选的精确代理过滤器。如果省略，将返回任何代理的记忆。传递 None 以仅列出没有代理范围的内存。
  • thread_id str | None- 可选的确切线程过滤器。省略时，将返回任何线程的内存。传递 None 以仅列出没有线程范围的内存。
  • metadata_filter dict[str, Any] | None- 元数据过滤器应用于内存元数据。省略时，不应用元数据筛选。传递 None 以仅列出没有存储元数据的内存。
  • limit int | None- 要返回的可选最大记录数。省略后，后备存储可能会应用其默认列表上限。传递 None 以禁用该上限。
• 返回：后备存储返回的类似内存的记录，包括 "memory"、"guideline"、"fact" 和 "preference" 记录。
• 返回类型： list[ MemoryRecord ]

示例

from oracleagentmemory.core import OracleAgentMemory
client = OracleAgentMemory(
    connection=db_pool,
    embedder=embedder,
    llm=llm,
)
client.add_memory("User likes pizza.", user_id="u1", memory_id="mem-1")
'mem-1'
[record.id for record in client.list_memories(user_id="u1", limit=10)]
['mem-1']

method list_memories_async（异步）

列表以异步方式持久保存类似内存的记录。

• 参数：
  • user_id str | None- 可选的确切用户过滤器。如果省略，将返回任何用户的内存。传递 None 以仅列出没有用户范围的内存。
  • agent_id str | None- 可选的精确代理过滤器。如果省略，将返回任何代理的记忆。传递 None 以仅列出没有代理范围的内存。
  • thread_id str | None- 可选的确切线程过滤器。省略时，将返回任何线程的内存。传递 None 以仅列出没有线程范围的内存。
  • metadata_filter dict[str, Any] | None- 元数据过滤器应用于内存元数据。省略时，不应用元数据筛选。传递 None 以仅列出没有存储元数据的内存。
  • limit int | None- 要返回的可选最大记录数。省略后，后备存储可能会应用其默认列表上限。传递 None 以禁用该上限。
• 返回：后备存储返回的类似内存的记录，包括 "memory"、"guideline"、"fact" 和 "preference" 记录。
• 返回类型： list[ MemoryRecord ]

示例

import anyio
from oracleagentmemory.core import OracleAgentMemory
client = OracleAgentMemory(
    connection=db_pool,
    embedder=embedder,
    llm=llm,
)
async def main():
    await client.add_memory_async("User likes pizza.", user_id="u1", memory_id="mem-1")
    records = await client.list_memories_async(user_id="u1", limit=10)
    return [record.id for record in records]
anyio.run(main)
['mem-1']

method list_messages

列出保留的聊天消息记录。

• 参数：
  • user_id str | None- 可选的确切用户过滤器。省略时，将返回任何用户的消息。传递 None 以仅列出没有用户范围的消息。
  • agent_id str | None- 可选的精确代理过滤器。省略时，将返回任何代理的消息。传递 None 以仅列出没有代理范围的消息。
  • thread_id str | None- 可选的确切线程过滤器。省略时，将返回任何线程的消息。传递 None 以仅列出没有线程范围的消息。
  • metadata_filter dict[str, Any] | None- 应用于消息元数据的元数据过滤器。省略时，不应用元数据筛选。传递 None 以仅列出没有存储元数据的消息。
  • limit int | None- 要返回的可选最大记录数。省略后，后备存储可能会应用其默认列表上限。传递 None 以禁用该上限。
  • include_image_bytes bool- 附加到返回消息的映像部分是否包括其存储的字节数。省略或 False 时，将返回附加的映像元数据，而不加载字节。设置为 True 以加载字节。
• 返回：后备存储返回的消息记录。
• 返回类型： list[ MessageRecord ]

示例

from oracleagentmemory.core import OracleAgentMemory
client = OracleAgentMemory(
    connection=db_pool,
    embedder=embedder,
    llm=llm,
)
thread = client.create_thread(thread_id="c1", user_id="u1")
message_id = thread.add_messages([{"role": "user", "content": "Hello"}])[0]
[record.id for record in client.list_messages(thread_id="c1", limit=10)] == [message_id]
True

method list_messages_async（异步）

列表以异步方式保留了聊天消息记录。

• 参数：
  • user_id str | None- 可选的确切用户过滤器。省略时，将返回任何用户的消息。传递 None 以仅列出没有用户范围的消息。
  • agent_id str | None- 可选的精确代理过滤器。省略时，将返回任何代理的消息。传递 None 以仅列出没有代理范围的消息。
  • thread_id str | None- 可选的确切线程过滤器。省略时，将返回任何线程的消息。传递 None 以仅列出没有线程范围的消息。
  • metadata_filter dict[str, Any] | None- 应用于消息元数据的元数据过滤器。省略时，不应用元数据筛选。传递 None 以仅列出没有存储元数据的消息。
  • limit int | None- 要返回的可选最大记录数。省略后，后备存储可能会应用其默认列表上限。传递 None 以禁用该上限。
  • include_image_bytes bool- 附加到返回消息的映像部分是否包括其存储的字节数。省略或 False 时，将返回附加的映像元数据，而不加载字节。设置为 True 以加载字节。
• 返回：后备存储返回的消息记录。
• 返回类型： list[ MessageRecord ]

示例

import anyio
from oracleagentmemory.core import OracleAgentMemory
client = OracleAgentMemory(
    connection=db_pool,
    embedder=embedder,
    llm=llm,
)
async def main():
    thread = await client.create_thread_async(thread_id="c1", user_id="u1")
    message_ids = await thread.add_messages_async(
        [{"role": "user", "content": "Hello"}]
    )
    records = await client.list_messages_async(thread_id="c1", limit=10)
    return [record.id for record in records] == message_ids
anyio.run(main)
True

method list_threads

列出持久的对话话题。

• 参数：
  • user_id str | None- 需要确切的用户过滤器。传递 None 以仅列出没有用户范围的线程。
  • agent_id str | None- 可选的精确代理过滤器。省略时，将返回任何代理的线程。传递 None 以仅列出没有代理作用域的线程。
  • metadata_filter dict[str, Any] | None- 元数据过滤器应用于线程元数据。省略时，不应用元数据筛选。传递 None 以仅列出没有存储元数据的线程。
  • limit int | None- 要返回的可选最大记录数。省略后，后备存储可能会应用其默认列表上限。传递 None 以禁用该上限。
• 返回：后备存储返回的线程记录。
• 返回类型： list[ ThreadRecord ]

示例

from oracleagentmemory.core import OracleAgentMemory
client = OracleAgentMemory(
    connection=db_pool,
    embedder=embedder,
    llm=llm,
)
client.create_thread(thread_id="c1", user_id="u1").thread_id
'c1'
[record.thread_id for record in client.list_threads(user_id="u1", limit=10)]
['c1']

method list_threads_async（异步）

异步列出持久的对话线程。

• 参数：
  • user_id str | None- 需要确切的用户过滤器。传递 None 以仅列出没有用户范围的线程。
  • agent_id str | None- 可选的精确代理过滤器。省略时，将返回任何代理的线程。传递 None 以仅列出没有代理作用域的线程。
  • metadata_filter dict[str, Any] | None- 元数据过滤器应用于线程元数据。省略时，不应用元数据筛选。传递 None 以仅列出没有存储元数据的线程。
  • limit int | None- 要返回的可选最大记录数。省略后，后备存储可能会应用其默认列表上限。传递 None 以禁用该上限。
• 返回：后备存储返回的线程记录。
• 返回类型： list[ ThreadRecord ]

示例

import anyio
from oracleagentmemory.core import OracleAgentMemory
client = OracleAgentMemory(
    connection=db_pool,
    embedder=embedder,
    llm=llm,
)
async def main():
    await client.create_thread_async(thread_id="c1", user_id="u1")
    records = await client.list_threads_async(user_id="u1", limit=10)
    return [record.thread_id for record in records]
anyio.run(main)
['c1']

method list_users

列出持久的用户概要信息记录。

• 参数：
  • metadata_filter dict[str, Any] | None- 元数据过滤器应用于用户配置文件元数据。省略时，不应用元数据筛选。传递 None 以仅列出没有存储元数据的配置文件。
  • limit int | None- 要返回的可选最大记录数。省略后，后备存储可能会应用其默认列表上限。传递 None 以禁用该上限。
• 退货：后备存储返回的用户配置文件记录。
• 返回类型： list[ UserProfileRecord ]

示例

from oracleagentmemory.core import OracleAgentMemory
client = OracleAgentMemory(
    connection=db_pool,
    embedder=embedder,
    llm=llm,
)
client.add_user("u1", "Prefers concise answers.", metadata={"source": "crm"})
'u1'
[record.id for record in client.list_users(metadata_filter={"source": "crm"})]
['u1']

method list_users_async（异步）

列表以异步方式保留了用户概要信息记录。

• 参数：
  • metadata_filter dict[str, Any] | None- 元数据过滤器应用于用户配置文件元数据。省略时，不应用元数据筛选。传递 None 以仅列出没有存储元数据的配置文件。
  • limit int | None- 要返回的可选最大记录数。省略后，后备存储可能会应用其默认列表上限。传递 None 以禁用该上限。
• 退货：后备存储返回的用户配置文件记录。
• 返回类型： list[ UserProfileRecord ]

示例

import anyio
from oracleagentmemory.core import OracleAgentMemory
client = OracleAgentMemory(
    connection=db_pool,
    embedder=embedder,
    llm=llm,
)
async def main():
    await client.add_user_async(
        "u1",
        "Prefers concise answers.",
        metadata={"source": "crm"},
    )
    records = await client.list_users_async(metadata_filter={"source": "crm"})
    return [record.id for record in records]
anyio.run(main)
['u1']

method search

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

• 参数：
  • query str- 自然语言查询字符串。
  • user_id str | None- 用户标识符过滤器。OracleAgentMemory 客户机搜索需要显式的用户范围，除非随 scope 一起提供。将具体 user_id 传递给目标用户，或将 None 传递给仅目标未定义范围的用户记录。
  • agent_id str | None- 可选代理标识符过滤器。在提供 scope 时忽略。
  • thread_id str | None- 可选线程标识符过滤器。在提供 scope 时忽略。
  • exact_user_match bool- 用户匹配是否应严格。OracleAgentMemory 客户机搜索需要精确的用户匹配并拒绝 False。在提供 scope 时忽略。
  • exact_agent_match bool- 代理匹配是否应严格。在提供 scope 时忽略。
  • exact_thread_match bool- 线程匹配是否应严格。在提供 scope 时忽略。
  • 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": "profile_import"}（表示标量字段）、metadata_filter={"prefs": {"category": "travel"}}（表示嵌套字段）和 metadata_filter={"tags": ["survey", "travel"]}（表示完全匹配列表）。组合条件以要求所有条件：

    metadata_filter={
        "source": "profile_import",
        "prefs": {"category": "travel"},
        "tags": ["survey", "travel"],
    }

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

    metadata_filter={
        "source": "profile_import",
        "tags": {
            "$array_contains": "travel",
            "$not": {"$array_contains": "archived"},
        },
    }

  • include_invalid_results bool- 结果是否包括处于无效状态的记录。省略此参数或传递 True 以包含这些参数。传递 False 以将其排除。
  • num_hops int- 从每个直接内存结果跟踪的内存链路边缘数。支持从 0 到 5 的值；仅省略直接结果。扩展遵循任一方向的链接。
  • max_linked_results int- 附加到每个直接结果的所有跃点的最大链接内存。忽略 100 的缺省值；传递 0 以不返回链接的上下文。
  • scope SearchScope- 可选的预生成搜索范围。请提供 scope 或显式标识符和完全匹配参数，而不是两者。OracleAgentMemory 客户机搜索要求解析的范围包含带有 exact_user_match=True 的显式 user_id。使用 user_id=None 仅针对未界定的用户记录。
• 退货：按相关性降低排序的搜索结果。该列表可以包含少于 max_results 个条目。
• 返回类型： list[SearchResult]
• 引发：ValueError - 如果 scope 与显式标识符或完全匹配参数组合，如果 max_results 小于 1，如果 metadata_filter 不是字典或 None，或者实施拒绝解析的客户机搜索范围。OracleAgentMemory 客户机搜索会拒绝省略的用户范围并拒绝 exact_user_match=False。

注释

显式 None 范围值仍遵循已解析的确切匹配规则：exact_*_match=False 保持该维不受约束，而 exact_*_match=True 仅匹配该维上未定义的记录。

method search_async（异步）

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

• 参数：
  • query str- 自然语言查询字符串。
  • user_id str | None- 用户标识符过滤器。OracleAgentMemory 客户机搜索需要显式的用户范围，除非随 scope 一起提供。将具体 user_id 传递给目标用户，或将 None 传递给仅目标未定义范围的用户记录。
  • agent_id str | None- 可选代理标识符过滤器。在提供 scope 时忽略。
  • thread_id str | None- 可选线程标识符过滤器。在提供 scope 时忽略。
  • exact_user_match bool- 用户匹配是否应严格。OracleAgentMemory 客户机搜索需要精确的用户匹配并拒绝 False。在提供 scope 时忽略。
  • exact_agent_match bool- 代理匹配是否应严格。在提供 scope 时忽略。
  • exact_thread_match bool- 线程匹配是否应严格。在提供 scope 时忽略。
  • 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": "profile_import"}（表示标量字段）、metadata_filter={"prefs": {"category": "travel"}}（表示嵌套字段）和 metadata_filter={"tags": ["survey", "travel"]}（表示完全匹配列表）。组合条件以要求所有条件：

    metadata_filter={
        "source": "profile_import",
        "prefs": {"category": "travel"},
        "tags": ["survey", "travel"],
    }

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

    metadata_filter={
        "source": "profile_import",
        "tags": {
            "$array_contains": "travel",
            "$not": {"$array_contains": "archived"},
        },
    }

  • include_invalid_results bool- 结果是否包括处于无效状态的记录。省略此参数或传递 True 以包含这些参数。传递 False 以将其排除。
  • num_hops int- 从每个直接内存结果跟踪的内存链路边缘数。支持从 0 到 5 的值；仅省略直接结果。扩展遵循任一方向的链接。
  • max_linked_results int- 附加到每个直接结果的所有跃点的最大链接内存。忽略 100 的缺省值；传递 0 以不返回链接的上下文。
  • scope SearchScope- 可选的预生成搜索范围。请提供 scope 或显式标识符和完全匹配参数，而不是两者。OracleAgentMemory 客户机搜索要求解析的范围包含带有 exact_user_match=True 的显式 user_id。使用 user_id=None 仅针对未界定的用户记录。
• 退货：按相关性降低排序的搜索结果。
• 返回类型： list[SearchResult]
• 引发：ValueError - 如果 scope 与显式标识符或完全匹配参数组合，如果 max_results 小于 1，如果 metadata_filter 不是字典或 None，或者实施拒绝解析的客户机搜索范围。OracleAgentMemory 客户机搜索会拒绝省略的用户范围并拒绝 exact_user_match=False。

注释

显式 None 范围值仍遵循已解析的确切匹配规则：exact_*_match=False 保持该维不受约束，而 exact_*_match=True 仅匹配该维上未定义的记录。

method update_image

按标识符更新存储的图像记录。

• 参数：
  • image_id str- 要更新的图像记录的标识符。
  • image bytes- 可选替换映像字节数。提供字节以替换存储的映像。如果省略，将保留存储的图像。
  • description str | None- 可选的替换说明。省略时，将保留存储的描述。传递 None 将使用配置的 LLM 生成新说明。非空字符串将直接替换存储的说明和可搜索文本。
  • mime_type ImageMimeType- 替换映像字节的 MIME 类型。必须同时提供 image 和 mime_type。同时省略以保留存储的图像和 MIME 类型。
  • metadata dict[str, Any] | None- 可选的替换元数据映射。省略时，将保留存储的元数据。如果提供，它将替换存储的元数据对象；此 API 不深入合并元数据。
  • timestamp str | None- 此映像的可选新时间戳。省略时，将保留存储的时间戳。传递 None 以将其清除。
  • ttl_days int | None- 可选的到期刷新（天）。将此参数与 ttl_anchor 一起省略，以使当前失效保持不变。传递 None 以清除到期。附加到消息的图像的到期必须通过父消息进行更改。
  • ttl_anchor TimeToLiveAnchor- 用于到期刷新的可选生存时间锚。提供不带 ttl_days 的 ttl_anchor 将使用方案默认生存时间持续时间。刷新期间省略时，存储将使用 TimeToLiveAnchor.CREATED_AT。
  • **kwargs ( Any )- 实现会拒绝意外的关键字参数。
• 退货：更新的图像记录的标识符。
• 返回类型： str
• 引发：ValueError - 如果为附加到消息的图像提供了到期设置。

注释

省略的字段保持不变。此 API 不支持范围更新。元数据替换是整个对象替换，而不是递归 JSON 合并。

method update_image_async（异步）

通过配置的存储更新一个独立映像。

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

• 参数：
  • image_id str- 要更新的映像的标识符。
  • image bytes- 可选的替换原始映像字节数。
  • description str | None- 可选的替换说明。省略它以保留当前说明。传递 None 以使用配置的 LLM 生成新说明。
  • mime_type ImageMimeType- 提供替换映像字节时需要 MIME 类型。
  • metadata dict[str, Any] | None- 可选的替换元数据。
  • timestamp str | None- 可选替换事件时间戳。
  • ttl_days int | None- 可选的到期设置。将图像附加到消息时，无法通过此方法更改这些内容。
  • ttl_anchor TimeToLiveAnchor- 可选的到期设置。将图像附加到消息时，无法通过此方法更改这些内容。
  • kwargs Any
• 返回：更新的图像标识符。
• 返回类型： str
• 引发：ValueError - 如果为附加到消息的图像提供了到期设置。

method update_memory

按标识符更新存储的类似内存的记录。

• 参数：
  • memory_id str- 要更新的类似内存的记录标识符。
  • content str- 可选替换内容。提供一个字符串以替换存储的内容。如果省略，将保留存储的内容。省略 content 以保留当前值，或者使用 delete_memory() 删除记录。
  • metadata dict[str, Any] | None- 可选的替换元数据映射。省略时，将保留存储的元数据。如果提供，它将替换存储的元数据对象；此 API 不深入合并元数据。
  • timestamp str | None- 此内存的可选新时间戳。它表示创建内存的时间。省略时，将保留存储的时间戳。传递 None 以清除保存的时间戳并使用在存储中创建记录的时间。如果 ttl_anchor 为 TimeToLiveAnchor.TIMESTAMP，则不带时区的 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 client 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 时间戳将视为 UTC。
  • status RecordStatus- 此类似内存记录的可选替换生命周期状态。省略它以保留当前状态。
  • **kwargs ( Any )- 意外关键字参数将被拒绝。
• 返回：更新的类似内存的记录标识符。
• 返回类型： str

注释

省略的字段将从存储的记录中保留。存储的范围保持不变。元数据替换是整个对象替换，而不是递归 JSON 合并。

method update_memory_async（异步）

按标识符异步更新存储的类似内存的记录。

• 参数：
  • memory_id str- 要更新的类似内存的记录标识符。
  • content str- 可选替换内容。提供一个字符串以替换存储的内容。如果省略，将保留存储的内容。省略 content 以保留当前值，或者使用 delete_memory() 删除记录。
  • metadata dict[str, Any] | None- 可选的替换元数据映射。省略时，将保留存储的元数据。如果提供，它将替换存储的元数据对象；此 API 不深入合并元数据。
  • timestamp str | None- 此内存的可选新时间戳。它表示创建内存的时间。省略时，将保留存储的时间戳。传递 None 以清除保存的时间戳并使用在存储中创建记录的时间。如果 ttl_anchor 为 TimeToLiveAnchor.TIMESTAMP，则不带时区的 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 client 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 时间戳将视为 UTC。
  • status RecordStatus- 此类似内存记录的可选替换生命周期状态。省略它以保留当前状态。
  • **kwargs ( Any )- 意外关键字参数将被拒绝。
• 返回：更新的类似内存的记录标识符。
• 返回类型： str

注释

省略的字段将从存储的记录中保留。存储的范围保持不变。元数据替换是整个对象替换，而不是递归 JSON 合并。

示例

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

method update_record_link

更新一个存储关系的可变字段。

省略的值会保留。当 relation_type 更改为内置内存关系类型时，其固定反向标签将替换 opposite_relation_type。为 timestamp 或 metadata 传递 None 以清除该值。

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

示例

client.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 update_thread

持久保存线程元数据和持久的运行时配置更新。

• 参数：
  • thread_id str- 要更新的线程的标识符。
  • metadata dict[str, Any] | None- 对话线程的可选元数据更新。省略时，存储的元数据保持不变。显式传递 None 将清除存储的元数据。提供映射时，它将替换存储的元数据对象。
  • LLM ILlm- 返回的 OracleThread 实例的可选 LLM 覆盖。这不会保留，但会参与与 get_thread 和 create_thread 相同的验证规则。

  • extract_memories bool-

    自动内存提取的可选持久覆盖。

    已弃用

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

  • max_message_token_length int- 提取和汇总期间使用的最大提示时消息大小的可选持久覆盖。
  • message_shortening_input_token_limit int- 对于缩短超大消息时发送到 LLM 的最大摘录大小的可选持久覆盖。

  • memory_extraction_window int-

    提取窗口大小的可选持久覆盖。

    已弃用

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

  • context_summary_update_frequency int-

    自动刷新之前的最新有效汇总后的消息的可选持久覆盖。

    已弃用

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

  • memory_extraction_frequency int-

    可选的持久覆盖，表示附加的消息数会触发自动内存提取。

    已弃用

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

  • memory_extraction_token_limit int-

    用于提取和运行汇总提示预算的可选持久覆盖。

    已弃用

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

  • context_card_token_limit int- 用于构建上下文卡中包含的摘要和主题列表的 LLM 提示符的输入令牌预算的可选持久覆盖。

  • enable_context_summary bool-

    用于运行上下文汇总是否保持启用状态的可选持久覆盖。

    已弃用

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

  • memory_extraction_custom_instructions str | None-

    附加到内存提取系统提示符的可选持久定制说明。通过 None 将清除任何存储的线程级别定制指令；配置客户机级别缺省值时仍适用。

    已弃用

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

  • memory_extraction_inherit_message_metadata bool | Sequence[str]-

    从源消息复制到自动提取的存储器上的元数据的可选持久覆盖。

    已弃用

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

  • memory_extraction_config MemoryExtractionConfig- 可选的分组持久提取配置更新。提供的字段将写入存储的线程配置中，供以后加载的 OracleThread 实例和后台提取作业使用。省略的字段在存在时保留其保存的值。在保存图像上下文设置之前创建的线程会回退到客户机值，然后回退到 DISABLED，此时不存在保存的图像上下文。
  • image_input_limit_config ImageInputLimitConfig- 可选的持久原始映像和 LLM 映像请求限制更新。省略的字段保留存储的值；提供的字段由后续加载的线程实例使用。
  • search_config MemorySearchConfig- 用于存储线程的可选搜索配置。提供的配置由后续装入的线程实例使用。
  • **kwargs ( Any )- 其他特定于实现的选项。OracleAgentMemory 当前拒绝未知关键字参数。
• 返回：更新了反映持久元数据和运行时配置的 OracleThread 实例。
• 返回类型：OracleThread
• 增加：
  • KeyError - 如果此客户机实例不知道线程 ID。
  • ValueError - 如果在解析有效的运行时配置后没有 LLM 可用于自动内存提取。

注释

运行时配置通过存储的对话线程解析，加上传递给此调用的显式覆盖，匹配 get_thread 语义，然后再保留结果。省略的元数据和运行时配置更新是从存储的数据（而不是从任何以前加载的 OracleThread 实例）解析的，并且仅写入显式提供的元数据更新或持久的运行时配置覆盖。元数据替换是整个对象替换，而不是递归 JSON 合并。线程所有权通过此 API 不可变，因此 user_id 和 agent_id 保持不变。可变运行时状态（例如提取计数器）保持不变。

示例

from oracleagentmemory.core import OracleAgentMemory
client = OracleAgentMemory(
    connection=db_pool,
    embedder=embedder,
    llm=llm,
)
updated = client.update_thread(
    "c1",
    metadata={"flags": {"vip": True}},
    message_shortening_input_token_limit=12_000,
)
updated.message_shortening_input_token_limit
12000

method update_thread_async（异步）

异步持久保存更新的线程元数据和持久运行时配置。

• 参数：
  • thread_id str- 要更新的线程的标识符。
  • metadata dict[str, Any] | None- 对话线程的可选元数据更新。省略时，存储的元数据保持不变。显式传递 None 将清除存储的元数据。提供映射时，它将替换存储的元数据对象。
  • **kwargs ( Any )-update_thread() 接受的其他持久运行时配置更新和每次调用覆盖。
• 返回：更新了反映持久元数据和运行时配置的 OracleThread 实例。
• 返回类型：OracleThread

method wait_for_memory_extraction

等待此客户机启动更早的后台内存提取。

此方法等待已通过此 OracleAgentMemory 实例在此代理内存组件拥有的所有线程中启动的后台提取。它不等待此等待开始后启动提取，不等待其他代理内存组件启动提取，也不等待在另一个进程中运行的提取。此等待的提取失败计数为已完成。

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

示例

client = OracleAgentMemory(
    connection=db_pool,
    embedder=embedder,
    memory_extraction_config=MemoryExtractionConfig(extract_memories=False),
)
client.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(client.wait_for_memory_extraction_async(timeout=10))

图像输入限制

class oracleagentmemory.core.ImageInputLimitConfig

基准：object

配置原始映像和 LLM 映像请求限制。

省略的字段从下一个更广泛的配置范围继承。客户端字段继承 SDK 默认值，而每线程字段继承客户端配置。无法禁用验证，解析的值不能超过 SDK 的绝对最大值。

• 参数：
  • max_raw_image_bytes int- 一个映像的最大原始字节长度。SDK 默认值为 10 MiB，绝对最大值为 32 MiB。
  • max_images_per_llm_request int- 一个 LLM 请求中的最大映像数。SDK 默认值为 100，绝对最大值为 512。
  • max_total_raw_image_bytes_per_llm_request int- 一个 LLM 请求中映像的最大组合原始字节长度。排除文本、元数据、JSON 帧和 base64 扩展。SDK 默认值为 100 MiB，绝对最大值为 256 MiB。

示例

from oracleagentmemory.core import ImageInputLimitConfig
config = ImageInputLimitConfig(
    max_raw_image_bytes=16 * 1024 * 1024,
    max_images_per_llm_request=200,
)

内存提取

class oracleagentmemory.core.MemoryExtractionImageContext

基础：str、Enum

选择图像如何参与自动内存提取。

DISABLED 省略提取提示中的图像和图像说明。IMAGE 发送原始图像部分。CAPTION 将图像描述作为文本发送，并要求每个选定的图像都具有非空白描述。

CAPTION = ‘ CAPTION ’

将说明作为文本包含，并且每个选定图像都需要一个说明。

已禁用 = ‘ DISABLED ’

请勿在提取提示中包括图像或图像说明。

图像 = ‘ IMAGE ’

在提取提示中包含原始图像部分。

MEMORY = ‘ MEMORY ’

当前不支持图像特定的内存提取。

class oracleagentmemory.core.MemoryExtractionConfig

基准：object

用于自动内存提取的分组设置。

将此对象传递到 OracleAgentMemory、create_thread、get_thread 或 update_thread 以配置自动提取。extraction_mode 和后台队列设置还控制自动图像描述生成。每个字段都独立解析。为操作提供的值优先，后跟保存的线程值、客户机值和 SDK 默认值。新线程和独立线程没有已保存的线程值。

• 参数：
  • memory_extraction_window int- 用于提取提示的“最近消息”窗口。-1 表示提取提示仅使用新添加的消息。如果省略，请使用上面的解析顺序。
  • context_summary_update_frequency int- 在自动刷新最新的有效摘要之后的消息数。启用内存提取时，将在每次到期提取后进行检查，因此以后可能会刷新。每次检查时值小于或等于 0 刷新。如果省略，请使用上面的解析顺序。
  • memory_extraction_frequency int- 运行内存提取之间的附加消息数。每次附加后 0 提取下面的值。如果省略，请使用上面的解析顺序。
  • memory_extraction_token_limit int- 用于提取和摘要提示的输入令牌预算。低于 1 的值将禁用提示预算限制。如果省略，请使用上面的解析顺序。
  • extract_memories bool- 是否启用自动内存提取。设置为 False 可禁用自动提取，并允许在不使用提取 LLM 的情况下执行操作。如果省略，请使用上面的解析顺序。
  • enable_context_summary bool- 提取提示是否维护和使用正在运行的上下文摘要。如果省略，请使用上面的解析顺序。
  • memory_extraction_custom_instructions str | None- 附加到提取系统提示符的可选调用方指令。在 update_thread 上传递 None 以清除存储的线程级别指令。如果省略，请使用上面的解析顺序。
  • memory_link_extraction_custom_instructions str | None- 附加到自动链路解析系统提示符的可选调用方指令。在 update_thread 上传递 None 以清除存储的线程级别指令。如果省略，请使用上面的解析顺序。当 memory_link_extraction_mode 为 MemoryLinkExtractionMode.DISABLED 时，将忽略此设置。
  • memory_extraction_image_context oracleagentmemory.core.extractors.memoryextractionconfig.MemoryExtractionImageContext- 选择提取期间使用的图像表示形式。DISABLED 省略提示中的图像和图像描述，IMAGE 发送原始图像部分，CAPTION 将图像描述作为文本发送，并要求每个选定的图像都具有非空白描述。当前不支持 MEMORY。省略时，先使用保存的线程值，然后使用客户机值，再使用 DISABLED。忽略此字段从不启用图像处理。
  • memory_extraction_inherit_message_metadata bool | collections.abc.Sequence[str]- 控制从源消息复制到提取的内存中的元数据。True 复制所有源消息元数据，False 不复制任何内容，而序列仅复制匹配的顶层元数据键。如果省略，请使用上面的解析顺序。
  • extraction_mode oracleagentmemory.core.extractors.memoryextractionconfig.MemoryExtractionMode- 控制自动内存提取和映像说明生成何时运行。MemoryExtractionMode.INLINE 在 write 方法返回之前完成它们。原始写入成功并尝试将派生的工作排队后，MemoryExtractionMode.BACKGROUND 将返回。在后台模式下，生成的描述和派生的记忆可能会在以后出现，或者如果工作无法完成，可能永远不会写入。例如，update_message() 可以在以后读取的内存反映更新的消息内容之前返回。如果省略，请使用上面的解析顺序。SDK 默认值为 BACKGROUND。设置 extract_memories=False 将禁用内存提取，但不禁用映像说明生成。
  • memory_link_extraction_mode oracleagentmemory.core.extractors.memoryextractionconfig.MemoryLinkExtractionMode- 如何解析新提取的内存的现有内存链接。DURING_EXTRACTION 在提取请求中包括有界候选项。POST_EXTRACTION 对提取批使用另一个链接解析请求。DISABLED 不创建自动链接。如果省略，请使用上面的解析顺序。SDK 默认值为 POST_EXTRACTION。
  • memory_link_extraction_token_limit int- 一次提取通过后所有提取链接解析请求的输入令牌总预算。低于 1 的值将禁用其提示预算。当 memory_link_extraction_mode 为 DURING_EXTRACTION 或 DISABLED 时，将忽略此设置。对 add_memory(autonomous_linking=True) 的调用独立于提取模式使用相同的后存储解析程序和预算。如果省略，请使用上面的解析顺序。
  • background_extraction_queue_full_behavior oracleagentmemory.core.extractors.memoryextractionconfig.BackgroundExtractionQueueFullBehavior- 在后台模式下，控制自动提取或图像描述生成无法立即排队时会发生什么情况。DROP 记录警告并继续，无需等待。WAIT_THEN_DROP 将等待队列容量直到配置的超时，然后记录警告并继续。WAIT_THEN_RAISE 等待队列容量，直到配置的超时，然后在原始写入成功后引发 TimeoutError。如果省略，请使用上面的解析顺序。SDK 默认值为 DROP。
  • background_extraction_queue_put_timeout_seconds float- 在后台模式下，当 background_extraction_queue_full_behavior 为 WAIT_THEN_DROP 或 WAIT_THEN_RAISE 时，自动提取或图像描述生成等待队列容量的最大秒数。如果省略，请使用上面的解析顺序。SDK 默认值为 300.0 秒。

示例

from oracleagentmemory.core import (
    MemoryExtractionImageContext,
    MemoryExtractionConfig,
    MemoryExtractionMode,
    MemoryLinkExtractionMode,
)
config = MemoryExtractionConfig(
    extract_memories=True,
    memory_extraction_image_context=MemoryExtractionImageContext.CAPTION,
    extraction_mode=MemoryExtractionMode.BACKGROUND,
    memory_link_extraction_mode=MemoryLinkExtractionMode.POST_EXTRACTION,
    memory_link_extraction_token_limit=8_000,
)

提取或图像描述无法立即排队时应执行的操作。

省略的值解析为 DROP。

在等待模式下后台工作等待队列容量的最大秒数。

省略的值解析为 300.0 秒。

自动刷新之前在最新的有效汇总之后的消息。

每次检查时值小于或等于 0 刷新。

OAM 是否维护线程读取和提取提示的上下文摘要。

提取和图像描述是内嵌运行还是后台运行。

省略的值解析为 BACKGROUND。

运行提取之间的消息；每次附加后，值低于 0 提取。

图像表示；省略解析为线程、客户机，然后解析为 DISABLED。

源消息元数据已复制到提取的内存中。

提示的输入令牌预算；低于 1 的值将禁用限制。

用于提取提示的近期消息窗口；-1 仅使用新消息。

附加到自动链路解析提示的可选调用方指令。

如何为提取的记忆解析自动链接。

省略的值解析为 POST_EXTRACTION。

POST_EXTRACTION 链接解析的输入标记预算合计。

低于 1 的值将禁用限制。

class oracleagentmemory.core.MemoryExtractionMode

基础：str、Enum

控制何时运行自动提取和映像说明。

INLINE 在写入方法返回之前完成派生的工作。原始写入成功并尝试将该工作排队后，BACKGROUND 将返回。背景工作是最好的努力：生成的描述和派生的记忆可能稍后出现，或者如果无法完成，可能永远不会写。

后台 = ‘ BACKGROUND ’

在原始写入后返回并在后台运行派生工作。

内嵌 = ‘ INLINE ’

在返回写入之前完成提取和图像说明。

class oracleagentmemory.core.BackgroundExtractionQueueFullBehavior

基础：str、Enum

控制在配置的后台工作无法及时排队时发生的情况。

尽管具有特定于提取的名称，但此设置也适用于在后台模式下自动生成图像描述。

删除 = ‘ DROP ’

记录警告，并在队列容量不可用时立即继续。

WAIT_THEN_DROP = ‘ WAIT_THEN_DROP ’

等待队列容量达到配置的超时，然后记录警告并继续。

WAIT_THEN_RAISE = ‘ WAIT_THEN_RAISE ’

等待队列容量达到配置的超时，然后引发 TimeoutError。