存储和方案

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

存储 API

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]- 仅用于嵌入/索引的可选替代有效负荷。如果提供，则必须与文本输入保持一致。
- embeddings list[list[float]] | list[ndarray]- 与文本输入对齐的可选预计算嵌入向量。如果提供，存储必须直接使用这些向量，而不是调用其嵌入器。如果未提供，门店必须附加嵌入器，否则将引发错误。
- 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]- 与记录一起保留的可选事件时间戳。标量值可以在对齐的文本输入之间广播。
- metadata dict[str, Any] | list[dict[str, Any] | None] | None- 可选的调用方提供的元数据字典。如果省略了文本值，而不是显式设置为 ""，则元数据可以包括 "content" 作为回退源。
- **store_kwargs ( Any )- 特定于实现的写入选项，转发到具体存储。
返回类型： list[str]

注

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

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

method `add_agent`（抽象）

添加代理概要记录。

参数：
- agent_id str- 代理配置文件的稳定标识符。
- information str- 描述代理的自由格式文本。
退货：已创建的代理概要信息记录的标识符。
返回类型： str

method `add_async`（异步）

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

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

参数：
- 内容 list[str | None]
- record_type str
- index_texts list[str]
- embeddings（嵌入）list[list[float]] | list[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] | list[dict[str, Any] | None] | None
- 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- 描述用户的自由格式文本。
退货：创建的用户配置文件记录的标识符。
返回类型： 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 的记录。未界定的记录类型会忽略此筛选器。
返回：在返回的窗口中按从最早到最新顺序排序的记录。
返回类型： 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。
- 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- 可选的部分元数据映射。仅当记录的存储元数据包含所有请求的键和值时，记录才会匹配。嵌套字典以递归方式进行匹配。列表值通过完全相等而不是递归子集匹配进行匹配，因此列表顺序和长度也必须匹配。
返回值：按增加距离排序的 (record, distance) 对。
返回类型： 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

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 接受的可选记录类型过滤器相同。
返回：底层 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 | None- 可选的仅嵌入有效负载，用于重新计算存储的向量而不更改持久文本。
- embedding list[float] | ndarray | None- 可选的预计算嵌入向量。如果提供，则直接使用此项，且不调用嵌入器。通过 None 在存储支持存储嵌入时显式清除存储嵌入。
- metadata dict[str, Any] | None- 可选的替换元数据映射。传递 None 以在存储支持元数据时清除元数据。
返回：更新的记录数，通常为 0 或 1。如果没有存储的记录与请求的逻辑标识符匹配，则返回 0。
返回类型： int
引发：ValueError - 如果更新有效负载对存储无效，例如省略每个可选字段或提供冲突的语义参数。

Oracle DB 存储

class `oracleagentmemory.core.OracleDBMemoryStore`

基础：OracleMemoryStore

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

创建 Oracle DB 存储。

参数：
- embedder IEmbedder | None- 用于向量化记录类型的嵌入程序。当调用方始终在 add、update 和 search 中提供预计算向量时，可以是 None。
- pool Any-Oracle DB 连接或池。通过原始连接可为此存储实例启用单会话模式：并发存储调用在本地进行序列化，以保留写入操作使用的行锁和事务处理假设。将连接池用于并发请求。
- schema_policy SchemaPolicy | str- 模式设置模式。默认为需要现有的新型托管方案，且无需执行 DDL 更改。使用 SchemaPolicy.CREATE_IF_NECESSARY 填充缺少的对象，或者使用 SchemaPolicy.RECREATE 删除和重新创建托管对象。
- vector_dim int- 在创建 VECTOR 列时嵌入维以创建方案。
- table_name_prefix str- 添加到受管理表/索引名称的可选前缀。

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]- 仅用于嵌入/索引的可选替代有效负荷。如果提供，则必须与文本输入保持一致。
- embeddings list[list[float]] | list[ndarray]- 与文本输入对齐的可选预计算嵌入向量。如果提供，存储必须直接使用这些向量，而不是调用其嵌入器。如果未提供，门店必须附加嵌入器，否则将引发错误。
- 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]- 与记录一起保留的可选事件时间戳。标量值可以在对齐的文本输入之间广播。
- metadata dict[str, Any] | list[dict[str, Any] | None] | None- 可选的调用方提供的元数据字典。如果省略了文本值，而不是显式设置为 ""，则元数据可以包括 "content" 作为回退源。
- **store_kwargs ( Any )- 特定于实现的写入选项，转发到具体存储。
返回类型： list[str]

注

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

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

method `add_async`（异步）

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

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

参数：
- 内容 list[str | None]
- record_type str
- index_texts list[str]
- embeddings（嵌入）list[list[float]] | list[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] | list[dict[str, Any] | None] | None
- 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_agent`

添加代理概要记录。

参数：
- agent_id str- 代理标识符。
- information str- 关于代理的自由格式信息。此文本存储为概要信息内容，用于在 RECORD_CHUNKS 中构建概要信息嵌入行。
退货：插入的代理概要信息记录的标识符。
返回类型： str

注

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

示例

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

method `add_user`

添加用户概要记录。

参数：
- user_id str- 用户标识符。
- information str- 关于用户的自由格式信息。此文本存储为概要信息内容，用于在 RECORD_CHUNKS 中构建概要信息嵌入行。
返回：插入的用户配置文件记录的标识符。
返回类型： 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

注

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

示例

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 时，存储的元数据必须包含所有请求的键和值。嵌套字典以递归方式进行匹配。列表值通过完全相等而不是递归子集匹配进行匹配，因此列表顺序和长度也必须匹配。
退货：按插入顺序排序的记录。
返回类型： 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`

按相似性搜索记录。

参数：
- query str | None- 自然语言查询。必须在省略 query_vector 时提供。
- query_vector list[float] | None- 可选的预计算查询嵌入。只能提供 query 和 query_vector 中的一个。
- k int- 要返回的最大结果数量。显式值必须至少为 1。
- 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- 可选的部分元数据映射。仅当记录的存储元数据包含所有请求的键和值时，记录才会匹配。嵌套字典以递归方式进行匹配。列表值通过完全相等而不是递归子集匹配进行匹配，因此列表顺序和长度也必须匹配。
返回值：按增加距离排序的 (record, distance) 对。
返回类型： list[tuple[ Record ，float]]
引发：ValueError - 如果 k 小于 1。

示例

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

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 接受的可选记录类型过滤器相同。
返回：底层 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 | None- 可选的仅嵌入有效负载。如果省略，则嵌入 text。
- embedding list[float] | ndarray | None- 可选的预计算嵌入向量。如果提供，则直接使用此项，且不调用嵌入器。传递 None 以清除存储的嵌入。
- metadata dict[str, Any] | None- 串行化到 JSON 并存储在 metadata 中的可选元数据映射。
返回：更新的行数（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.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_async（异步）

method add_batches

method add_batches_async（异步）

method add_agent

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

method `add_batches`

method `add_batches_async`（异步）

method `add_agent`

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.SchemaPolicy`