存储和方案

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

存储 API

class oracleagentmemory.core.OracleMemoryStore

基础：IMemoryStore

OracleAgentMemory 使用的公用存储接口。

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

method add（抽象）

嵌入和保留文本记录。

• 参数：
  • contents list[str | None]- 要存储的文本有效负载。如果未提供 index_texts，这些值也用作嵌入有效负载。如果省略项 (None)，则在可用时存储元数据关键字 "content" 中的解析项；否则保留空内容。
  • record_type str- 存储记录的记录类型标签（例如 "message" 或 "memory"）。
  • index_texts list[str]- 可选的仅嵌入有效负载，与 contents 对齐。
  • embeddings list[list[float]] | list[ndarray]- 与 contents 对齐的可选预计算嵌入向量。如果提供，存储将直接使用这些向量，而不调用嵌入器。
  • record_ids str | None | list[str] | list[None]- 可选的调用方可见记录 ID。必须为所有文本提供（每文本一个）或省略。返回的 ID 在提供时与这些值匹配。
  • thread_ids str | None | list[str | None]- 随记录一起存储的可选范围标识符。
  • user_ids str | None | list[str | None]- 随记录一起存储的可选范围标识符。
  • agent_ids str | None | list[str | None]- 随记录一起存储的可选范围标识符。
  • roles str | None | list[str | None]- 消息记录的可选聊天角色。
  • timestamps str | None | list[str | None]- 可选时间戳或每记录时间戳。
  • metadata dict[str, Any] | list[dict[str, Any] | None] | None- 可选的元数据映射或按记录的元数据映射。元数据可以包括 "content" 作为省略的文本值的回退源。
  • **store_kwargs ( Any )- 高级 API 转发的特定于存储的写入选项。
• 返回：插入每个输入内容项的标识符。如果提供，这些值与 record_ids 匹配；否则，存储生成标识符。
• 返回类型： list[str]

示例

store.add(["Abstract memory"], record_type="memory", record_ids="mem-abstract-docs")
['mem-abstract-docs']

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

将记录添加到内存存储。

• 参数：
  • contents list[str | None]- 要存储的文本有效负载。除非提供了 index_texts 或 embeddings，否则这些值还用于计算嵌入。省略项 (None) 时，存储元数据关键字 "content" 中的解析项（如果可用）；否则保留空内容。
  • record_type str- 存储记录的记录类型标签（例如 "message"、"memory"、guideline、fact 或 preference）。
  • index_texts list[str]- 仅用于嵌入/索引的可选替代有效负荷。提供时，长度必须与 contents 相同。
  • embeddings list[list[float]] | list[ndarray]- 与 contents 对齐的可选预计算嵌入向量。如果提供，门店必须直接使用这些向量，且不得调用嵌入器。省略时，存储仅对非空索引有效负载使用嵌入器；显式空字符串在存储时不使用块嵌入。
  • record_ids str | None | list[str] | list[None]- 可选的调用方可见记录 ID。必须为所有文本提供（每文本一个）或省略。返回的 ID 在提供时与这些值匹配。如果省略，存储将生成客户端 ID。
  • thread_ids str | None | list[str | None]- 随记录一起存储的可选范围标识符。
  • user_ids str | None | list[str | None]- 随记录一起存储的可选范围标识符。
  • agent_ids str | None | list[str | None]- 随记录一起存储的可选范围标识符。
  • roles str | None | list[str | None]- 消息记录的可选聊天角色。
  • timestamps str | None | list[str | None]- 可选的调用方提供的事件时间戳。
  • metadata dict[str, Any] | list[dict[str, Any] | None] | None- 可选的调用方提供的元数据字典。元数据可以包括 "content" 作为省略的文本值的回退源。
  • **store_kwargs ( Any )- 特定于存储的写入选项。对于 Oracle executemany 批处理，支持的密钥当前包括 batch_size。
• 返回：插入每个输入内容项的标识符。如果提供，这些值与 record_ids 匹配；否则，存储返回的 ID。
• 返回类型： list[str]

示例

store.add(
    ["Hello from docs"],
    record_type="message",
    record_ids="msg-docs-add",
    thread_ids="c-docs-add",
    roles="user",
)
['msg-docs-add']

method add_agent

添加代理概要记录。

• 参数：
  • agent_id str- 代理标识符。
  • information str- 关于代理的自由格式信息。
• 退货：插入的代理概要信息记录的标识符。
• 返回类型： str

示例

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

method add_user

添加用户概要记录。

• 参数：
  • user_id str- 用户标识符。
  • information str- 关于用户的自由格式信息。
• 返回：插入的用户配置文件记录的标识符。
• 返回类型： str

示例

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

method delete

按标识符删除受管向量记录行及其块行。

• 参数：
  • record_type str- 应将其托管表作为目标的记录类型标签，例如 "message"、"memory"、"guideline"、"fact" 或 "preference"
  • record_id str- 要删除的行的标识符。
• 返回值：删除的行数（未找到标识符时为 0）。
• 返回类型： int

示例

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"。
  • 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"）。
  • limit int- 要返回的最大记录数。
  • thread_id str | None- 精确的线程范围过滤器。如果省略，则不应用任何筛选。设置为 None 时，仅返回线程维上未作用域的记录。
  • user_id str | None- 精确的用户范围过滤器。如果省略，则不应用任何筛选。设置为 None 时，仅返回用户维上未作用域的记录。
  • agent_id str | None- 精确代理范围过滤器。如果省略，则不应用任何筛选。设置为 None 时，仅返回未在代理维上作用域的记录。
  • metadata_filter dict[str, Any] | None- 元数据过滤器。如果省略，则不应用任何筛选。设置为 None 时，仅返回没有存储元数据的记录。设置为 dict 时，存储的元数据必须包含所有请求的键和值。嵌套字典以递归方式进行匹配。列表值通过完全相等而不是递归子集匹配进行匹配，因此列表顺序和长度也必须匹配。
• 退货：按插入顺序排序的记录。
• 返回类型： list［记录］

示例

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']

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- 要包括的记录类型的可选集。如果省略，搜索将涵盖任何记录类型。
  • 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）
  • 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_

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

重新创建

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