存储和方案

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

存储 API

存储写入语义

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

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

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

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

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

存储级别检索有效负载

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

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

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

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

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

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

class `oracleagentmemory.core.OracleMemoryStore`

基础：IMemoryStore

OracleAgentMemory 使用的公用存储接口。

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

method `add`

将记录添加到商店。

参数：
- contents list[str | None]- 记录要保留的有效负载。除非提供了 index_texts 或 embeddings，否则文本值也用于语义索引。当文本值为 None 时，实现可能会回退到 metadata["content"]。将保留显式空字符串。
- record_type str- 要创建的逻辑记录类型，例如 "message"、"memory"、"guideline"、"fact"、"preference"、"user_profile" 或 "agent_profile"。
- 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 项使用当前时间。
- metadata dict[str, Any] | None | list[dict[str, Any] | None]- 可选的调用方提供的元数据字典。如果省略了文本值，而不是显式设置为 ""，则元数据可以包括 "content" 作为回退源。
- ttl_days int | None | list[int | None]- 支持过期记录的可选生存时间（以天为单位）。省略此参数以使用存储默认值。为不应过期的记录传递 None。标量值可以在对齐的文本输入之间广播。
- ttl_anchor TimeToLiveAnchor | list[TimeToLiveAnchor]- 可选的生存时间锚。使用 TimeToLiveAnchor.CREATED_AT 可相对于存储的创建时间到期，使用 TimeToLiveAnchor.TIMESTAMP 可相对于每个记录的事件时间戳到期。如果省略，则实施将使用 TimeToLiveAnchor.CREATED_AT。
- **store_kwargs ( Any )- 特定于实现的写入选项，转发到具体存储。
返回类型： list[str]

注

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

返回：插入记录的标识符，其逻辑顺序与输入相同。
返回类型： List[str]
参数：
- 内容 list[str | 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]
- store_kwargs Any

method `add_agent`（抽象）

添加代理概要记录。

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

method `add_async`（异步）

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

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

参数：
- 内容 list[str | 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]
- store_kwargs Any
返回类型： list[str]

method `add_batches`

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

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

示例

store.add_batches(
    [
        PendingRecordBatch(
            texts=["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_user`（抽象）

添加用户概要记录。

参数：
- 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_thread`（抽象）

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

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

注

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

method `get`（抽象）

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

参数：
- record_type str- 要检索的记录的逻辑类型。
- record_id str- 要检索的记录的标识符。
返回：找到时存储的记录，否则为 None。
退货类型：记录 | 无

method `list`（抽象）

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

参数：
- record_type str- 要枚举的逻辑记录类型。
- limit int | None- 返回的最近记录的最大可选数量。省略时，实现可以应用安全上限，例如 MAX_LIST_LIMIT。传递 None 以禁用该上限并返回每个匹配记录。
- thread_id str | None- 精确的线程范围过滤器。如果省略，则不应用任何筛选。设置为 None 时，仅返回其 thread_id 为 None 的记录。未界定的记录类型会忽略此筛选器。
- 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"],
}
```
返回：在返回的窗口中按从最早到最新顺序排序的记录。
返回类型： List［ Record（记录）］

method `list_thread_messages`（抽象）

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

参数：
- thread_id str- 应返回其消息的线程的标识符。
- last_n int | None- 要包含的最近消息的可选数量。省略时，将返回线程的所有存储消息。
返回：在返回的窗口中按从最早到最新顺序排序的消息记录。
返回类型： 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" 可否定同一字段中的另一个字段级表达式，包括运算符字典或原始完全匹配值。正表达式失败时（包括缺少的字段）匹配负表达式；负数数组成员资格也匹配非数组字段。
返回值：按增加距离排序的 (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-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"}} 等组合条件。
返回：底层 search 调用返回的 (record, distance) 对。
返回类型： List[tuple[ Record ，float]]
引发：ValueError - 如果 k 小于 1。

method `update`（抽象）

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

参数：
- record_type str- 要更新的记录的逻辑类型。
- record_id str- 要更新的记录的标识符。
- text str | None- 可选替换内容。传递 None 可在存储支持时显式清除存储的文本。存储还可以清除关联的语义状态，并在同一调用中拒绝冲突的非空 index_text 或 embedding 更新。省略参数以保持内容不变。
- index_text str | list[str] | None- 可选的替代语义有效负荷，用于重新计算或替换存储的搜索状态，而无需更改持久文本。门店可以对字符串进行内部分块。非空字符串列表被视为调用方拥有的块，不能再次拆分。某些实现也可能会将其单独保留为混合搜索文本。
- embedding list[float] | ndarray | list[list[float] | ndarray] | None- 可选的预计算嵌入向量或块嵌入向量列表。如果提供，则直接使用此项，且不调用嵌入器。多个向量需要匹配的 index_text 块列表或现有的存储块文本行。通过 None 在存储支持存储嵌入时显式清除存储嵌入。具有文本感知索引的存储还可以允许在没有嵌入或显式嵌入的情况下进行语义更新。
- metadata dict[str, Any] | None- 可选的替换元数据映射。传递 None 以在存储支持元数据时清除元数据。
- 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。
返回：更新的记录数，通常为 0 或 1。如果没有存储的记录与请求的逻辑标识符匹配，则返回 0。
返回类型： int
引发：ValueError - 如果更新有效负载对存储无效，例如省略每个可选字段或提供冲突的语义参数。

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 更改。使用 SchemaPolicy.CREATE_IF_NECESSARY 填充缺少的对象，或者使用 SchemaPolicy.RECREATE 删除和重新创建托管对象。SchemaPolicy.CREATE_IF_NECESSARY 可以应用受支持的托管模式版本升级，可以通过添加文本索引来升级向量模式以进行关键字搜索，也可以通过添加托管搜索结构和混合索引来进行混合搜索。
- vector_dim int | None- 用于本地向量存储的可选嵌入维。传递正整数以创建托管嵌入列和向量索引，并根据该维验证现有方案元数据。当此存储不需要本地向量存储时，传递 None 或省略该参数。关键字和混合搜索可以基于存储的搜索文本进行操作，而无需使用本地嵌入列。向量搜索需要本地向量存储。
- 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 或无前缀默认值。
- search_strategy SearchStrategy- 选择 search() 后端的 SearchStrategy 值。使用 SearchStrategy.VECTOR（默认值）进行仅向量检索，使用 SearchStrategy.HYBRID 在存储的搜索文本上查询托管的 Oracle 混合向量索引，或使用 SearchStrategy.KEYWORD 在没有向量融合的情况下按关键字/文本匹配对存储的搜索文本进行排名。KEYWORD 不需要嵌入。HYBRID 要求 embedder 为 OracleDBEmbedder，因此托管混合索引使用与主存储嵌入器相同的数据库内模型。如果关键字客户机打开现有的混合模式，则存储可以使用该混合索引的文本分支。当与现有方案一起使用不兼容的策略时，启动失败，因为该方案可能不包含策略所需的存储搜索状态。
- 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)。根据记录中存储的预期信息、应用程序保留它的原因以及任何应用程序或监管保留承诺选择此配置。

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

如果方案设置必须创建托管的过期记录清除作业，但数据库用户缺少调度程序 - 作业权限，则初始化将警告并继续。过期的消息和记忆不会被读取和搜索隐藏，但是在具有 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 list[str | None]- 记录要保留的有效负载。文本值也用于搜索文本，除非提供了 index_texts。当文本值为 None 时，存储可能会回退到 metadata["content"]。将保留显式空字符串。
- record_type str- 要创建的逻辑记录类型，例如 "message"、"memory"、"guideline"、"fact"、"preference"、"user_profile" 或 "agent_profile"。
- 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]- 与插入的记录关联的可选用户标识符。标量值可以在对齐的输入之间广播。
- 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" 作为回退源。
- ttl_days int | None | list[int | None]- 消息和类似内存的记录可选的生存时间持续时间（天）。省略此参数以使用托管方案中的 MemoryRetentionConfig.default_ttl_days。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. MemoryRetentionConfig.max_ttl_days 以上的值将夹到该最大值并显示警告。标量值可以在对齐的输入之间广播。
- ttl_anchor TimeToLiveAnchor | list[TimeToLiveAnchor]- 可选的生存时间锚。使用 TimeToLiveAnchor.CREATED_AT 可相对于数据库创建时间过期，或者使用 TimeToLiveAnchor.TIMESTAMP 可相对于提供的事件时间戳过期。如果省略，则失效使用 TimeToLiveAnchor.CREATED_AT。时间戳锚定到期要求每个插入的记录都有一个具体的 ISO-8601 时间戳。没有时区的 ISO-8601 时间戳将视为 UTC。
- **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_async`（异步）

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

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

参数：
- 内容 list[str | 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]
- store_kwargs Any
返回类型： list[str]

method `add_batches`

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

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

示例

store.add_batches(
    [
        PendingRecordBatch(
            texts=["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_user`

添加用户概要记录。

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

注

用户概要信息记录未受限制。插入的公共记录标识符与 user_id 传递的值相同。

示例

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

method `delete`

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

参数：
- record_type str- 要删除的记录类型标签。支持的类型包括 "thread"、"message"、"memory"、"guideline"、"fact"、"preference"、"user_profile" 和 "agent_profile"。
- 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_thread`

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

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

注

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

示例

store.delete_thread("c1")
0

method `get`

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

参数：
- record_type str- 解析为受管理行的记录类型标签，例如 "message"、"memory"、"guideline"、"fact"、"preference"、"user_profile" 或 "agent_profile"。
- record_id str- 要查找的标识符。
返回：找到时使用解码元数据填充的记录，否则为 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（方法）`list`

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

参数：
- record_type str- 记录类型标签（例如 "message"、"memory"、"guideline"、"fact"、"preference"、"user_profile" 或 "agent_profile"）。
- limit int | None- 要返回的可选最大记录数。如果省略，存储将使用其默认列表上限。传递 None 以禁用该上限并返回每个匹配记录。
- thread_id str | None- 精确的线程范围过滤器。如果省略，则不应用任何筛选。设置为 None 时，仅返回其 thread_id 为 SQL NULL 的行。未界定的记录类型会忽略此筛选器。
- 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"],
}
```
退货：按插入顺序排序的记录。
返回类型： list［记录］

注

"user_profile" 和 "agent_profile" 是不受限制的记录类型。对于这些记录类型，将忽略 thread_id、user_id 和 agent_id，角色标识保留在 record.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_thread_messages`

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

参数：
- thread_id str- 应返回其消息的线程标识符。
- last_n int | None- 要返回的最近消息的可选数量。
返回：按插入顺序排序的消息记录。
返回类型： list[ MessageRecord ]

示例

store.list_thread_messages("c1")
[]

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- 包括的可搜索记录类型的可选集。如果省略，数据库搜索将涵盖消息、内存表行和角色概要文件。Actor 配置文件贡献其 information 有效负载，而消息和内存行贡献其 content 有效负载。在搜索期间，概要信息记录类型将角色标识符用于适用的范围维，而其余范围维的行为方式为 None。
- metadata_filter dict[str, Any] | None- 可选的元数据过滤器映射。metadata_filter 中的条目与 AND 语义组合。值不是字段级运算符字典的条目使用完全匹配语义：所请求的关键字必须存在于存储的元数据中。嵌套字典以递归方式进行匹配。标量和列表值通过完全相等进行匹配；列表顺序和长度也必须匹配。要测试数组成员关系，请使用字段级运算符字典，例如 {"tags": {"$array_contains": "prod"}}。"$array_contains" 的列表操作数表示必须存在所有列出的值；"$array_contains_any" 表示必须至少存在一个列出的值。使用 "$not" 可否定同一字段中的另一个字段级表达式，包括运算符字典或原始完全匹配值。正表达式失败时（包括缺少的字段）匹配负表达式；负数数组成员资格也匹配非数组字段。
返回值：按增加距离排序的 (record, distance) 对。该列表可以包含少于 k 个条目。
返回类型： list[tuple[ Record ，float]]
引发：ValueError - 如果 k 小于 1，则如果同时提供或未提供 query 和 query_vector，如果 query 为空，如果向量模式无法解析查询嵌入，如果 query_vector 无效，或者如果 metadata_filter 无效。

示例

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"}} 等组合条件。
返回：底层 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- 要更新的存储行的标识符。
- text str | None- 可选替换文本保留在 content 列中。传递 None 以清除存储的文本并清除存储的嵌入。在同一调用中仅传递 None 或省略语义参数。传递 "" 以保留显式空内容，同时清除该记录的任何存储向量表示形式。省略时，现有内容保持不变。
- index_text str | list[str] | None- 可选的仅语义有效负载。省略时，text 用于语义索引。在支持混合的方案中，这也成为 Oracle 文本组件使用的存储搜索文本。存储可以对字符串值进行分块；列表值被视为调用方拥有的块，并按原样写入 RECORD_CHUNKS。仅提供 embedding 时，将重用现有的搜索文本。
- embedding list[float] | ndarray | list[list[float] | ndarray] | None-
  
  可选的预计算嵌入向量或块嵌入向量的列表。配置本地向量存储时，将直接使用此方法，并且不会调用嵌入器。传递 None 以清除存储的嵌入。单个向量表示提供 text 时的整个替换文本，即使配置的块会拆分该文本也是如此。替换文本时会拒绝多个块向量，除非 index_text 是块列表。仅提供 embedding 时，嵌入计数必须与记录的现有块行匹配。
  
  在 SearchStrategy.VECTOR 中，向量搜索根据存储的嵌入进行排名。在 SearchStrategy.HYBRID 或 SearchStrategy.KEYWORD 中，数据库支持的搜索按存储的搜索文本和 Oracle 管理的文本或混合索引状态进行排名，因此更新时嵌入仅影响任何配置的本地向量存储，而不影响该活动搜索策略。如果此存储是在没有本地向量存储的情况下配置的，请提供 index_text 而不是 embedding 以更新这些文本感知索引可见的文本。仅文本语义更新可以在这些模式下完全省略 embedding。
- metadata dict[str, Any] | None- 串行化到 JSON 并存储在 metadata 中的可选元数据映射。
- timestamp str | None- 与记录一起保存的可选新时间戳。它表示创建记录的时间。省略时，将保留现有时间戳。通过 None 清除保存的时间戳，并将数据库创建时间用于将来的 TimeToLiveAnchor.CREATED_AT 到期刷新。如果 ttl_anchor 为 TimeToLiveAnchor.TIMESTAMP，则不带时区的 ISO-8601 时间戳将视为 UTC。
- ttl_days int | None- 可选的到期刷新（天）。将此参数与 ttl_anchor 一起省略，以保留当前的失效时间戳。Pass None to use MemoryRetentionConfig.max_ttl_days when the retention configuration sets one, or to clear expiration when it does not. MemoryRetentionConfig.max_ttl_days 以上的值将夹到该最大值并显示警告。如果尚未清除过期记录，刷新失效可能会使过期记录再次可见。
- 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。
返回：更新的行数（0 或 1）。如果没有与 record_type 和 record_id 匹配的逻辑记录，则返回 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", text="Updated note")
1
store.get("memory", "mem-update-docs").content
'Updated note'

搜索策略

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_async（异步）

method add_batches

method add_batches_async（异步）

method add_user（抽象）

method delete（抽象）

method delete_thread（抽象）

method get（抽象）

method list（抽象）

method list_thread_messages（抽象）

method search（抽象）

method search_async（异步）

method update（抽象）

Oracle DB 存储

class oracleagentmemory.core.OracleDBMemoryStore

method add

method add_agent

method add_async（异步）

method add_batches

method add_batches_async（异步）

method add_user

method delete

method delete_thread

method get

method（方法）list

method list_thread_messages

method search

method search_async（异步）

method update

搜索策略

class oracleagentmemory.core.dbsearch.SearchStrategy

HYBRID = ‘ HYBRID ’

KEYWORD = ‘ KEYWORD ’

VECTOR = ‘ VECTOR ’

搜索索引同步模式

class oracleagentmemory.core.dbsearch.SearchIndexSyncMode

AUTO = ‘ AUTO ’

MANUAL = ‘ MANUAL ’

ON_COMMIT = ‘ ON_COMMIT ’

生存时间

class oracleagentmemory.core.retention.MemoryRetentionConfig

class oracleagentmemory.apis.ttl.TimeToLiveAnchor

CREATED_AT = ‘ CREATED_AT ’

TIMESTAMP = ‘ TIMESTAMP ’

模式策略

class oracleagentmemory.core.SchemaPolicy

需要现有

CREATE_IF_EMPTY

需要 CREATE_IF_

重新创建

class `oracleagentmemory.core.OracleMemoryStore`

method `add`

method `add_agent`（抽象）

method `add_async`（异步）

method `add_batches`

method `add_batches_async`（异步）

method `add_user`（抽象）

method `delete`（抽象）

method `delete_thread`（抽象）

method `get`（抽象）

method `list`（抽象）

method `list_thread_messages`（抽象）

method `search`（抽象）

method `search_async`（异步）

method `update`（抽象）

class `oracleagentmemory.core.OracleDBMemoryStore`

method `add`

method `add_agent`

method `add_async`（异步）

method `add_batches`

method `add_batches_async`（异步）

method `add_user`

method `delete`

method `delete_thread`

method `get`

method（方法）`list`

method `list_thread_messages`

method `search`

method `search_async`（异步）

method `update`

class `oracleagentmemory.core.dbsearch.SearchStrategy`

class `oracleagentmemory.core.dbsearch.SearchIndexSyncMode`

class `oracleagentmemory.core.retention.MemoryRetentionConfig`

class `oracleagentmemory.apis.ttl.TimeToLiveAnchor`

class `oracleagentmemory.core.SchemaPolicy`