存储和方案

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

存储 API

class oracleagentmemory.core.OracleMemoryStore

基础：IMemoryStore

OracleAgentMemory 使用的公用存储接口。

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

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

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_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 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_

仅创建缺少的托管对象，包括元数据。

重新创建

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