存储和方案

此页介绍 Oracle Agent Memory SDK 使用的核心存储抽象和方案控制。

存储 API

存储写入语义

存储写入在应用程序存储的文本与存储用于检索的有效负载之间保持清晰的分隔。大多数应用程序可以使用内存级和线程级 API，让存储为向量、关键字或混合检索准备所需的搜索行。较低级别的存储 API 公开了 index_texts、index_text、embeddings 和 embedding 以进行高级集成，这些集成已经知道应使用哪些文本或向量进行检索。

把每个写成两个相关的部分：

add() 中的 contents 和 update() 中的 content 控制由 get()、list() 和搜索结果返回的存储记录内容。
add() 中的 index_texts 和 update() 中的 index_text 控制写入存储检索行的文本。搜索使用这些行，然后返回原始逻辑记录。

update() 还接受 text 作为已过时的兼容性参数。在新代码中使用 content；提供 text 将发出弃用警告。

如果未提供搜索覆盖或显式嵌入，存储将使用解析的存储文本作为检索文本。配置分块时，存储将分块非空文本。空文本存储记录文本，但不提供检索文本。

下表介绍了在考虑显式向量有效负载之前如何选择检索文本。

存储级别检索有效负载

输入	`add()`	`update()`
省略 `index_texts` 或 `index_text`	每个记录都使用其解析的 `contents` 值进行检索。	替换 `content` 值用于检索。如果还省略了 `content`，则仅嵌入更新会重用记录的现有检索文本行。
字符串 `index_texts` 条目或字符串 `index_text`	该字符串将替换该记录的检索文本。存储可以在写入检索行之前将其分块。	该字符串将替换该记录的检索文本。存储可以在写入检索行之前将其分块。
`list[str]` `index_texts` 条目或 `list[str]` `index_text`	该列表被视为调用方拥有的块。每个非空字符串都写为一个检索行，并且存储不会再次将其分块。	该列表被视为调用方拥有的块。每个非空字符串都写为一个检索行，并且存储不会再次将其分块。
`None` `index_texts` 条目或 `index_text=None`	外部 `index_texts` 列表中的 `None` 表示“将存储的内容用于此记录”。	除非还提供了 `content`，否则 `index_text=None` 将清除检索行，同时将存储的内容保持不变。
空字符串或空块列表	存储记录内容，不提供该记录的检索文本。	在提供 `content` 时更新记录内容，并清除该记录的检索文本。

显式嵌入是可选的。如果省略了本地向量存储，则当配置本地向量存储时，存储将从检索文本派生本地向量；关键字或混合存储也可以使用仅文本检索行。当提供显式 embeddings 或 embedding 值时，存储将直接写入这些向量，并且不会为这些向量调用其嵌入器。

在 add() 中，embeddings=None 的行为类似于省略 embeddings。在 update() 中，embedding=None 是显式的：存储根据 content 和 index_text 保留或重写检索文本，但存储没有本地向量的行。如果同时省略 content 和 index_text，则会从现有检索行中清除向量。

向量形状告诉商店调用方正在获取多少块所有权：

一个向量表示一个向量用于整个检索文本。存储不会拆分显式向量的文本。如果该检索文本为空，则可以存储向量而不使用配套块文本。
多个向量表示每个调用方拥有的块一个向量。提供匹配的 index_texts 或 index_text 块列表，或者使用仅嵌入的 update() 重用记录的现有检索文本行。
向量计数必须与块计数匹配，并且一个 add() 调用中的所有显式向量必须具有相同的维。
仅当没有检索文本行与其对齐时，才允许空的每记录向量有效负载。

某些组合被拒绝，因此存储的文本、检索文本和向量不会分开。通过 content=None 将清除存储的内容和检索行，因此不能将其与非空的 index_text 或 embedding 值组合使用；操作者概要信息记录不支持 content=None。弃用的 text 参数具有相同的行为。在 update() 中传递 index_text=None 表示“清除检索行”，因此不允许在同一调用中执行非空的显式嵌入。多个显式向量需要显式块文本，除非更新仅嵌入且现有检索行已提供块文本。

class `oracleagentmemory.core.OracleMemoryStore`

基础：IMemoryStore

OracleAgentMemory 使用的公用存储接口。

存储实施负责持久保存文本记录并对它们执行相似性搜索。定义了同步和异步入口点，以便更高级别的 API 可以在不复制特定于存储的逻辑的情况下公开匹配的同步/异步曲面。

method `add`

将记录添加到商店。

参数：
- contents Sequence[str | Mapping[str, object] | Sequence[MessageContent] | bytes | None]- 记录有效负载的只读序列。消息条目可以包含有序的 MessageContent 部分，而线程概要条目可以是映射。除非提供了 index_texts 或 embeddings，否则文本值也用于语义索引。当文本值为 None 时，实现可能会回退到 metadata["content"]。将保留显式空字符串。
- record_type str- 要创建的逻辑记录类型，例如 "message"、"memory"、"guideline"、"fact"、"preference"、"user_profile"、"agent_profile" 或 "thread_summary"。
- index_texts list[str | list[str] | None]- 仅用于语义索引的可选替代有效负荷。如果提供，外部列表必须与文本输入对齐。每个条目可以是一个字符串，存储可以在内部分块，也可以是一个非空字符串列表，存储将其视为调用方拥有的块，不能再次拆分。
- embeddings list[list[float] | ndarray | list[list[float] | ndarray]]- 与文本输入对齐的可选预计算嵌入向量。每个记录条目可以是该记录的嵌入向量或块嵌入向量的列表。如果提供，存储必须直接使用这些向量，而不是调用其嵌入器。一个记录的多个向量需要匹配 index_texts 块列表，因此文本和向量块边界是显式的。如果未提供，存储通常从其配置的嵌入程序派生语义状态，但特定于实现的文本感知索引模式也可能允许没有文本感知写入。
- record_ids str | None | list[str | None]- 可选的调用方可见标识符。单个字符串可用于单记录插入，而列表必须与文本输入对齐。省略此字段时将返回生成的标识符。
- thread_ids str | None | list[str | None]- 与插入的记录关联的可选线程标识符。标量值可以在对齐的文本输入之间广播。
- user_id str | None | list[str | None]- 与插入的记录关联的可选用户标识符。标量值可以在对齐的文本输入之间广播。
- agent_ids str | None | list[str | None]- 与插入的记录关联的可选代理标识符。标量值可以在对齐的文本输入之间广播。
- roles str | None | list[str | None]- 可选消息角色，例如 "user" 或 "assistant"。标量值可以在对齐的文本输入之间广播。仅当 record_type 为 "message" 时使用。
- timestamps str | None | list[str | None]- 与记录一起保存的可选时间戳。每个时间戳都表示与记录关联的事件。标量值可以在对齐的文本输入之间广播。省略项或 None 项存储 NULL 事件时间戳；读取项使用记录创建时间作为有效时间戳。
- metadata dict[str, Any] | None | list[dict[str, Any] | None]- 可选的调用方提供的元数据字典。如果省略了文本值，而不是显式设置为 ""，则元数据可以包括 "content" 作为回退源。当 record_type="image" 时，每个映像写入都需要具有 "image/png"、"image/jpeg" 或 "image/webp" 之一的 "image_mime_type"。商店使用此字段保存图像，但不会将其作为记录元数据的一部分返回。
- ttl_days int | None | list[int | None]- 支持过期记录的可选生存时间（以天为单位）。省略此参数以使用存储默认值。为不应过期的记录传递 None。标量值可以在对齐的文本输入之间广播。
- ttl_anchor TimeToLiveAnchor | list[TimeToLiveAnchor]- 可选的生存时间锚。使用 TimeToLiveAnchor.CREATED_AT 可相对于存储的创建时间到期，使用 TimeToLiveAnchor.TIMESTAMP 可相对于每个记录的事件时间戳到期。如果省略，则实施将使用 TimeToLiveAnchor.CREATED_AT。
- statuses RecordStatus | list[RecordStatus]- 记录的可选生命周期状态或状态。省略此项以存储 RecordStatus.VALID。
- **store_kwargs ( Any )- 特定于实现的写入选项，转发到具体存储。
返回类型： list[str]

注释

当调用方已具有一个或多个 PendingRecordBatch 对象时，请使用 add_batches()。

返回：插入记录的标识符，其逻辑顺序与输入相同。
返回类型： List[str]
参数：
- 内容 Sequence[str | Mapping[str, object] | Sequence[MessageContent] | bytes | None]
- record_type str
- index_texts list[str | list[str] | None]
- embeddings（嵌入）list[list[float] | ndarray | list[list[float] | ndarray]]
- record_id str | None | list[str | None]
- thread_id str | None | list[str | None]
- user_ids str | None | list[str | None]
- agent_ids str | None | list[str | None]
- 角色 str | None | list[str | None]
- timestamps（时间戳）str | None | list[str | None]
- metadata（元数据）dict[str, Any] | None | list[dict[str, Any] | None]
- ttl_days int | None | list[int | None]
- ttl_anchor TimeToLiveAnchor | list[TimeToLiveAnchor]
- statuses RecordStatus | list[RecordStatus]
- store_kwargs Any

method `add_agent`（抽象）

添加代理概要记录。

参数：
- agent_id str- 代理配置文件的稳定标识符。
- information str- 描述代理的自由格式文本。
- metadata dict[str, Any] | None- 存储在代理配置文件行上的可选元数据映射。
退货：已创建的代理概要信息记录的标识符。
返回类型： str

method `add_agent_async`（异步）

异步添加代理概要信息记录。

参数：
- agent_id str- 代理配置文件的稳定标识符。
- information str- 描述代理的自由格式文本。
- metadata dict[str, Any] | None- 存储在代理配置文件行上的可选元数据映射。
退货：已创建的代理概要信息记录的标识符。
返回类型： str

method `add_async`（异步）

将面向行的记录异步添加到存储中。

接受相同的参数并返回与 add() 相同的标识符。

参数：
- 内容 Sequence[str | Mapping[str, object] | Sequence[MessageContent] | bytes | None]
- record_type str
- index_texts list[str | list[str] | None]
- embeddings（嵌入）list[list[float] | ndarray | list[list[float] | ndarray]]
- record_id str | None | list[str | None]
- thread_id str | None | list[str | None]
- user_ids str | None | list[str | None]
- agent_ids str | None | list[str | None]
- 角色 str | None | list[str | None]
- timestamps（时间戳）str | None | list[str | None]
- metadata（元数据）dict[str, Any] | None | list[dict[str, Any] | None]
- ttl_days int | None | list[int | None]
- ttl_anchor TimeToLiveAnchor | list[TimeToLiveAnchor]
- statuses RecordStatus | list[RecordStatus]
- store_kwargs Any
返回类型： list[str]

method `add_batches`

将调用者准备的逻辑批处理添加到存储。

参数：
- batches（批处理）list[PendingRecordBatch]- 要保留的完全准备的逻辑批处理。每个批处理应具有自己的每记录字段，例如 record_type、范围值、角色、时间戳和元数据。
- **store_kwargs ( Any )- 特定于实现的写入选项，转发到具体存储。
返回：已插入记录的标识符，其逻辑顺序与输入批和行相同。
返回类型： List[str]

示例

store.add_batches(
    [
        PendingRecordBatch(
            contents=["pizza batch"],
            record_type="memory",
            record_ids="mem-batch-docs",
        )
    ]
)
['mem-batch-docs']

method `add_batches_async`（异步）

将呼叫者准备的逻辑批处理异步添加到存储中。

接受相同的参数并返回与 add_batches() 相同的标识符。

参数：
- 批 list[PendingRecordBatch]
- store_kwargs Any
返回类型： list[str]

method `add_relations`（抽象）

存储一个或多个定向关系。

标量值在源 - 记录批中广播。列表值必须具有相同的长度。一个端点对只能存储一个方向。使用 opposite_relation_types 描述反向视图，而不是添加第二个反向关系。实施可能会限制它们保留的端点记录类型和关系标签。

参数：
- source_record_ids str | list[str]- 每个定向关系的源端的记录标识符或标识符。
- source_record_types str | list[str]-source_record_ids 的记录类型或类型。为所有来源提供一个值，或者为每个关系提供一个值。
- target_record_ids str | list[str]- 每个定向关系的目标端的记录标识符或标识符。
- target_record_types str | list[str]-target_record_ids 的记录类型或类型。为所有目标提供一个值，或者为每个关系提供一个值。
- relation_types str | list[str]- 定向关系标签或标签。为所有关系提供一个值，或者为每个关系提供一个值。
- opposite_relation_types str | list[str]- 每个关系的反向视图的可选标签或标签。对于内置内存关系类型，省略使用预定义的反向标签。对于自定义关系类型，省略在两个方向上使用相同的标签。
- relation_id str | None | list[str | None]- 可选的稳定标识符或标识符。省略此项可让存储生成标识符。
- timestamps str | None | list[str | None]- 要存储在关系上的可选时间戳或时间戳。
- metadata dict[str, Any] | None | list[dict[str, Any] | None]- 要存储在关系上的可选元数据对象。
返回：按输入顺序列出关系标识符。
返回类型： list[str]

示例

store.add_relations(
    "new", "memory", "old", "memory", "supersedes"
)
['relation-id']

method `add_relations_async`（异步）

异步存储一个或多个定向关系。

标量值在源 - 记录批中广播。列表值必须具有相同的长度。一个端点对只能存储一个方向。使用 opposite_relation_types 描述反向视图，而不是添加第二个反向关系。

参数：
- source_record_ids str | list[str]- 每个定向关系的源端的记录标识符或标识符。
- source_record_types str | list[str]-source_record_ids 的记录类型或类型。为所有来源提供一个值，或者为每个关系提供一个值。
- target_record_ids str | list[str]- 每个定向关系的目标端的记录标识符或标识符。
- target_record_types str | list[str]-target_record_ids 的记录类型或类型。为所有目标提供一个值，或者为每个关系提供一个值。
- relation_types str | list[str]- 定向关系标签或标签。为所有关系提供一个值，或者为每个关系提供一个值。
- opposite_relation_types str | list[str]- 每个关系的反向视图的可选标签或标签。对于内置内存关系类型，省略使用预定义的反向标签。对于自定义关系类型，省略在两个方向上使用相同的标签。
- relation_id str | None | list[str | None]- 可选的稳定标识符或标识符。省略此项可让存储生成标识符。
- timestamps str | None | list[str | None]- 要存储在关系上的可选时间戳或时间戳。
- metadata dict[str, Any] | None | list[dict[str, Any] | None]- 要存储在关系上的可选元数据对象。
返回：按输入顺序列出关系标识符。
返回类型： list[str]

示例

await store.add_relations_async(
    "new", "memory", "old", "memory", "supersedes"
)
['relation-id']

method `add_user`（抽象）

添加用户概要记录。

参数：
- user_id str- 用户配置文件的稳定标识符。数据库支持的实施可能会在省略附加的最终用户安全上下文时推断此值。
- information str- 描述用户的必需自由格式文本。
- metadata dict[str, Any] | None- 存储在用户配置文件行上的可选元数据映射。
退货：创建的用户配置文件记录的标识符。
返回类型： str

method `add_user_async`（异步）

异步添加用户概要信息记录。

参数：
- user_id str- 用户配置文件的稳定标识符。
- information str- 描述用户的自由格式文本。
- metadata dict[str, Any] | None- 存储在用户配置文件行上的可选元数据映射。
退货：创建的用户配置文件记录的标识符。
返回类型： str

method `delete`（抽象）

按标识符删除一个存储的记录。

参数：
- record_type str- 要删除的记录的逻辑类型。
- record_id str- 要删除的记录标识符。
- cascade bool- 在 True 时，对同一删除操作内请求的顶层目标应用任何存储支持的级联删除行为。这主要用于目标，例如拥有其他范围记录的操作者概要信息。例如，用户配置文件或代理配置文件级联可以删除自有线程本身、随这些线程删除的线程范围消息和类似内存的记录，以及任何剩余的直接操作者范围记录，例如消息、内存、准则、事实或首选项。对于 actor-profile 删除，当匹配的概要文件行已经不存在时，此范围清除仍可能运行。
返回：请求删除的顶层记录数，通常为 0 或 1。级联子行不单独计算，因此当缺少的角色配置文件触发范围清除时，这可能仍为 0。
返回类型： int

method `delete_async`（异步）

按标识符异步删除一个存储的记录。

参数：
- record_type str- 要删除的记录的逻辑类型。
- record_id str- 要删除的记录标识符。
- cascade bool- 在 True 时，对同一删除操作内请求的顶层目标应用任何存储支持的级联删除行为。这主要用于目标，例如拥有其他范围记录的操作者概要信息。例如，用户配置文件或代理配置文件级联可以删除自有线程本身、随这些线程删除的线程范围消息和类似内存的记录，以及任何剩余的直接操作者范围记录，例如消息、内存、准则、事实或首选项。对于 actor-profile 删除，当匹配的概要文件行已经不存在时，此范围清除仍可能运行。
返回：请求删除的顶层记录数，通常为 0 或 1。级联子行不单独计算，因此当缺少的角色配置文件触发范围清除时，这可能仍为 0。
返回类型： int

method `delete_relations`（抽象）

按标识符删除关系。

将根据保留的关系重新计算生命周期状态。

参数：relation_id str | list[str]- 要删除关系的标识符或标识符。
退货：已删除的关系数。
返回类型： int

示例

store.delete_relations("relation-id")
1

method `delete_relations_async`（异步）

按标识符异步删除关系。

将根据保留的关系重新计算生命周期状态。

参数：relation_id str | list[str]- 要删除关系的标识符或标识符。
退货：已删除的关系数。
返回类型： int

示例

await store.delete_relations_async("relation-id")
1

method `delete_thread`（抽象）

删除线程及其关联的存储数据。

参数：thread_id str- 要删除的线程的标识符。
返回：已删除的线程记录数，通常为 0 或 1。
返回类型： int

注释

这是用于删除存储管理的线程和线程范围记录的存储级别操作。当保留要求同时调用删除源消息和派生的线程范围内存数据时，首选线程删除，因为消息级别的删除并不意味着删除单独保留的派生记录。

method `delete_thread_async`（异步）

异步删除线程及其关联的存储数据。

参数：thread_id str- 要删除的线程的标识符。
返回：已删除的线程记录数，通常为 0 或 1。
返回类型： int

注释

method `get`（抽象）

按类型和标识符检索一个存储的记录。

参数：
- record_type str- 要检索的记录的逻辑类型，例如 "thread"、"message"、"memory"、"guideline"、"fact"、"preference"、"user_profile"、"agent_profile" 或 "image"。
- record_id str- 要检索的记录的标识符。
- include_bytes bool- 是否装入存储的映像字节数。对于消息记录，这将控制附加的图像是否包括其字节数。对于图像记录，它控制是否加载独立图像字节。此选项对其他记录类型没有影响。
返回：找到时存储的记录，否则为 None。"thread" 查找返回线程元数据、运行时配置、运行时状态以及存储支持持久性线程时填充的创建时间戳的 ThreadRecord。
退货类型：记录 | 无

method `get_async`（异步）

按类型和标识符异步检索一个存储的记录。

参数：
- record_type str- 要检索的记录的逻辑类型，例如 "thread"、"message"、"memory"、"guideline"、"fact"、"preference"、"user_profile"、"agent_profile" 或 "image"。
- record_id str- 要检索的记录的标识符。
- include_bytes bool- 是否装入存储的映像字节数。对于消息记录，这将控制附加的图像是否包括其字节数。对于图像记录，它控制是否加载独立图像字节。此选项对其他记录类型没有影响。
返回：找到时存储的记录，否则为 None。"thread" 查找返回线程元数据、运行时配置、运行时状态以及存储支持持久性线程时填充的创建时间戳的 ThreadRecord。
退货类型：记录 | 无

method `get_relation`（抽象）

在存储的源到目标方向中返回一个关系。

单独提供 relation_id，或者提供一个完整的源到目标端点元组。

参数：
- source_record_id str- 源记录标识符。省略 relation_id 时，对于其他端点元组字段是必需的。
- source_record_type str- 源记录类型。省略 relation_id 时，对于其他端点元组字段是必需的。
- target_record_id str- 目标记录标识符。省略 relation_id 时，对于其他端点元组字段是必需的。
- target_record_type str- 目标记录类型。省略 relation_id 时，对于其他端点元组字段是必需的。
- relation_type str- 定向关系标签。省略 relation_id 时，对于其他端点元组字段是必需的。
- relation_id str- 要直接匹配的关系标识符。单独提供此参数，而不是将其与端点元组字段组合。
返回值：匹配关系或不存在的 None。
返回类型：RecordRelation | 无

示例

store.get_relation(relation_id="relation-id")
RecordRelation(...)
store.get_relation(
    "source-id", "memory", "target-id", "fact", "supports"
)
RecordRelation(...)

method `get_relation_async`（异步）

按 ID 或端点元组异步检索一个关系。

单独提供 relation_id，或者提供一个完整的源到目标端点元组。

参数：
- source_record_id str- 源记录标识符。省略 relation_id 时，对于其他端点元组字段是必需的。
- source_record_type str- 源记录类型。省略 relation_id 时，对于其他端点元组字段是必需的。
- target_record_id str- 目标记录标识符。省略 relation_id 时，对于其他端点元组字段是必需的。
- target_record_type str- 目标记录类型。省略 relation_id 时，对于其他端点元组字段是必需的。
- relation_type str- 定向关系标签。省略 relation_id 时，对于其他端点元组字段是必需的。
- relation_id str- 要直接匹配的关系标识符。单独提供此参数，而不是将其与端点元组字段组合。
返回值：匹配关系或不存在的 None。
返回类型：RecordRelation | 无

示例

await store.get_relation_async(relation_id="relation-id")
RecordRelation(...)

method `list`（抽象）

列出一种记录类型的存储记录。

参数：
- record_type str- 要枚举的逻辑记录类型，例如 "thread"、"message"、"memory"、"guideline"、"fact"、"preference"、"user_profile"、"agent_profile" 或 "thread_summary" 或 "image"。
- limit int | None- 返回的最近记录的最大可选数量。省略时，实现可以应用安全上限，例如 MAX_LIST_LIMIT。传递 None 以禁用该上限并返回每个匹配记录。
- thread_id str | None- 精确的线程范围过滤器。如果省略，则不应用任何筛选。设置为 None 时，仅返回其 thread_id 为 None 的记录。未界定的记录类型会忽略此筛选器。如果 record_type 为 "thread"，则不应设置 thread_id；请使用 record_id 选择特定线程。
- user_id str | None- 精确的用户范围过滤器。如果省略，则不应用任何筛选。设置为 None 时，仅返回其 user_id 为 None 的记录。未界定的记录类型会忽略此筛选器。
- agent_id str | None- 精确代理范围过滤器。如果省略，则不应用任何筛选。设置为 None 时，仅返回其 agent_id 为 None 的记录。未界定的记录类型会忽略此筛选器。
- metadata_filter dict[str, Any] | None-
  
  元数据过滤器。如果省略，则不应用任何筛选。设置为 None 时，仅返回元数据为 None 的记录。设置为 dict 时，metadata_filter 中的条目将与 AND 语义组合。值不是字段级运算符字典的条目使用完全匹配语义：所请求的关键字必须存在于存储的元数据中。嵌套字典以递归方式进行匹配。标量和列表值通过完全相等进行匹配；列表顺序和长度也必须匹配。要测试数组成员关系，请使用字段级运算符字典，例如 {"tags": {"$array_contains": "prod"}}。"$array_contains" 的列表操作数表示必须存在所有列出的值；"$array_contains_any" 表示必须至少存在一个列出的值。使用 "$not" 可否定同一字段中的另一个字段级表达式，包括运算符字典或原始完全匹配值。正表达式失败时（包括缺少的字段）匹配负表达式；负数数组成员资格也匹配非数组字段。示例包括 metadata_filter={"source": "slack"}（表示标量字段）、metadata_filter={"review": {"status": "open"}}（表示嵌套字段）和 metadata_filter={"tags": ["prod", "urgent"]}（表示完全匹配列表）。组合条件以要求所有条件：
```
metadata_filter={
    "source": "slack",
    "review": {"status": "open"},
    "tags": ["prod", "urgent"],
}
```
- include_bytes bool- 附加到消息记录的映像记录或映像是否包括其存储的字节数。省略或 False 时，将返回映像说明和元数据，而不会加载字节。对于直接映像列表，请仅使用精确的 record_id 和至少一个精确的用户、代理或线程范围筛选器将其设置为 True。此选项对其他记录类型没有影响。
- record_id str- 精确的记录标识符过滤器。省略时，将返回具有任何标识符的记录。范围和元数据筛选器仍是附加约束条件。
返回：在返回的窗口中按从最早到最新顺序排序的记录。
返回类型： List［ Record（记录）］

method `list_async`（异步）

异步列出一种记录类型的存储记录。

参数：
- record_type str- 要枚举的逻辑记录类型，例如 "thread"、"message"、"memory"、"guideline"、"fact"、"preference"、"user_profile"、"agent_profile" 或 "image"。
- limit int | None- 返回的最近记录的最大可选数量。省略时，实现可以应用安全上限，例如 MAX_LIST_LIMIT。传递 None 以禁用该上限并返回每个匹配记录。
- thread_id str | None- 精确的线程范围过滤器。如果省略，则不应用任何筛选。设置为 None 时，仅返回其 thread_id 为 None 的记录。未界定的记录类型会忽略此筛选器。如果 record_type 为 "thread"，则不应设置 thread_id；请使用 record_id 选择特定线程。
- user_id str | None- 精确的用户范围过滤器。如果省略，则不应用任何筛选。设置为 None 时，仅返回其 user_id 为 None 的记录。未界定的记录类型会忽略此筛选器。
- agent_id str | None- 精确代理范围过滤器。如果省略，则不应用任何筛选。设置为 None 时，仅返回其 agent_id 为 None 的记录。未界定的记录类型会忽略此筛选器。
- metadata_filter dict[str, Any] | None-
  
  元数据过滤器。如果省略，则不应用任何筛选。设置为 None 时，仅返回元数据为 None 的记录。设置为 dict 时，metadata_filter 中的条目将与 AND 语义组合。值不是字段级运算符字典的条目使用完全匹配语义：所请求的关键字必须存在于存储的元数据中。嵌套字典以递归方式进行匹配。标量和列表值通过完全相等进行匹配；列表顺序和长度也必须匹配。要测试数组成员关系，请使用字段级运算符字典，例如 {"tags": {"$array_contains": "prod"}}。"$array_contains" 的列表操作数表示必须存在所有列出的值；"$array_contains_any" 表示必须至少存在一个列出的值。使用 "$not" 可否定同一字段中的另一个字段级表达式，包括运算符字典或原始完全匹配值。正表达式失败时（包括缺少的字段）匹配负表达式；负数数组成员资格也匹配非数组字段。示例包括 metadata_filter={"source": "slack"}（表示标量字段）、metadata_filter={"review": {"status": "open"}}（表示嵌套字段）和 metadata_filter={"tags": ["prod", "urgent"]}（表示完全匹配列表）。组合条件以要求所有条件：
```
metadata_filter={
    "source": "slack",
    "review": {"status": "open"},
    "tags": ["prod", "urgent"],
}
```
- include_bytes bool- 附加到消息记录的映像记录或映像是否包括其存储的字节数。省略或 False 时，将返回映像说明和元数据，而不会加载字节。对于直接映像列表，请仅使用精确的 record_id 和至少一个精确的用户、代理或线程范围筛选器将其设置为 True。此选项对其他记录类型没有影响。
- record_id str- 精确的记录标识符过滤器。省略时，将返回具有任何标识符的记录。范围和元数据筛选器仍是附加约束条件。
返回：在返回的窗口中按从最早到最新顺序排序的记录。
返回类型： List［ Record（记录）］

method `list_relations`（抽象）

按从源到目标的方向列出存储的关系。

参数：
- relation_type str- 要匹配的可选定向关系标签，例如 "supports" 或 "supersedes"。忽略以包括每个关系类型。
- source_record_id str- 要匹配的可选源记录标识符。
- source_record_type str- 要匹配的可选源记录类型。
- target_record_id str- 要匹配的可选目标记录标识符。
- target_record_type str- 要匹配的可选目标记录类型。
- limit int | None- 要返回的最早创建关系的最大可选数。省略时，实现可以应用安全上限，例如 MAX_LIST_LIMIT。通过 None 返回每个匹配的存储关系。
- metadata_filter dict[str, Any] | None- 元数据过滤器。如果省略，则不应用任何筛选。设置为 None 时，仅返回元数据为 None 的关系。设置为字典时，条目将与 AND 语义组合。嵌套字典使用递归完全匹配。标量和列表值需要完全相等；使用 {"tags": {"$array_contains": "prod"}} 匹配数组成员关系；使用 "$array_contains_any" 匹配列出的任何值；使用 "$not" 否定另一个字段表达式。
- relation_id str- 精确的关系标识符过滤器。如果省略，将返回与任何标识符的关系。其他筛选器仍是附加约束条件。
返回：按创建时间和标识符排序的关系。
返回类型： list[ RecordRelation ]

示例

store.list_relations(
    source_record_id="current-memory",
    relation_type="supports",
    metadata_filter={"source": "manual"},
)
[RecordRelation(...)]

method `list_relations_async`（异步）

以源到目标为方向异步列出关系。

参数：
- relation_type str- 要匹配的可选定向关系标签，例如 "supports" 或 "supersedes"。忽略以包括每个关系类型。
- source_record_id str- 要匹配的可选源记录标识符。
- source_record_type str- 要匹配的可选源记录类型。
- target_record_id str- 要匹配的可选目标记录标识符。
- target_record_type str- 要匹配的可选目标记录类型。
- limit int | None- 要返回的最早创建关系的最大可选数。省略时，实现可以应用安全上限，例如 MAX_LIST_LIMIT。通过 None 返回每个匹配的存储关系。
- metadata_filter dict[str, Any] | None- 元数据过滤器。如果省略，则不应用任何筛选。设置为 None 时，仅返回元数据为 None 的关系。设置为字典时，条目将与 AND 语义组合。嵌套字典使用递归完全匹配。标量和列表值需要完全相等；使用 {"tags": {"$array_contains": "prod"}} 匹配数组成员关系；使用 "$array_contains_any" 匹配列出的任何值；使用 "$not" 否定另一个字段表达式。
- relation_id str- 可直接匹配的可选关系标识符。
返回：按创建时间和标识符排序的关系。
返回类型： list[ RecordRelation ]

示例

await store.list_relations_async(
    source_record_id="current-memory", relation_type="supports"
)
[RecordRelation(...)]

method `list_thread_messages`（抽象）

列出存储于一个线程的消息历史记录。

参数：
- thread_id str- 应返回其消息的线程的标识符。
- last_n int | None- 要包含的最近消息的可选数量。省略时，将返回线程的所有存储消息。当与序列范围结合时，该限制适用于该范围内。
- range_start_seq_no int | None- 可选的包含下限序列边界。仅返回其 seq_no 至少是此值的消息。
- range_end_seq_no int | None- 可选的排斥序列上限边界。仅返回 seq_no 小于此值的消息。
- include_bytes bool- 附加到返回消息的映像部分是否包括其存储的字节数。省略或 False 时，将返回映像说明和元数据，而不会加载字节。
返回：在返回的窗口中按从最早到最新顺序排序的消息记录。
返回类型： List[ MessageRecord ]

method `list_thread_messages_async`（异步）

异步列出存储为一个线程的消息历史记录。

参数：
- thread_id str- 应返回其消息的线程的标识符。
- last_n int | None- 要包含的最近消息的可选数量。省略时，将返回线程的所有存储消息。当与序列范围结合时，该限制适用于该范围内。
- range_start_seq_no int | None- 可选的包含下限序列边界。仅返回其 seq_no 至少是此值的消息。
- range_end_seq_no int | None- 可选的排斥序列上限边界。仅返回 seq_no 小于此值的消息。
- include_bytes bool- 附加到返回消息的映像部分是否包括其存储的字节数。省略或 False 时，将返回映像说明和元数据，而不会加载字节。
返回：在返回的窗口中按从最早到最新顺序排序的消息记录。
返回类型： List[ MessageRecord ]

method `search`（抽象）

按相似性搜索记录。

参数：
- query str | None- 自然语言查询。必须在省略 query_vector 时提供。
- query_vector list[float] | None- 可选的预计算查询嵌入。只能提供 query 和 query_vector 中的一个。
- k int- 要返回的最大结果数量。显式值必须至少为 1。这是上限：当筛选器限制过多、存在较少的非失效匹配记录或由于特定于实施的搜索行为时，调用返回的结果可能少于 k。
- thread_id str | None- 可选线程范围。
- user_id str | None- 可选的用户和代理范围过滤器。
- agent_id str | None- 可选的用户和代理范围过滤器。
- exact_user_match bool- 提供的每个范围标识符是否必须完全匹配。
- exact_agent_match bool- 提供的每个范围标识符是否必须完全匹配。
- exact_thread_match bool- 提供的每个范围标识符是否必须完全匹配。
- record_types set[str] | None- 要包括的记录类型的可选集。
- metadata_filter dict[str, Any] | None- 可选的元数据过滤器映射。metadata_filter 中的条目与 AND 语义组合。值不是字段级运算符字典的条目使用完全匹配语义：所请求的关键字必须存在于存储的元数据中。嵌套字典以递归方式进行匹配。标量和列表值通过完全相等进行匹配；列表顺序和长度也必须匹配。要测试数组成员关系，请使用字段级运算符字典，例如 {"tags": {"$array_contains": "prod"}}。"$array_contains" 的列表操作数表示必须存在所有列出的值；"$array_contains_any" 表示必须至少存在一个列出的值。使用 "$not" 可否定同一字段中的另一个字段级表达式，包括运算符字典或原始完全匹配值。正表达式失败时（包括缺少的字段）匹配负表达式；负数数组成员资格也匹配非数组字段。
- include_invalid_results bool- 结果是否包括处于无效状态的类似内存的记录。默认值为 True。传递 False 以将其排除。
- num_hops int- 从每个直接内存结果跟踪的内存链路边缘数。支持从 0 到 5 的值；0 将禁用图形扩展。
- max_linked_results int- 附加到每个直接结果的所有跃点的最大链接内存。0 会保留没有链接上下文的直接结果。默认为 100。
返回值：按增加距离排序的 (record, distance) 对。该列表可以包含少于 k 个条目。
返回类型： list[tuple[ Record ，float]]
引发：ValueError - 如果 k 小于 1。

示例

store.add(
    ["Searchable abstract memory"],
    record_type="memory",
    record_ids="mem-search-abstract-docs",
)
['mem-search-abstract-docs']
store.search("Searchable", 1, record_types={"memory"})[0][0].id
'mem-search-abstract-docs'

对标量元数据值进行筛选：

store.add(
    ["pizza release"],
    record_type="memory",
    record_ids="mem-search-meta-source-docs2",
    metadata={"source": "slack"},
)
['mem-search-meta-source-docs2']
any(
    record.id == "mem-search-meta-source-docs2"
    for record, _ in store.search(
        "pizza",
        k=3,
        metadata_filter={"source": "slack"},
    )
)
True

对嵌套元数据进行过滤：

store.add(
    ["pizza review"],
    record_type="memory",
    record_ids="mem-search-meta-review-docs2",
    metadata={"review": {"status": "open"}},
)
['mem-search-meta-review-docs2']
any(
    record.id == "mem-search-meta-review-docs2"
    for record, _ in store.search(
        "pizza",
        k=3,
        metadata_filter={"review": {"status": "open"}},
    )
)
True

完全匹配列表值，包括顺序：

store.add(
    ["pizza tags"],
    record_type="memory",
    record_ids="mem-search-meta-tags-docs2",
    metadata={"tags": ["prod", "urgent"]},
)
['mem-search-meta-tags-docs2']
any(
    record.id == "mem-search-meta-tags-docs2"
    for record, _ in store.search(
        "pizza",
        k=5,
        metadata_filter={"tags": ["prod", "urgent"]},
    )
)
True

当元数据数组包含值时进行筛选：

any(
    record.id == "mem-search-meta-tags-docs2"
    for record, _ in store.search(
        "pizza",
        k=5,
        metadata_filter={"tags": {"$array_contains": "prod"}},
    )
)
True

组合多个元数据条件。记录必须满足每个键：

store.add(
    ["pizza rollout"],
    record_type="memory",
    record_ids="mem-search-meta-combined-docs2",
    metadata={
        "source": "slack",
        "review": {"status": "open"},
        "tags": ["prod", "urgent"],
    },
)
['mem-search-meta-combined-docs2']
any(
    record.id == "mem-search-meta-combined-docs2"
    for record, _ in store.search(
        "pizza",
        k=5,
        metadata_filter={
            "source": "slack",
            "review": {"status": "open"},
            "tags": ["prod", "urgent"],
        },
    )
)
True

method `search_async`（异步）

按语义相似性异步搜索记录。

参数：
- query str | None-search 接受的同一查询文本。
- k int-search 接受的最大结果计数相同。显式值必须至少为 1。
- query_vector list[float] | None-search 接受的同一可选预计算查询嵌入。
- thread_id str | None-search 接受的相同可选范围过滤器。
- user_id str | None- 与 search 接受的可选范围过滤器相同。
- agent_id str | None- 与 search 接受的可选范围过滤器相同。
- exact_user_match bool-search 接受的相同完全匹配标志。
- exact_agent_match bool-search 接受的相同完全匹配标志。
- exact_thread_match bool-search 接受的相同完全匹配标志。
- record_types set[str] | None- 与 search 接受的可选记录类型过滤器相同。
- metadata_filter dict[str, Any] | None-search 接受的相同可选元数据过滤器，包括标量、嵌套、精确列表、数组成员身份以及 {"source": "slack"}、{"review": {"status": "open"}}、{"tags": ["prod", "urgent"]} 和 {"tags": {"$array_contains": "prod"}} 等组合条件。
- include_invalid_results bool-search 接受的相同生命周期状态结果选项。
- num_hops int-search 接受的相同图形扩展深度。
- max_linked_results int-search 接受的每直接结果链接内存限制相同。
返回：底层 search 调用返回的 (record, distance) 对。
返回类型： List[tuple[ Record ，float]]
引发：ValueError - 如果 k 小于 1。

method `update`（抽象）

更新存储的记录内容，嵌入数据、元数据、时间戳或到期。

参数：
- record_type str- 要更新的记录的逻辑类型。
- record_id str- 要更新的记录的标识符。
- content str | Mapping[str, object] | Sequence[MessageContent] | bytes | None- 规范替换内容。对于 message 记录，传递文本和图像内容部分的字符串或有序序列；使用 "" 将消息替换为空文本。对于类似内存的记录，存储可以接受 None 来清除存储的文本和关联的语义状态。省略参数以保持内容不变。请勿将其与 text 一起提供。
- index_text str | list[str] | None- 可选的替代语义有效负荷，用于重新计算或替换存储的搜索状态，而无需更改持久文本。门店可以对字符串进行内部分块。非空字符串列表被视为调用方拥有的块，不能再次拆分。某些实现也可能会将其单独保留为混合搜索文本。对于 image 记录，此字段将替换保留的图像描述。
- embedding list[float] | ndarray | list[list[float] | ndarray] | None- 可选的预计算嵌入向量或块嵌入向量列表。如果提供，则直接使用此项，且不调用嵌入器。多个向量需要匹配的 index_text 块列表或现有的存储块文本行。通过 None 在存储支持存储嵌入时显式清除存储嵌入。具有文本感知索引的存储还可以允许在没有嵌入或显式嵌入的情况下进行语义更新。
- metadata dict[str, Any] | None- 可选的替换元数据映射。传递 None 以在存储支持元数据时清除元数据。在此映射中替换映像 content 需要 "image_mime_type"。商店使用此字段保存图像，但不会将其作为记录元数据的一部分返回。
- timestamp str | None- 与记录一起保存的可选新时间戳。它表示创建记录的时间。省略此参数可使存储的时间戳保持不变。传递 None 以清除保存的时间戳，并在商店支持记录时使用将记录添加到商店的时间。
- ttl_days int | None- 可选的到期刷新（天）。将此参数与 ttl_anchor 一起省略，以保留当前的失效时间戳。传递 None 以清除到期。
- ttl_anchor TimeToLiveAnchor- 用于到期刷新的可选生存时间锚。将 TimeToLiveAnchor.CREATED_AT 用于记录创建时间，将 TimeToLiveAnchor.TIMESTAMP 用于在同一更新中提供的替换 timestamp，或者在省略 timestamp 时使用存储的事件时间戳。提供不带 ttl_days 的 ttl_anchor 将使用存储或方案默认生存时间持续时间。在刷新期间省略 ttl_anchor 时，实施将使用 TimeToLiveAnchor.CREATED_AT。
- status RecordStatus- 记录的可选替换生命周期状态。
- text str | None-
  
  content 的已弃用别名。传递 None 可在存储支持时显式清除存储的文本。请勿将其与 content 一起提供。
  
  已弃用
  
  自版本 26.8.0 起已废弃：此参数在 26.8.0 中已废弃，将在 27.1 中删除。请改用 content。
返回：更新的记录数（0 或 1）。返回值 0 表示未更新任何记录。
返回类型： int
引发：ValueError - 如果更新有效负载对存储无效，例如省略每个可选字段或提供冲突的语义参数。

method `update_async`（异步）

异步更新存储的记录内容，嵌入数据、元数据、时间戳或到期。

参数：
- record_type str- 要更新的记录的逻辑类型。
- record_id str- 要更新的记录的标识符。
- content str | Mapping[str, object] | Sequence[MessageContent] | bytes | None- 规范替换内容。对于 message 记录，传递文本和图像内容部分的字符串或有序序列；使用 "" 将消息替换为空文本。对于类似内存的记录，存储可以接受 None 来清除存储的文本和关联的语义状态。省略参数以保持内容不变。请勿将其与 text 一起提供。
- index_text str | list[str] | None- 可选的替代语义有效负荷，用于重新计算或替换存储的搜索状态，而无需更改持久文本。门店可以对字符串进行内部分块。非空字符串列表被视为调用方拥有的块，不能再次拆分。某些实现也可能会将其单独保留为混合搜索文本。对于 image 记录，此字段将替换保留的图像描述。
- embedding list[float] | ndarray | list[list[float] | ndarray] | None- 可选的预计算嵌入向量或块嵌入向量列表。如果提供，则直接使用此项，且不调用嵌入器。多个向量需要匹配的 index_text 块列表或现有的存储块文本行。通过 None 在存储支持存储嵌入时显式清除存储嵌入。具有文本感知索引的存储还可以允许在没有嵌入或显式嵌入的情况下进行语义更新。
- metadata dict[str, Any] | None- 可选的替换元数据映射。传递 None 以在存储支持元数据时清除元数据。在此映射中替换映像 content 需要 "image_mime_type"。商店使用此字段保存图像，但不会将其作为记录元数据的一部分返回。
- timestamp str | None- 与记录一起保存的可选新时间戳。它表示创建记录的时间。省略此参数可使存储的时间戳保持不变。传递 None 以清除保存的时间戳，并在商店支持记录时使用将记录添加到商店的时间。
- ttl_days int | None- 可选的到期刷新（天）。将此参数与 ttl_anchor 一起省略，以保留当前的失效时间戳。传递 None 以清除到期。
- ttl_anchor TimeToLiveAnchor- 用于到期刷新的可选生存时间锚。将 TimeToLiveAnchor.CREATED_AT 用于记录创建时间，将 TimeToLiveAnchor.TIMESTAMP 用于在同一更新中提供的替换 timestamp，或者在省略 timestamp 时使用存储的事件时间戳。提供不带 ttl_days 的 ttl_anchor 将使用存储或方案默认生存时间持续时间。在刷新期间省略 ttl_anchor 时，实施将使用 TimeToLiveAnchor.CREATED_AT。
- status RecordStatus- 记录的可选替换生命周期状态。省略它以保留当前状态。
- text str | None-
  
  content 的已弃用别名。传递 None 可在存储支持时显式清除存储的文本。请勿将其与 content 一起提供。
  
  已弃用
  
  自版本 26.8.0 起已废弃：此参数在 26.8.0 中已废弃，将在 27.1 中删除。请改用 content。
返回：更新的记录数（0 或 1）。返回值 0 表示未更新任何记录。
返回类型： int
引发：ValueError - 如果更新有效负载对存储无效，例如省略每个可选字段或提供冲突的语义参数。

method `update_relations`（抽象）

更新存储关系上的可变值。

省略的字段保持不变，但更改为内置内存关系类型会将其反向标签替换为固定反向。数据库支持的内存存储还会在关系类型更改后重新计算端点生命周期状态。

参数：
- relation_id str | list[str]- 要更新的关系的标识符或标识符。
- relation_types str | list[str]- 可选的替换定向关系标签或标签。省略此项以保留存储的标签。
- opposite_relation_types str | list[str]- 可选的替换反向关系标签或标签。传递标签以替换它，或者省略此参数以保留它。
- timestamps str | None | list[str | None]- 可选的替换时间戳或时间戳。传递 None 以清除存储的时间戳。
- metadata dict[str, Any] | None | list[dict[str, Any] | None]- 可选替换元数据对象或对象。提供的元数据将替换存储的对象；它不会合并。
返回：已更新的关系的标识符。
返回类型： list[str]

示例

store.update_relations(
    "relation-id", relation_types="supports"
)
['relation-id']

method `update_relations_async`（异步）

异步更新存储关系上的可变值。

参数：
- relation_id str | list[str]- 要更新的关系的标识符或标识符。
- relation_types str | list[str]- 可选的替换定向关系标签或标签。省略此项以保留存储的标签。
- opposite_relation_types str | list[str]- 可选的替换反向关系标签或标签。传递标签以替换它，或者省略此参数以保留它。
- timestamps str | None | list[str | None]- 可选的替换时间戳或时间戳。传递 None 以清除存储的时间戳。
- metadata dict[str, Any] | None | list[dict[str, Any] | None]- 可选替换元数据对象或对象。提供的元数据将替换存储的对象；它不会合并。
返回：已更新的关系的标识符。
返回类型： list[str]

示例

await store.update_relations_async(
    "relation-id", relation_types="supports"
)
['relation-id']

Oracle DB 存储

class `oracleagentmemory.core.OracleDBMemoryStore`

基础：OracleMemoryStore

数据库支持的消息、文档、内存和角色概要信息持久性。

创建 Oracle DB 存储。

参数：
- embedder IEmbedder | None- 当存储需要本地向量嵌入时使用的嵌入器。调用方始终提供预计算向量时，或者将关键字搜索与仅文本写入和文本查询一起使用时，可以是 None。SearchStrategy.HYBRID 在此处需要 OracleDBEmbedder，以便托管混合索引可以使用此嵌入器的数据库内模型。
- pool Any-Oracle DB 连接或池。通过原始连接可为此存储实例启用单会话模式：并发存储调用在本地进行序列化，以保留写入操作使用的行锁和事务处理假设。将连接池用于并发请求。
- schema_policy SchemaPolicy | str- 控制托管模式的打开或准备方式。默认为需要现有的新方案，且不进行 DDL 更改。对于由 memory_store_id 标识的存储，SchemaPolicy.CREATE_IF_NECESSARY 将在需要时创建或修复方案；SchemaPolicy.RECREATE 将删除并重建方案。较旧的方案版本需要先升级程序包方案，然后才能进行修复。设置 schema_owner 时，使用 SchemaPolicy.REQUIRE_EXISTING 进行常规跨方案访问，使用 SchemaPolicy.NO_CHECK 进行深度数据安全运行时访问。这两种方法都阻止了托管方案 DDL 的创建，包括方案创建、修复、重新创建和首次创建混合索引；在以拥有数据库用户的身份连接时执行这些操作，而无需使用 schema_owner。这两种模式都不会使存储成为只读：正常的内存读取和写入使用连接用户的有效数据库授权。对于 Deep Data Security 运行时访问，请使用 SchemaPolicy.NO_CHECK，并在 OracleMemoryEndUserSecurityContext 处于活动状态时创建存储。生成的存储要求每个后续数据库操作都有一个活动的最终用户上下文。NO_CHECK 以外的方案策略拒绝活动的最终用户上下文，因此方案生命周期工作不能意外地作为最终用户运行。
- vector_dim int | None- 用于本地向量存储的可选嵌入维。传递正整数以创建托管嵌入列和向量索引，并根据该维验证现有方案元数据。当此存储不需要本地向量存储时，传递 None 或省略该参数。关键字和混合搜索可以基于存储的搜索文本进行操作，而无需使用本地嵌入列。向量搜索需要本地向量存储。如果省略此参数并且有效搜索后端为向量搜索，则当有嵌入器可用时，存储将使用 embedder.embedding_dimension。
- table_name_prefix str-
  
  添加到托管表/索引名称的可选前缀。传递 this 或 memory_store_id，而不是两者。
  
  已弃用
  
  自版本 26.6.0 起已废弃：此参数在 26.6.0 中已废弃，将在 27.1 中删除。请改用 memory_store_id。
- memory_store_id str- 托管数据库内存存储的稳定 ID。重用同一 ID 重新打开同一托管存储。ID 联接到带下划线的托管数据库对象名称，因此它必须以字母开头，仅包含字母、数字和下划线，并且最多 16 个字符。传递 this 或 table_name_prefix，而不是两者。如果省略，则在省略 table_name_prefix 时，存储将使用 table_name_prefix 或无前缀默认值。创建、修复或重新创建连接用户方案中的存储需要该方案中的兼容 DBMS_AGENT_MEMORY_STORE 程序包。
- schema_owner str- 现有托管内存存储的可选方案所有者。省略此选项以使用连接用户的方案。pool 参数可以是原始数据库连接或连接池；当此选项属于对其他用户拥有的表具有授权的应用程序数据库用户时，请使用此选项。此选项仅用于对已创建的托管内存存储的运行时访问。使用 SchemaPolicy.REQUIRE_EXISTING 进行普通跨方案访问，或者使用 SchemaPolicy.NO_CHECK 为深度数据安全保护存储提供活动的最终用户安全上下文。在以方案所有者身份连接时创建、升级或重新创建托管内存存储，并忽略此选项。传递一个无引号的标识符；小写输入将规范化为大写，并且不支持带引号的区分大小写的模式所有者。向应用程序数据库用户授予 CREATE SESSION 和所需的对象权限；有关确切授权，请参见故障排除指南的 Database Users and Privileges 部分。或者，在运行时方案中公开同名的托管对象视图并省略 schema_owner；这仅受 SchemaPolicy.REQUIRE_EXISTING 支持。
- search_strategy SearchStrategy- 选择 search() 后端的 SearchStrategy 值。使用 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。
- memory_retention_config MemoryRetentionConfig- 数据库支持的消息和内存的可选内存保留配置。当新写入省略 ttl_days 时使用 MemoryRetentionConfig.default_ttl_days。MemoryRetentionConfig.max_ttl_days 将显式每记录持续时间夹在配置的最大值之上，并发出警告，如果设置，则使 ttl_days=None 使用该最大值，而不是创建非失效行。使用 SchemaPolicy.CREATE_IF_NECESSARY 时，显式配置会刷新现有最新托管方案上存储的元数据，但不会更新现有到期日期；省略该配置会保留现有设置。如果显式配置将 default_ttl_days 或 max_ttl_days 留在 NOT_SET_MARKER，SDK 将在比较或存储方案元数据之前将该属性解析为其默认值 (None)。根据记录中存储的预期信息、应用程序保留它的原因以及任何应用程序或监管保留承诺选择此配置。
引发：RuntimeError - 如果最终用户安全上下文在使用 SchemaPolicy.NO_CHECK 以外的模式策略处于活动状态，或者在没有活动的最终用户安全上下文的情况下打开或使用 NO_CHECK 运行时存储。

警告：SchemaPolicy.CREATE_IF_NECESSARY 可能比正常存储启动贵，因为它可能会在初始化成功之前修复托管方案对象。当方案可能包含多个行时，计划修复工作将作为维护操作。旧方案版本上的存储需要在初始化之前进行程序包方案升级。

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

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

创建该托管混合索引还会创建由托管方案命名的 DBMS_VECTOR_CHAIN 向量器首选项。该首选项存储已配置的 OracleDBEmbedder 模型中的轻量向量器配置元数据。可以使用 Oracle Text 首选项视图（例如 CTX_USER_PREFERENCES 和 CTX_USER_PREFERENCE_VALUES）对其进行检查。

method `add`

将记录添加到 Oracle DB 存储。

参数：
- contents Sequence[str | Mapping[str, object] | Sequence[MessageContent] | bytes | None]- 记录有效负载的只读序列。消息条目可以包含有序的 MessageContent 部分。线程概要条目可以是映射、成为 {"text": value} 对象的字符串或存储为 JSON null 的 None。文本值也用于搜索，除非提供 index_texts。对于其他记录类型，None 可能回退到 metadata["content"]。将保留显式空字符串。
- record_type str- 要创建的逻辑记录类型，例如 "message"、"memory"、"guideline"、"fact"、"preference"、"user_profile"、"agent_profile" 或 "thread_summary"。
- index_texts list[str | list[str] | None]- 用作搜索文本的可选替代有效负荷。使用此项可以控制由数据库支持的关键字或混合搜索索引。每个外部列表条目都与一个记录对齐。存储可能会对字符串条目进行分块。列表条目被视为调用方拥有的块，并按原样写入 RECORD_CHUNKS.chunk_text。如果还提供了 embeddings，则列表条目每个块仅需要一个向量；字符串条目仅接受该记录的单个向量。
- embeddings list[list[float] | ndarray | list[list[float] | ndarray]]-
  
  与 contents 对齐的可选预计算嵌入向量。每个记录条目可以是一个向量，也可以是一个块向量的列表。当配置本地向量存储时，这些向量将直接存储为记录的向量表示形式，而不是调用存储的嵌入器来创建用于写入的本地向量。单个向量表示整个语义文本，即使配置的块将以其他方式拆分它。多个块向量需要匹配的 index_texts 块列表。
  
  在 SearchStrategy.VECTOR 中，向量搜索根据存储的向量进行排名。在 SearchStrategy.HYBRID 或 SearchStrategy.KEYWORD 中，数据库支持的搜索按存储的搜索文本和 Oracle 管理的文本或混合索引状态进行排名，因此，添加时间嵌入仅影响任何配置的本地向量存储，而不影响该活动搜索策略。如果此存储配置了没有本地向量存储，请提供 index_texts 而不是 embeddings 以覆盖这些文本感知索引可见的文本。
- record_ids str | None | list[str | None]- 可选的调用方可见标识符。单个字符串可用于单记录插入，而列表必须与 contents 对齐。省略此字段时将返回生成的标识符。
- thread_ids str | None | list[str | None]- 与插入的记录关联的可选线程标识符。标量值可以在对齐的输入之间广播。
- user_id str | None | list[str | None]- 与插入的记录关联的可选用户标识符。标量值可以在对齐的输入之间广播。在 SchemaPolicy.NO_CHECK 运行时存储上省略时，存储将使用活动的最终用户安全上下文的用户名。显式传递 None 以保留未定义范围的用户 ID。
- agent_ids str | None | list[str | None]- 与插入的记录关联的可选代理标识符。标量值可以在对齐的输入之间广播。
- roles str | None | list[str | None]- 可选消息角色，例如 "user" 或 "assistant"。仅当 record_type 为 "message" 时使用。
- timestamps str | None | list[str | None]- 与记录一起保存的可选时间戳。每个时间戳都表示创建记录的时间。标量值可以在对齐的输入之间广播。省略或 None 项会保留事件时间戳未设置。当 ttl_anchor 为 TimeToLiveAnchor.TIMESTAMP 时，每个受影响的记录都必须具有具体的 ISO-8601 时间戳值。没有时区的 ISO-8601 时间戳将视为 UTC。
- metadata dict[str, Any] | None | list[dict[str, Any] | None]- 可选的元数据字典。元数据可以在省略文本值而不是设置为 "" 时将 "content" 作为回退源。映像写入需要 "image_mime_type" 以及 "image/png"、"image/jpeg" 或 "image/webp"。商店使用此字段保存图像，但不会将其作为记录元数据的一部分返回。
- ttl_days int | None | list[int | None] – Optional time-to-live duration in days for message and memory-like records. Omit this argument to use MemoryRetentionConfig.default_ttl_days from the managed schema. Pass None to use MemoryRetentionConfig.max_ttl_days when the retention configuration sets one, or to create a non-expiring record when it does not. Values above MemoryRetentionConfig.max_ttl_days are clamped to that maximum with a warning. Scalar values may be broadcast across aligned inputs.
- ttl_anchor TimeToLiveAnchor | list[TimeToLiveAnchor]- 可选的生存时间锚。使用 TimeToLiveAnchor.CREATED_AT 可相对于数据库创建时间过期，或者使用 TimeToLiveAnchor.TIMESTAMP 可相对于提供的事件时间戳过期。如果省略，则失效使用 TimeToLiveAnchor.CREATED_AT。时间戳锚定到期要求每个插入的记录都有一个具体的 ISO-8601 时间戳。没有时区的 ISO-8601 时间戳将视为 UTC。
- statuses RecordStatus | list[RecordStatus]- 支持它的记录的可选生命周期状态。提供一个 RecordStatus 值以将其应用于每个输入记录，或者提供与 contents 对齐的状态列表。省略此参数以使用 RecordStatus.VALID。
- **store_kwargs （任意）–数据库写入选项。batch_size 控制执行程序批大小，默认为 256。
返回：插入记录的标识符，其逻辑顺序与输入相同。
返回类型： list[str]

示例

store.add(
    ["Index this stored text"],
    record_type="memory",
    record_ids="mem-db-add-docs",
)
['mem-db-add-docs']
store.add(
    ["Stored text"],
    record_type="memory",
    index_texts=["Search this text"],
    record_ids="mem-db-index-text-docs",
)
['mem-db-index-text-docs']
store.add(
    ["Short-lived event"],
    record_type="memory",
    record_ids="mem-db-ttl-docs",
    timestamps="2026-01-01T12:00:00+00:00",
    ttl_days=7,
    ttl_anchor=TimeToLiveAnchor.TIMESTAMP,
)
['mem-db-ttl-docs']

method `add_agent`

添加代理概要记录。

参数：
- agent_id str- 代理标识符。
- information str- 关于代理的自由格式信息。此文本存储为概要内容，并用于构建概要的可搜索表示形式。
- metadata dict[str, Any] | None- 存储在代理配置文件行上的可选元数据映射。
退货：插入的代理概要信息记录的标识符。
返回类型： str

注释

代理概要信息记录未受影响。插入的公共记录标识符与 agent_id 传递的值相同。

示例

store.add_agent("a-docs-agent", "Support assistant")
'a-docs-agent'

method `add_agent_async`（异步）

异步添加代理概要信息记录。

参数：
- agent_id str- 代理配置文件的稳定标识符。
- information str- 描述代理的自由格式文本。
- metadata dict[str, Any] | None- 存储在代理配置文件行上的可选元数据映射。
退货：已创建的代理概要信息记录的标识符。
返回类型： str

method `add_async`（异步）

将面向行的记录异步添加到存储中。

接受相同的参数并返回与 add() 相同的标识符。

参数：
- 内容 Sequence[str | Mapping[str, object] | Sequence[MessageContent] | bytes | None]
- record_type str
- index_texts list[str | list[str] | None]
- embeddings（嵌入）list[list[float] | ndarray | list[list[float] | ndarray]]
- record_id str | None | list[str | None]
- thread_id str | None | list[str | None]
- user_ids str | None | list[str | None]
- agent_ids str | None | list[str | None]
- 角色 str | None | list[str | None]
- timestamps（时间戳）str | None | list[str | None]
- metadata（元数据）dict[str, Any] | None | list[dict[str, Any] | None]
- ttl_days int | None | list[int | None]
- ttl_anchor TimeToLiveAnchor | list[TimeToLiveAnchor]
- statuses RecordStatus | list[RecordStatus]
- store_kwargs Any
返回类型： list[str]

method `add_batches`

将调用者准备的逻辑批处理添加到存储。

参数：
- batches（批处理）list[PendingRecordBatch]- 要保留的完全准备的逻辑批处理。每个批处理应具有自己的每记录字段，例如 record_type、范围值、角色、时间戳和元数据。
- **store_kwargs ( Any )- 特定于实现的写入选项，转发到具体存储。
返回：已插入记录的标识符，其逻辑顺序与输入批和行相同。
返回类型： List[str]

示例

store.add_batches(
    [
        PendingRecordBatch(
            contents=["pizza batch"],
            record_type="memory",
            record_ids="mem-batch-docs",
        )
    ]
)
['mem-batch-docs']

method `add_batches_async`（异步）

将呼叫者准备的逻辑批处理异步添加到存储中。

接受相同的参数并返回与 add_batches() 相同的标识符。

参数：
- 批 list[PendingRecordBatch]
- store_kwargs Any
返回类型： list[str]

method `add_relations`

以原子方式存储一个或多个内存到内存的关系。

标量值在源 ID 批中广播；列表必须对齐。一个端点对只能存储一个关系方向。内置内存链接标签会收到固定的反向标签，生命周期标签会更新同一事务处理中的端点状态。

参数：
- source_record_ids str | list[str]- 作为标量或对齐列表的源内存标识符。
- source_record_types str | list[str]- 源记录的类似内存的类型。
- target_record_ids str | list[str]- 目标内存标识符（标量或对齐列表）。
- target_record_types str | list[str]- 目标记录的类似内存的类型。
- relation_types str | list[str]- 定向关系标签。
- opposite_relation_types str | list[str]- 定制关系类型的可选反向标签。这描述了所存储关系的反向视图；它不会在反向方向上创建第二个关系。
- relation_id str | None | list[str | None]- 可选的稳定关系标识符。省略以生成标识符。
- timestamps str | None | list[str | None]- 与关系一起存储的可选时间戳。
- metadata dict[str, Any] | None | list[dict[str, Any] | None]- 随关系一起存储的可选元数据。
返回：按输入顺序创建关系标识符。
返回类型： list[str]

示例

store.add_relations(
    "new-memory", "memory", "old-memory", "memory", "supersedes"
)
['relation-id']

method `add_relations_async`（异步）

异步存储一个或多个定向关系。

参数：
- source_record_ids str | list[str]- 每个定向关系的源端的记录标识符或标识符。
- source_record_types str | list[str]-source_record_ids 的记录类型或类型。为所有来源提供一个值，或者为每个关系提供一个值。
- target_record_ids str | list[str]- 每个定向关系的目标端的记录标识符或标识符。
- target_record_types str | list[str]-target_record_ids 的记录类型或类型。为所有目标提供一个值，或者为每个关系提供一个值。
- relation_types str | list[str]- 定向关系标签或标签。为所有关系提供一个值，或者为每个关系提供一个值。
- opposite_relation_types str | list[str]- 每个关系的反向视图的可选标签或标签。对于内置内存关系类型，省略使用预定义的反向标签。对于自定义关系类型，省略在两个方向上使用相同的标签。
- relation_id str | None | list[str | None]- 可选的稳定标识符或标识符。省略此项可让存储生成标识符。
- timestamps str | None | list[str | None]- 要存储在关系上的可选时间戳或时间戳。
- metadata dict[str, Any] | None | list[dict[str, Any] | None]- 要存储在关系上的可选元数据对象。
返回：按输入顺序列出关系标识符。
返回类型： list[str]

示例

await store.add_relations_async(
    "new", "memory", "old", "memory", "supersedes"
)
['relation-id']

method `add_user`

添加用户概要记录。

参数：
- user_id str- 用户标识符。在 SchemaPolicy.NO_CHECK 运行时存储上省略时，存储将使用活动的最终用户安全上下文的用户名。否则，请显式提供此参数。
- information str- 需要有关用户的自由格式信息。此文本存储为概要内容，并用于构建概要的可搜索表示形式。
- metadata dict[str, Any] | None- 存储在用户配置文件行上的可选元数据映射。
返回：插入的用户配置文件记录的标识符。
返回类型： str

注释

用户概要信息记录未受限制。插入的公共记录标识符是显式或推断的 user_id。

示例

store.add_user("u-docs-profile", "Prefers concise answers.")
'u-docs-profile'

method `add_user_async`（异步）

异步添加用户概要信息记录。

参数：
- user_id str- 用户配置文件的稳定标识符。
- information str- 描述用户的自由格式文本。
- metadata dict[str, Any] | None- 存储在用户配置文件行上的可选元数据映射。
退货：创建的用户配置文件记录的标识符。
返回类型： str

method `delete`

按标识符删除一个托管行及其块行。

参数：
- record_type str- 要删除的记录类型标签。支持的类型包括 "thread"、"message"、"memory"、"guideline"、"fact"、"preference"、"user_profile" 和 "agent_profile" 以及 "thread_summary"。
- record_id str- 要删除的标识符。
- 级联 bool- 当 True 时，将支持的顶层目标（例如角色配置文件）展开到同一事务处理中其作用域的子行。对于用户配置文件或代理配置文件目标，这将首先删除拥有的线程行，这将删除其线程范围消息和内存表行，然后删除所有剩余的直接操作范围消息和类似内存的行（memory、guideline、fact、preference）。当匹配的概要行已经不存在时，此范围清除仍会运行。
返回值：删除的请求的顶级目标数，通常为 0 或 1。级联子行不单独计算，因此当缺少的角色配置文件触发范围清除时，这可能仍为 0。
返回类型： int

注释

该操作在一个事务处理内运行。为支持的顶层目标启用 cascade 时，将一起提交或回退概要信息删除和所有范围子删除。

示例

store.add(["Delete me"], record_type="memory", record_ids="mem-delete-docs")
['mem-delete-docs']
store.delete("memory", "mem-delete-docs")
1

method `delete_async`（异步）

按标识符异步删除一个存储的记录。

参数：
- record_type str- 要删除的记录的逻辑类型。
- record_id str- 要删除的记录标识符。
- cascade bool- 在 True 时，对同一删除操作内请求的顶层目标应用任何存储支持的级联删除行为。这主要用于目标，例如拥有其他范围记录的操作者概要信息。例如，用户配置文件或代理配置文件级联可以删除自有线程本身、随这些线程删除的线程范围消息和类似内存的记录，以及任何剩余的直接操作者范围记录，例如消息、内存、准则、事实或首选项。对于 actor-profile 删除，当匹配的概要文件行已经不存在时，此范围清除仍可能运行。
返回：请求删除的顶层记录数，通常为 0 或 1。级联子行不单独计算，因此当缺少的角色配置文件触发范围清除时，这可能仍为 0。
返回类型： int

method `delete_relations`

按标识符删除关系并重新计算生命周期状态。

参数：relation_id str | list[str]- 要删除关系的标识符或标识符。
退货：已删除的关系数。
返回类型： int

示例

store.delete_relations("relation-id")
1

method `delete_relations_async`（异步）

按标识符异步删除关系。

将根据保留的关系重新计算生命周期状态。

参数：relation_id str | list[str]- 要删除关系的标识符或标识符。
退货：已删除的关系数。
返回类型： int

示例

await store.delete_relations_async("relation-id")
1

method `delete_thread`

删除线程及其关联的存储行。

参数：thread_id str- 应删除其行的线程标识符，包括线程行、相关子行和显式块行清除。
返回数：已删除的线程行数（0 或 1）。
返回类型： int

注释

需要线程范围级联清除时使用此操作。在数据库支持的存储中，删除该线程将删除托管线程行以及关联的消息和内存行以及为检索而维护的搜索数据。这比仅删除原始消息行的消息级别删除更广泛。线程删除将删除从属消息和内存行及其在同一事务处理中的关联检索数据。

示例

store.delete_thread("c1")
0

method `delete_thread_async`（异步）

异步删除线程及其关联的存储数据。

参数：thread_id str- 要删除的线程的标识符。
返回：已删除的线程记录数，通常为 0 或 1。
返回类型： int

注释

method `get`

按标识符检索存储的记录。

参数：
- record_type str- 解析为受管理行的记录类型标签，例如 "message"、"memory"、"guideline"、"fact"、"preference"、"thread"、"user_profile" 或 "agent_profile" 或 "thread_summary"。
- record_id str- 要查找的标识符。
- include_bytes bool- 是装入图像记录的图像字节，还是装入消息记录的附加图像。默认值为 False。
返回：找到时使用解码元数据填充的记录，否则为 None。
退货类型：记录 | 无

示例

store.add(["Remember this"], record_type="memory", record_ids="mem-get-docs")
['mem-get-docs']
store.get("memory", "mem-get-docs").id
'mem-get-docs'

method `get_async`（异步）

按类型和标识符异步检索一个存储的记录。

参数：
- record_type str- 要检索的记录的逻辑类型，例如 "thread"、"message"、"memory"、"guideline"、"fact"、"preference"、"user_profile"、"agent_profile" 或 "image"。
- record_id str- 要检索的记录的标识符。
- include_bytes bool- 是否装入存储的映像字节数。对于消息记录，这将控制附加的图像是否包括其字节数。对于图像记录，它控制是否加载独立图像字节。此选项对其他记录类型没有影响。
返回：找到时存储的记录，否则为 None。"thread" 查找返回线程元数据、运行时配置、运行时状态以及存储支持持久性线程时填充的创建时间戳的 ThreadRecord。
退货类型：记录 | 无

method `get_relation`

返回由 ID 或完整端点元组标识的一个关系。

单独提供 relation_id，或者提供一个完整的源到目标端点元组。

参数：
- source_record_id str- 源记录标识符。省略 relation_id 时，对于其他端点元组字段是必需的。
- source_record_type str- 源记录类型。省略 relation_id 时，对于其他端点元组字段是必需的。
- target_record_id str- 目标记录标识符。省略 relation_id 时，对于其他端点元组字段是必需的。
- target_record_type str- 目标记录类型。省略 relation_id 时，对于其他端点元组字段是必需的。
- relation_type str- 定向关系标签。省略 relation_id 时，对于其他端点元组字段是必需的。
- relation_id str- 要直接匹配的关系标识符。单独提供此参数，而不是将其与端点元组字段组合。
返回值：匹配的存储关系，或不存在的 None。
返回类型：RecordRelation | 无

示例

store.get_relation(relation_id="relation-id")
RecordRelation(...)
store.get_relation(
    "source-id", "memory", "target-id", "fact", "supports"
)
RecordRelation(...)

method `get_relation_async`（异步）

按 ID 或端点元组异步检索一个关系。

单独提供 relation_id，或者提供一个完整的源到目标端点元组。

参数：
- source_record_id str- 源记录标识符。省略 relation_id 时，对于其他端点元组字段是必需的。
- source_record_type str- 源记录类型。省略 relation_id 时，对于其他端点元组字段是必需的。
- target_record_id str- 目标记录标识符。省略 relation_id 时，对于其他端点元组字段是必需的。
- target_record_type str- 目标记录类型。省略 relation_id 时，对于其他端点元组字段是必需的。
- relation_type str- 定向关系标签。省略 relation_id 时，对于其他端点元组字段是必需的。
- relation_id str- 要直接匹配的关系标识符。单独提供此参数，而不是将其与端点元组字段组合。
返回值：匹配关系或不存在的 None。
返回类型：RecordRelation | 无

示例

await store.get_relation_async(relation_id="relation-id")
RecordRelation(...)

method（方法）`list`

枚举记录类型的持久记录。

参数：
- record_type str- 记录类型标签（例如 "thread"、"message"、"memory"、"guideline"、"fact"、"preference"、"thread"、"user_profile" 或 "agent_profile"）。
- limit int | None- 要返回的可选最大记录数。如果省略，存储将使用其默认列表上限。传递 None 以禁用该上限并返回每个匹配记录。
- thread_id str | None- 精确的线程范围过滤器。如果省略，则不应用任何筛选。设置为 None 时，仅返回其 thread_id 为 SQL NULL 的行。未界定的记录类型会忽略此筛选器。如果 record_type 为 "thread"，则不应设置 thread_id；请使用 record_id 选择特定线程。
- user_id str | None- 精确的用户范围过滤器。如果省略，则不应用任何筛选。设置为 None 时，仅返回其 user_id 为 SQL NULL 的行。未界定的记录类型会忽略此筛选器。
- agent_id str | None- 精确代理范围过滤器。如果省略，则不应用任何筛选。设置为 None 时，仅返回其 agent_id 为 SQL NULL 的行。未界定的记录类型会忽略此筛选器。
- metadata_filter dict[str, Any] | None-
  
  元数据过滤器。如果省略，则不应用任何筛选。设置为 None 时，仅返回没有存储元数据的记录。设置为 dict 时，metadata_filter 中的条目将与 AND 语义组合。值不是字段级运算符字典的条目使用完全匹配语义：所请求的关键字必须存在于存储的元数据中。嵌套字典以递归方式进行匹配。标量和列表值通过完全相等进行匹配；列表顺序和长度也必须匹配。要测试数组成员关系，请使用字段级运算符字典，例如 {"tags": {"$array_contains": "prod"}}。"$array_contains" 的列表操作数表示必须存在所有列出的值；"$array_contains_any" 表示必须至少存在一个列出的值。使用 "$not" 可否定同一字段中的另一个字段级表达式，包括运算符字典或原始完全匹配值。正表达式失败时（包括缺少的字段）匹配负表达式；负数数组成员资格也匹配非数组字段。示例包括 metadata_filter={"source": "slack"}（表示标量字段）、metadata_filter={"review": {"status": "open"}}（表示嵌套字段）和 metadata_filter={"tags": ["prod", "urgent"]}（表示完全匹配列表）。组合条件以要求所有条件：
```
metadata_filter={
    "source": "slack",
    "review": {"status": "open"},
    "tags": ["prod", "urgent"],
}
```
- include_bytes bool- 附加到消息记录的映像记录或映像是否包括其存储的字节数。默认值为 False。直接映像列表需要 record_id 和至少一个精确的用户、代理或线程范围筛选器（如果是 True）。
- record_id str- 精确的记录标识符过滤器。省略时，将返回具有任何标识符的记录。范围和元数据筛选器仍是附加约束条件。
退货：按插入顺序排序的记录。
返回类型： list［记录］

注释

"user_profile" 和 "agent_profile" 是不受限制的记录类型。对于这些记录类型，将忽略 thread_id、user_id 和 agent_id，角色标识保留在 record.id 中。"thread" 记录将线程标识符公开为 record.id 和 record.thread_id。

示例

store.add(
    ["First listed", "Second listed"],
    record_type="memory",
    record_ids=["mem-list-docs-1", "mem-list-docs-2"],
)
['mem-list-docs-1', 'mem-list-docs-2']
[record.id for record in store.list("memory", limit=2)]
['mem-list-docs-1', 'mem-list-docs-2']
store.add_user("u-list-docs", "Prefers concise answers.")
'u-list-docs'
any(
    record.id == "u-list-docs"
    for record in store.list("user_profile", user_id=None, limit=10)
)
True

method `list_async`（异步）

异步列出一种记录类型的存储记录。

参数：
- record_type str- 要枚举的逻辑记录类型，例如 "thread"、"message"、"memory"、"guideline"、"fact"、"preference"、"user_profile"、"agent_profile" 或 "image"。
- limit int | None- 返回的最近记录的最大可选数量。省略时，实现可以应用安全上限，例如 MAX_LIST_LIMIT。传递 None 以禁用该上限并返回每个匹配记录。
- thread_id str | None- 精确的线程范围过滤器。如果省略，则不应用任何筛选。设置为 None 时，仅返回其 thread_id 为 None 的记录。未界定的记录类型会忽略此筛选器。如果 record_type 为 "thread"，则不应设置 thread_id；请使用 record_id 选择特定线程。
- user_id str | None- 精确的用户范围过滤器。如果省略，则不应用任何筛选。设置为 None 时，仅返回其 user_id 为 None 的记录。未界定的记录类型会忽略此筛选器。
- agent_id str | None- 精确代理范围过滤器。如果省略，则不应用任何筛选。设置为 None 时，仅返回其 agent_id 为 None 的记录。未界定的记录类型会忽略此筛选器。
- metadata_filter dict[str, Any] | None-
  
  元数据过滤器。如果省略，则不应用任何筛选。设置为 None 时，仅返回元数据为 None 的记录。设置为 dict 时，metadata_filter 中的条目将与 AND 语义组合。值不是字段级运算符字典的条目使用完全匹配语义：所请求的关键字必须存在于存储的元数据中。嵌套字典以递归方式进行匹配。标量和列表值通过完全相等进行匹配；列表顺序和长度也必须匹配。要测试数组成员关系，请使用字段级运算符字典，例如 {"tags": {"$array_contains": "prod"}}。"$array_contains" 的列表操作数表示必须存在所有列出的值；"$array_contains_any" 表示必须至少存在一个列出的值。使用 "$not" 可否定同一字段中的另一个字段级表达式，包括运算符字典或原始完全匹配值。正表达式失败时（包括缺少的字段）匹配负表达式；负数数组成员资格也匹配非数组字段。示例包括 metadata_filter={"source": "slack"}（表示标量字段）、metadata_filter={"review": {"status": "open"}}（表示嵌套字段）和 metadata_filter={"tags": ["prod", "urgent"]}（表示完全匹配列表）。组合条件以要求所有条件：
```
metadata_filter={
    "source": "slack",
    "review": {"status": "open"},
    "tags": ["prod", "urgent"],
}
```
- include_bytes bool- 附加到消息记录的映像记录或映像是否包括其存储的字节数。省略或 False 时，将返回映像说明和元数据，而不会加载字节。对于直接映像列表，请仅使用精确的 record_id 和至少一个精确的用户、代理或线程范围筛选器将其设置为 True。此选项对其他记录类型没有影响。
- record_id str- 精确的记录标识符过滤器。省略时，将返回具有任何标识符的记录。范围和元数据筛选器仍是附加约束条件。
返回：在返回的窗口中按从最早到最新顺序排序的记录。
返回类型： List［ Record（记录）］

method `list_relations`

按从源到目标的方向列出关系。

参数：
- relation_type str- 要匹配的可选定向关系标签，例如 "supports" 或 "supersedes"。忽略以包括每个关系类型。
- source_record_id str- 要匹配的可选源记录标识符。
- source_record_type str- 要匹配的可选源记录类型。
- target_record_id str- 要匹配的可选目标记录标识符。
- target_record_type str- 要匹配的可选目标记录类型。
- limit int | None- 要返回的最早创建关系的最大可选数。如果省略，存储将使用 MAX_LIST_LIMIT。通过 None 返回每个匹配的存储关系。
- metadata_filter dict[str, Any] | None- 元数据过滤器。如果省略，则不应用任何筛选。设置为 None 时，仅返回元数据为 None 的关系。设置为字典时，条目将与 AND 语义组合。嵌套字典使用递归完全匹配。标量和列表值需要完全相等；使用 {"tags": {"$array_contains": "prod"}} 匹配数组成员关系；使用 "$array_contains_any" 匹配列出的任何值；使用 "$not" 否定另一个字段表达式。
- relation_id str- 精确的关系标识符过滤器。如果省略，将返回与任何标识符的关系。其他筛选器仍是附加约束条件。
返回：按创建时间和标识符排序的关系。
返回类型： list[ RecordRelation ]

示例

store.list_relations(
    source_record_id="current-memory",
    relation_type="supports",
    metadata_filter={"source": "manual"},
)
[RecordRelation(...)]

method `list_relations_async`（异步）

以源到目标为方向异步列出关系。

参数：
- relation_type str- 要匹配的可选定向关系标签，例如 "supports" 或 "supersedes"。忽略以包括每个关系类型。
- source_record_id str- 要匹配的可选源记录标识符。
- source_record_type str- 要匹配的可选源记录类型。
- target_record_id str- 要匹配的可选目标记录标识符。
- target_record_type str- 要匹配的可选目标记录类型。
- limit int | None- 要返回的最早创建关系的最大可选数。省略时，实现可以应用安全上限，例如 MAX_LIST_LIMIT。通过 None 返回每个匹配的存储关系。
- metadata_filter dict[str, Any] | None- 元数据过滤器。如果省略，则不应用任何筛选。设置为 None 时，仅返回元数据为 None 的关系。设置为字典时，条目将与 AND 语义组合。嵌套字典使用递归完全匹配。标量和列表值需要完全相等；使用 {"tags": {"$array_contains": "prod"}} 匹配数组成员关系；使用 "$array_contains_any" 匹配列出的任何值；使用 "$not" 否定另一个字段表达式。
- relation_id str- 可直接匹配的可选关系标识符。
返回：按创建时间和标识符排序的关系。
返回类型： list[ RecordRelation ]

示例

await store.list_relations_async(
    source_record_id="current-memory", relation_type="supports"
)
[RecordRelation(...)]

method `list_thread_messages`

返回一个话题持续的消息。

参数：
- thread_id str- 应返回其消息的线程标识符。
- last_n int | None- 要返回的最近消息的可选数量。
- range_start_seq_no int | None- 可选的包含下限序列边界。
- range_end_seq_no int | None- 可选的排斥序列上限边界。
- include_bytes bool- 附加到返回消息的映像部分是否包括其存储的字节数。默认值为 False。
返回：按插入顺序排序的消息记录。
返回类型： list[ MessageRecord ]

示例

store.list_thread_messages("c1")
[]

method `list_thread_messages_async`（异步）

异步列出存储为一个线程的消息历史记录。

参数：
- thread_id str- 应返回其消息的线程的标识符。
- last_n int | None- 要包含的最近消息的可选数量。省略时，将返回线程的所有存储消息。当与序列范围结合时，该限制适用于该范围内。
- range_start_seq_no int | None- 可选的包含下限序列边界。仅返回其 seq_no 至少是此值的消息。
- range_end_seq_no int | None- 可选的排斥序列上限边界。仅返回 seq_no 小于此值的消息。
- include_bytes bool- 附加到返回消息的映像部分是否包括其存储的字节数。省略或 False 时，将返回映像说明和元数据，而不会加载字节。
返回：在返回的窗口中按从最早到最新顺序排序的消息记录。
返回类型： List[ MessageRecord ]

method `search`

按相似性搜索记录。

活动搜索后端取决于存储配置的 SearchStrategy。SearchStrategy.VECTOR 根据存储的记录向量对查询向量进行排名。SearchStrategy.HYBRID 在 Oracle 托管混合索引中查询存储的搜索文本及其托管索引状态。SearchStrategy.KEYWORD 仅按与存储的搜索文本匹配的文本进行排名。

参数：
- query str | None- 用于查找匹配或类似记录的可选自然语言文本。如果省略 query_vector，请至少提供一个非空格字符。矢量搜索嵌入此文本；关键字搜索将其与存储的搜索文本匹配；混合搜索将其用于文本和矢量检索。当文本超过配置的块大小时，存储将分别搜索每个查询块，并将排名结果与倒数排名融合合并。
- query_vector list[float] | None- 可选的预计算查询嵌入。只能提供 query 和 query_vector 中的一个。在向量搜索中，这与存储的记录向量进行比较。在混合搜索中，它作为查询端向量输入发送到 Oracle 托管的混合索引，不会导致数据库存储直接与添加时或更新时存储向量进行比较。关键字搜索不接受 query_vector。向量必须是非空的一维，并且只能包含有限数值。在混合搜索中，其维必须与配置的 OracleDBEmbedder 模型匹配。
- k int- 要返回的最大结果数量。显式值必须至少为 1。这是上限：当筛选器限制过多、存在较少的非失效匹配记录或由于特定于实施的搜索行为时，调用返回的结果可能少于 k。
- thread_id str | None- 可选线程范围标识符。exact_thread_match=False 使线程维不受约束。exact_thread_match=True 与提供的 thread_id 完全匹配。如果为 thread_id=None，则它仅匹配线程维上未作用域的记录。
- user_id str | None- 可选的用户和代理范围标识符。对应的 exact_*_match=False 标志使该维不受约束。exact_*_match=True 与提供的 ID 完全匹配。如果 ID 为 None，则它仅匹配该维上未作用域的记录。
- agent_id str | None- 可选的用户和代理范围标识符。对应的 exact_*_match=False 标志使该维不受约束。exact_*_match=True 与提供的 ID 完全匹配。如果 ID 为 None，则它仅匹配该维上未作用域的记录。
- exact_user_match bool- 每个范围标识符是否必须完全匹配。False 会使该维不受约束。True 与提供的值完全匹配。如果该值为 None，则它仅匹配该维上的未作用域记录。
- exact_agent_match bool- 每个范围标识符是否必须完全匹配。False 会使该维不受约束。True 与提供的值完全匹配。如果该值为 None，则它仅匹配该维上的未作用域记录。
- exact_thread_match bool- 每个范围标识符是否必须完全匹配。False 会使该维不受约束。True 与提供的值完全匹配。如果该值为 None，则它仅匹配该维上的未作用域记录。
- record_types set[str] | None- 包括的可搜索记录类型的可选集。如果省略，数据库搜索将涵盖消息、文档（例如图像、内存表行和角色概要文件）。图像记录提供其说明，角色概要文件提供其 information 有效负载，消息和内存行提供其 content 有效负载。在搜索期间，概要信息记录类型将角色标识符用于适用的范围维，而其余范围维的行为方式为 None。
- metadata_filter dict[str, Any] | None- 可选的元数据过滤器映射。metadata_filter 中的条目与 AND 语义组合。值不是字段级运算符字典的条目使用完全匹配语义：所请求的关键字必须存在于存储的元数据中。嵌套字典以递归方式进行匹配。标量和列表值通过完全相等进行匹配；列表顺序和长度也必须匹配。要测试数组成员关系，请使用字段级运算符字典，例如 {"tags": {"$array_contains": "prod"}}。"$array_contains" 的列表操作数表示必须存在所有列出的值；"$array_contains_any" 表示必须至少存在一个列出的值。使用 "$not" 可否定同一字段中的另一个字段级表达式，包括运算符字典或原始完全匹配值。正表达式失败时（包括缺少的字段）匹配负表达式；负数数组成员资格也匹配非数组字段。
- include_invalid_results bool- 结果是否包括处于无效状态的类似内存的记录。默认值为 True。传递 False 以将其排除。
- num_hops int- 从每个直接内存结果跟踪的内存链路边缘数。支持从 0 到 5 的值；0 将禁用图形扩展。扩展在两个方向上的链接后面。链接的记录将继续遵循请求的范围、元数据、记录类型和失效筛选器。直接消息、文档和概要结果保留在结果集中，但不会以图形展开。
- max_linked_results int- 附加到每个直接结果的所有跃点的最大链接内存。0 会保留没有链接上下文的直接结果。默认为 100。
返回值：按增加距离排序的 (record, distance) 对。该列表可以包含少于 k 个条目。对于分块查询，距离派生自相互 - 排名 - 融合评分。
返回类型： list[tuple[ Record ，float]]
增加：
- ValueError - 如果 k 小于 1，如果同时提供或未提供 query 和 query_vector，如果 query 为空，如果向量模式无法解析查询嵌入，如果 query_vector 无效，或者如果 metadata_filter 无效。
- TimeoutError - 如果图形扩展所用的时间超过允许的最大时间。

示例

store.add(
    ["pizza preference"],
    record_type="memory",
    record_ids="mem-search-docs",
    thread_ids="c-search-docs",
)
['mem-search-docs']
results = store.search(
    "pizza",
    1,
    thread_id="c-search-docs",
    exact_thread_match=True,
    record_types={"memory"},
)
results[0][0].id
'mem-search-docs'

对标量元数据值进行筛选：

store.add(
    ["pizza release"],
    record_type="memory",
    record_ids="mem-search-meta-source-docs",
    metadata={"source": "slack"},
)
['mem-search-meta-source-docs']
any(
    record.id == "mem-search-meta-source-docs"
    for record, _ in store.search(
        "pizza",
        k=3,
        metadata_filter={"source": "slack"},
    )
)
True

对嵌套元数据进行过滤：

store.add(
    ["pizza review"],
    record_type="memory",
    record_ids="mem-search-meta-review-docs",
    metadata={"review": {"status": "open"}},
)
['mem-search-meta-review-docs']
any(
    record.id == "mem-search-meta-review-docs"
    for record, _ in store.search(
        "pizza",
        k=3,
        metadata_filter={"review": {"status": "open"}},
    )
)
True

完全匹配列表值，包括顺序：

store.add(
    ["pizza tags"],
    record_type="memory",
    record_ids="mem-search-meta-tags-docs",
    metadata={"tags": ["prod", "urgent"]},
)
['mem-search-meta-tags-docs']
any(
    record.id == "mem-search-meta-tags-docs"
    for record, _ in store.search(
        "pizza",
        k=3,
        metadata_filter={"tags": ["prod", "urgent"]},
    )
)
True

当元数据数组包含值时进行筛选：

any(
    record.id == "mem-search-meta-tags-docs"
    for record, _ in store.search(
        "pizza",
        k=3,
        metadata_filter={"tags": {"$array_contains": "prod"}},
    )
)
True

组合多个元数据条件。记录必须满足每个键：

store.add(
    ["pizza rollout"],
    record_type="memory",
    record_ids="mem-search-meta-combined-docs",
    metadata={
        "source": "slack",
        "review": {"status": "open"},
        "tags": ["prod", "urgent"],
    },
)
['mem-search-meta-combined-docs']
any(
    record.id == "mem-search-meta-combined-docs"
    for record, _ in store.search(
        "pizza",
        k=5,
        metadata_filter={
            "source": "slack",
            "review": {"status": "open"},
            "tags": ["prod", "urgent"],
        },
    )
)
True

method `search_async`（异步）

按语义相似性异步搜索记录。

参数：
- query str | None-search 接受的同一查询文本。
- k int-search 接受的最大结果计数相同。显式值必须至少为 1。
- query_vector list[float] | None-search 接受的同一可选预计算查询嵌入。
- thread_id str | None-search 接受的相同可选范围过滤器。
- user_id str | None- 与 search 接受的可选范围过滤器相同。
- agent_id str | None- 与 search 接受的可选范围过滤器相同。
- exact_user_match bool-search 接受的相同完全匹配标志。
- exact_agent_match bool-search 接受的相同完全匹配标志。
- exact_thread_match bool-search 接受的相同完全匹配标志。
- record_types set[str] | None- 与 search 接受的可选记录类型过滤器相同。
- metadata_filter dict[str, Any] | None-search 接受的相同可选元数据过滤器，包括标量、嵌套、精确列表、数组成员身份以及 {"source": "slack"}、{"review": {"status": "open"}}、{"tags": ["prod", "urgent"]} 和 {"tags": {"$array_contains": "prod"}} 等组合条件。
- include_invalid_results bool-search 接受的相同生命周期状态结果选项。
- num_hops int-search 接受的相同图形扩展深度。
- max_linked_results int-search 接受的每直接结果链接内存限制相同。
返回：底层 search 调用返回的 (record, distance) 对。
返回类型： List[tuple[ Record ，float]]
引发：ValueError - 如果 k 小于 1。

method `update`

更新存储的记录内容、搜索状态、元数据和时间戳值。

参数：
- record_type str- 要修改行的记录类型标签（例如 "message"、"memory"、"guideline"、"fact"、"preference"、"user_profile" 或 "agent_profile"）
- record_id str- 要更新的存储行的标识符。
- content str | Mapping[str, object] | Sequence[MessageContent] | bytes | None- 规范替换内容保留在 content 列中。对于消息记录，传递 "" 以清除内容，同时清除任何存储的向量表示形式；显式 None 被拒绝。对于类似内存的记录，传递 None 以清除存储的文本和嵌入，并在同一调用中仅传递 None 或省略语义参数。省略时，现有内容保持不变。请勿将其与 text 一起提供。
- index_text str | list[str] | None- 可选的仅语义有效负载。省略时，content 用于语义索引。在支持混合的方案中，这也成为 Oracle 文本组件使用的存储搜索文本。存储可以对字符串值进行分块；列表值被视为调用方拥有的块，并按原样写入 RECORD_CHUNKS。仅提供 embedding 时，将重用现有的搜索文本。
- embedding list[float] | ndarray | list[list[float] | ndarray] | None-
  
  可选的预计算嵌入向量或块嵌入向量的列表。配置本地向量存储时，将直接使用此方法，并且不会调用嵌入器。传递 None 以清除存储的嵌入。单个向量表示提供 content 时的整个替换文本，即使配置的块会拆分该文本也是如此。替换文本时会拒绝多个块向量，除非 index_text 是块列表。仅提供 embedding 时，嵌入计数必须与记录的现有块行匹配。
  
  在 SearchStrategy.VECTOR 中，向量搜索根据存储的嵌入进行排名。在 SearchStrategy.HYBRID 或 SearchStrategy.KEYWORD 中，数据库支持的搜索按存储的搜索文本和 Oracle 管理的文本或混合索引状态进行排名，因此更新时嵌入仅影响任何配置的本地向量存储，而不影响该活动搜索策略。如果此存储是在没有本地向量存储的情况下配置的，请提供 index_text 而不是 embedding 以更新这些文本感知索引可见的文本。仅文本语义更新可以在这些模式下完全省略 embedding。
- metadata dict[str, Any] | None- 串行化到 JSON 并存储在 metadata 中的可选元数据映射。要替换映像 content，需要使用 "image/png"、"image/jpeg" 或 "image/webp" 替换 "image_mime_type"。商店使用此字段保存图像，但不会将其作为记录元数据的一部分返回。
- timestamp str | None- 与记录一起保存的可选新时间戳。它表示创建记录的时间。省略时，将保留现有时间戳。通过 None 清除保存的时间戳，并将数据库创建时间用于将来的 TimeToLiveAnchor.CREATED_AT 到期刷新。如果 ttl_anchor 为 TimeToLiveAnchor.TIMESTAMP，则不带时区的 ISO-8601 时间戳将视为 UTC。
- ttl_days int | None – Optional expiration refresh in days. Omit this argument together with ttl_anchor to preserve the current expiration timestamp. 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. Refreshing expiration can make an expired record visible again if it has not been purged yet.
- ttl_anchor TimeToLiveAnchor- 用于到期刷新的可选生存时间锚。使用 TimeToLiveAnchor.CREATED_AT 从存储的创建时间开始计数，或者使用 TimeToLiveAnchor.TIMESTAMP 从同一更新中提供的替换 timestamp 计数，或者使用 timestamp 省略时存储的事件时间戳计数。提供不带 ttl_days 的 ttl_anchor 时，将使用方案的 MemoryRetentionConfig.default_ttl_days 刷新失效。刷新期间省略 ttl_anchor 时，存储将使用 TimeToLiveAnchor.CREATED_AT。时间戳锚定刷新需要同一调用中的替换 ISO-8601 时间戳，或者需要采用该格式的现有存储事件时间戳。没有时区的 ISO-8601 时间戳将视为 UTC。
- status RecordStatus- 记录的可选替换生命周期状态。省略它以保留当前状态。
- text str | None-
  
  content 的已弃用别名。传递 None 以清除存储的文本并清除存储的嵌入。请勿将其与 content 一起提供。
  
  已弃用
  
  自版本 26.8.0 起已废弃：此参数在 26.8.0 中已废弃，将在 27.1 中删除。请改用 content。
返回：更新的记录数（0 或 1）。返回值 0 表示未更新任何记录。
返回类型： int
引发：ValueError - 如果不支持 record_type、未提供更新有效负载或者语义更新参数不兼容。

示例

store.add(["Original note"], record_type="memory", record_ids="mem-update-docs")
['mem-update-docs']
store.update("memory", "mem-update-docs", content="Updated note")
1
store.get("memory", "mem-update-docs").content
'Updated note'

method `update_async`（异步）

异步更新存储的记录内容，嵌入数据、元数据、时间戳或到期。

参数：
- record_type str- 要更新的记录的逻辑类型。
- record_id str- 要更新的记录的标识符。
- content str | Mapping[str, object] | Sequence[MessageContent] | bytes | None- 规范替换内容。对于 message 记录，传递文本和图像内容部分的字符串或有序序列；使用 "" 将消息替换为空文本。对于类似内存的记录，存储可以接受 None 来清除存储的文本和关联的语义状态。省略参数以保持内容不变。请勿将其与 text 一起提供。
- index_text str | list[str] | None- 可选的替代语义有效负荷，用于重新计算或替换存储的搜索状态，而无需更改持久文本。门店可以对字符串进行内部分块。非空字符串列表被视为调用方拥有的块，不能再次拆分。某些实现也可能会将其单独保留为混合搜索文本。对于 image 记录，此字段将替换保留的图像描述。
- embedding list[float] | ndarray | list[list[float] | ndarray] | None- 可选的预计算嵌入向量或块嵌入向量列表。如果提供，则直接使用此项，且不调用嵌入器。多个向量需要匹配的 index_text 块列表或现有的存储块文本行。通过 None 在存储支持存储嵌入时显式清除存储嵌入。具有文本感知索引的存储还可以允许在没有嵌入或显式嵌入的情况下进行语义更新。
- metadata dict[str, Any] | None- 可选的替换元数据映射。传递 None 以在存储支持元数据时清除元数据。在此映射中替换映像 content 需要 "image_mime_type"。商店使用此字段保存图像，但不会将其作为记录元数据的一部分返回。
- timestamp str | None- 与记录一起保存的可选新时间戳。它表示创建记录的时间。省略此参数可使存储的时间戳保持不变。传递 None 以清除保存的时间戳，并在商店支持记录时使用将记录添加到商店的时间。
- ttl_days int | None- 可选的到期刷新（天）。将此参数与 ttl_anchor 一起省略，以保留当前的失效时间戳。传递 None 以清除到期。
- ttl_anchor TimeToLiveAnchor- 用于到期刷新的可选生存时间锚。将 TimeToLiveAnchor.CREATED_AT 用于记录创建时间，将 TimeToLiveAnchor.TIMESTAMP 用于在同一更新中提供的替换 timestamp，或者在省略 timestamp 时使用存储的事件时间戳。提供不带 ttl_days 的 ttl_anchor 将使用存储或方案默认生存时间持续时间。在刷新期间省略 ttl_anchor 时，实施将使用 TimeToLiveAnchor.CREATED_AT。
- status RecordStatus- 记录的可选替换生命周期状态。省略它以保留当前状态。
- text str | None-
  
  content 的已弃用别名。传递 None 可在存储支持时显式清除存储的文本。请勿将其与 content 一起提供。
  
  已弃用
  
  自版本 26.8.0 起已废弃：此参数在 26.8.0 中已废弃，将在 27.1 中删除。请改用 content。
返回：更新的记录数（0 或 1）。返回值 0 表示未更新任何记录。
返回类型： int
引发：ValueError - 如果更新有效负载对存储无效，例如省略每个可选字段或提供冲突的语义参数。

method `update_relations`

更新可变关系字段并重新计算端点生命周期状态。

省略的字段保持不变。内置内存链接标签始终保留其派生的反向标签。

参数：
- relation_id str | list[str]- 要更新的关系的标识符或标识符。
- relation_types str | list[str]- 可选的替换定向关系标签或标签。
- opposite_relation_types str | list[str]- 定制类型的可选替换反向标签或标签。
- timestamps str | None | list[str | None]- 可选的替换时间戳。通过 None 清除一个。
- metadata dict[str, Any] | None | list[dict[str, Any] | None]- 可选的替换元数据。它将替换现有元数据。
返回：已更新的关系的标识符。
返回类型： list[str]

示例

store.update_relations("relation-id", relation_types="supports")
['relation-id']

method `update_relations_async`（异步）

异步更新存储关系上的可变值。

参数：
- relation_id str | list[str]- 要更新的关系的标识符或标识符。
- relation_types str | list[str]- 可选的替换定向关系标签或标签。省略此项以保留存储的标签。
- opposite_relation_types str | list[str]- 可选的替换反向关系标签或标签。传递标签以替换它，或者省略此参数以保留它。
- timestamps str | None | list[str | None]- 可选的替换时间戳或时间戳。传递 None 以清除存储的时间戳。
- metadata dict[str, Any] | None | list[dict[str, Any] | None]- 可选替换元数据对象或对象。提供的元数据将替换存储的对象；它不会合并。
返回：已更新的关系的标识符。
返回类型： list[str]

示例

await store.update_relations_async(
    "relation-id", relation_types="supports"
)
['relation-id']

关联

OracleDBMemoryStore 可以存储类似内存的记录（memory、fact、guideline 和 preference）之间的定向关系。当集成需要较低级别的关系 API 时，请使用 add_relations()、get_relation()、list_relations()、update_relations() 和 delete_relations()。客户端和线程 API 为支持的内存关系类型提供 link_records()、update_record_link() 和 delete_record_link()。

要检索一种关系，请单独提供 relation_id 或完整存储的端点元组：源记录 ID 和类型、目标记录 ID 和类型以及关系类型。部分元组和与任何元组字段组合的关系 ID 无效，因为两者都不能明确地标识所请求的关系。

使用 list_relations() 按创建顺序列举关系。按源或目标记录 ID 和类型进行筛选，或者按定向关系标签进行筛选。它使用商店的正常安全列表限制，除非您通过 limit=None。其 metadata_filter 使用与 list() 相同的完全匹配、嵌套对象、数组成员关系和否定语义；通过 metadata_filter=None 仅返回没有元数据的关系。

生命周期关系类型（supersedes、refines 和 duplicates）会在存在链接时将其目标内存标记为无效。删除或更改最后一个此类链接会将目标恢复为有效状态。搜索 API 可以排除具有 include_invalid_results=False 的无效记录。

class `oracleagentmemory.apis.relations.RecordRelation`

基准：object

描述两个记录之间存储的定向关系。

参数：
- id str- 关系的稳定标识符。
- source_record_id str- 关系存储源处的记录的标识符。
- source_record_type str- 源记录的逻辑类型。
- target_record_id str- 关系所存储目标处的记录的标识符。
- target_record_type str- 目标记录的逻辑类型。
- relation_type str- 其含义遵循存储的源到目标方向的标签。
- opposite_relation_type str- 遍历从目标移动到源时使用的标签。
- timestamp str | None- 与关系关联的可选调用方时间戳。
- metadata dict[str, Any] | None- 随关系一起存储的类似 JSON 的可选元数据。
- created_at str- 关系的数据库创建时间戳。

搜索策略

class `oracleagentmemory.core.dbsearch.SearchStrategy`

基础：Enum

Oracle DB 存储的搜索行为。

数据库存储初始化使用所选策略来选择托管方案搜索功能。VECTOR 搜索存储本地嵌入。KEYWORD 搜索存储可搜索文本和文本索引。HYBRID 搜索存储可搜索文本以及 Oracle 管理的混合向量索引状态。数据库存储会在启动时验证此方案功能，因此不兼容的策略不会无提示地返回未完成的结果。

VECTOR: 仅按向量相似性搜索。存储使用配置的嵌入器嵌入查询，或使用调用方提供的 query_vector，并按与存储向量的距离对记录进行排名。将此项与为向量搜索配置的数据库方案结合使用。
HYBRID: 使用 Oracle 托管混合索引进行搜索。Oracle 将文本匹配与存储的搜索文本与数据库内混合索引中的向量排名相结合。当用户可以按自然语言以及确切的标识符、别名或产品名称进行搜索时，使用此选项。此策略要求存储的主嵌入程序为 OracleDBEmbedder，因此托管索引和存储共享一个数据库内模型。
KEYWORD: 仅按关键字/文本匹配在存储的搜索文本上进行搜索。此模式不创建本地查询嵌入，也不需要 Oracle DB 嵌入。当针对现有混合模式打开时，它可以使用该混合索引的文本分支，而无需创建新的混合索引。如果准确的标识符、别名、产品名称或短短短语应驱动检索而无需向量融合，则使用此选项。

HYBRID = ‘ HYBRID ’

KEYWORD = ‘ KEYWORD ’

VECTOR = ‘ VECTOR ’

搜索索引同步模式

class `oracleagentmemory.core.dbsearch.SearchIndexSyncMode`

基础：Enum

托管数据库搜索索引的刷新行为。

此设置控制 Oracle 何时将新的或更改的搜索文本对数据库支持的文本感知搜索可见。SearchStrategy.HYBRID 使用 Oracle 托管的混合向量索引。SearchStrategy.KEYWORD 使用 Oracle Text 索引。SearchStrategy.VECTOR 不使用此设置。

ON_COMMIT: 提交写入事务处理时刷新索引。这是大多数应用程序的默认和最简单的选择，因为记录在成功写入后可立即搜索。它可以添加写入事务的工作，因为索引会立即保持最新状态。
MANUAL: 不要自动刷新索引。在您自己运行数据库端索引同步操作之前，新记录或更新的记录可能不会出现在关键字或混合搜索中。这对于要控制刷新工作何时运行的批量加载或维护窗口非常有用。
AUTO: 让 Oracle 异步刷新托管混合索引。写入可以避免立即刷新成本，但搜索结果可能会滞后于最近的写入，直到 Oracle 完成后台刷新。此模式仅受 SearchStrategy.HYBRID 支持。

警告：此设置控制托管搜索索引存在后正在进行的维护。它不会使第一个索引构建异步。在现有存储的搜索文本上创建托管混合索引可以长时间运行，因为 Oracle 从该文本构建托管混合索引状态。

AUTO = ‘ AUTO ’

MANUAL = ‘ MANUAL ’

ON_COMMIT = ‘ ON_COMMIT ’

生存时间

class `oracleagentmemory.core.retention.MemoryRetentionConfig`

基准：object

Oracle DB 支持的记录的方案级别保留设置。

参数：
- default_ttl_days int | None- 缺省生存时间（天）。保留为 NOT_SET_MARKER 以使用默认值 None（无最大值）。
- max_ttl_days int | None- 可选的最长生存时间（天）。保留为 NOT_SET_MARKER 以使用默认值 None。传递 None 表示无最大值。当设置时，这是一个硬上限：尝试使用较大 ttl_days 值的写入将被限制到此最大值，并发出警告，写入通过 ttl_days=None 的 API 将使用此最大值，而不是创建非失效记录。

class `oracleagentmemory.apis.ttl.TimeToLiveAnchor`

基础：Enum

用于计算从生存时间开始的失效时间戳的锚点。

CREATED_AT: 从记录的数据库创建时间戳计算到期。当调用方省略 ttl_anchor 时，这是缺省设置。
TIMESTAMP: 从记录的存储事件时间戳计算到期。当消息或内存表示较旧的事件并且应相对于该事件时间（而不是插入时间）过期时，使用此选项。

CREATED_AT = ‘ CREATED_AT ’

TIMESTAMP = ‘ TIMESTAMP ’

模式策略

class `oracleagentmemory.core.SchemaPolicy`

基础：str、Enum

Oracle DB 存储的方案创建策略。

需要现有

验证完整托管方案是否已存在并且是否是最新的。请勿创建或修改数据库对象。

CREATE_IF_EMPTY

如果不存在托管对象，则引导方案。如果对象已存在，则需要完整且最新的托管方案。

需要 CREATE_IF_

创建缺少的托管对象并应用支持的托管方案升级。

重新创建

删除并重新创建所有托管方案对象。这是毁灭性的。

无检查

跳过托管模式验证和创建。当最终用户安全上下文处于活动状态时，请将此策略用于受深度数据安全保护的现有存储。在最终用户上下文下打开的存储需要每个后续数据库操作的活动上下文。其他方案策略拒绝最终用户上下文，因为方案生命周期工作必须通过管理数据库标识运行。

存储和方案

存储 API

存储写入语义

存储级别检索有效负载

class oracleagentmemory.core.OracleMemoryStore

method add

method add_agent（抽象）

method add_agent_async（异步）

method add_async（异步）

method add_batches

method add_batches_async（异步）

method add_relations（抽象）

method add_relations_async（异步）

method add_user（抽象）

method add_user_async（异步）

method delete（抽象）

method delete_async（异步）

method delete_relations（抽象）

method delete_relations_async（异步）

method delete_thread（抽象）

method delete_thread_async（异步）

method get（抽象）

method get_async（异步）

method get_relation（抽象）

method get_relation_async（异步）

method list（抽象）

method list_async（异步）

method list_relations（抽象）

method list_relations_async（异步）

method list_thread_messages（抽象）

method list_thread_messages_async（异步）

method search（抽象）

method search_async（异步）

method update（抽象）

已弃用

method update_async（异步）

已弃用

method update_relations（抽象）

method update_relations_async（异步）

Oracle DB 存储

class oracleagentmemory.core.OracleDBMemoryStore

已弃用

method add

method add_agent

method add_agent_async（异步）

method add_async（异步）

method add_batches

method add_batches_async（异步）

method add_relations

method add_relations_async（异步）

method add_user

method add_user_async（异步）

method delete

method delete_async（异步）

method delete_relations

method delete_relations_async（异步）

method delete_thread

method delete_thread_async（异步）

method get

method get_async（异步）

method get_relation

method get_relation_async（异步）

method（方法）list

method list_async（异步）

method list_relations

method list_relations_async（异步）

method list_thread_messages

method list_thread_messages_async（异步）

method search

method search_async（异步）

method update

已弃用

method update_async（异步）

已弃用

method update_relations

method update_relations_async（异步）

关联

class oracleagentmemory.apis.relations.RecordRelation

搜索策略

class oracleagentmemory.core.dbsearch.SearchStrategy

class `oracleagentmemory.core.OracleMemoryStore`

method `add`

method `add_agent`（抽象）

method `add_agent_async`（异步）

method `add_async`（异步）

method `add_batches`

method `add_batches_async`（异步）

method `add_relations`（抽象）

method `add_relations_async`（异步）

method `add_user`（抽象）

method `add_user_async`（异步）

method `delete`（抽象）

method `delete_async`（异步）

method `delete_relations`（抽象）

method `delete_relations_async`（异步）

method `delete_thread`（抽象）

method `delete_thread_async`（异步）

method `get`（抽象）

method `get_async`（异步）

method `get_relation`（抽象）

method `get_relation_async`（异步）

method `list`（抽象）

method `list_async`（异步）

method `list_relations`（抽象）

method `list_relations_async`（异步）

method `list_thread_messages`（抽象）

method `list_thread_messages_async`（异步）

method `search`（抽象）

method `search_async`（异步）

method `update`（抽象）

method `update_async`（异步）

method `update_relations`（抽象）

method `update_relations_async`（异步）

class `oracleagentmemory.core.OracleDBMemoryStore`

method `add`

method `add_agent`

method `add_agent_async`（异步）

method `add_async`（异步）

method `add_batches`

method `add_batches_async`（异步）

method `add_relations`

method `add_relations_async`（异步）

method `add_user`

method `add_user_async`（异步）

method `delete`

method `delete_async`（异步）

method `delete_relations`

method `delete_relations_async`（异步）

method `delete_thread`

method `delete_thread_async`（异步）

method `get`

method `get_async`（异步）

method `get_relation`

method `get_relation_async`（异步）

method（方法）`list`

method `list_async`（异步）

method `list_relations`

method `list_relations_async`（异步）

method `list_thread_messages`

method `list_thread_messages_async`（异步）

method `search`

method `search_async`（异步）

method `update`

method `update_async`（异步）

method `update_relations`

method `update_relations_async`（异步）

class `oracleagentmemory.apis.relations.RecordRelation`

class `oracleagentmemory.core.dbsearch.SearchStrategy`

class `oracleagentmemory.core.dbsearch.SearchIndexSyncMode`

class `oracleagentmemory.core.retention.MemoryRetentionConfig`

class `oracleagentmemory.apis.ttl.TimeToLiveAnchor`

class `oracleagentmemory.core.SchemaPolicy`