商店與綱要

此頁面顯示 Oracle 代理程式記憶體 SDK 使用的核心存放區摘要和綱要控制項。

儲存 API

類別 `oracleagentmemory.core.OracleMemoryStore`

基本：IMemoryStore

OracleAgentMemory 使用的通用儲存介面。

商店實施負責保存文字記錄，並對其執行相似性搜尋。同時定義了同步和非同步進入點，因此高階 API 可以公開相符的同步 / 非同步曲面，而不需要複製儲存特定邏輯。

方法 `search` (摘要)

依相似性搜尋記錄。

參數：
- 查詢 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[ 記錄，浮動 ]]
發出：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 商店

類別 `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 – 新增至受管理表格 / 索引名稱的選擇性前置碼。

方法 `add_agent`

新增專員資料檔記錄。

參數：
- agent_id str – 代理程式 ID。
- 資訊 str – 代理程式的任意格式資訊。此文字會儲存為基本資料內容，並用於在 RECORD_CHUNKS 中建置基本資料內嵌資料列。
傳回：插入的專員資料檔記錄的識別碼。
傳回類型： str

注意事項

專員資料檔記錄未作用領域。插入的公用記錄 ID 與傳送為 agent_id 的值相同。

範例

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

方法 `add_user`

新增使用者基本資料記錄。

參數：
- user_id str – 使用者 ID。
- 資訊 str – 使用者的任意格式資訊。此文字會儲存為基本資料內容，並用於在 RECORD_CHUNKS 中建置基本資料內嵌資料列。
傳回：插入之使用者設定檔記錄的識別碼。
傳回類型： str

注意事項

使用者資料檔記錄未作用領域。插入的公用記錄 ID 與傳送為 user_id 的值相同。

範例

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

方法 `delete`

依 ID 刪除一個受管理資料列及其區塊資料列。

參數：
- record_type str – 要刪除的記錄類型標籤。支援的類型包括 "thread"、"message"、"memory"、"guideline"、"fact"、"preference"、"user_profile" 和 "agent_profile"。
- record_id str – 要刪除的識別碼。
- cascade bool – 當 True 時，將支援的最上層目標 (例如動作者設定檔) 展開至相同交易內的作用領域子項資料列。對於使用者設定檔或代理程式設定檔目標，這會先刪除擁有的繫線資料列，移除其繫線作用領域訊息和記憶體表格資料列，然後刪除其餘的直接作用領域訊息和類似記憶體的資料列 (memory、guideline、fact、preference)。當相符的基本資料列已不存在時，此作用領域清除仍會執行。
傳回：已移除要求的最上層目標數目，通常為 0 或 1。串連的子項資料列不會個別計算，因此當遺漏的動作者設定檔觸發範圍清除時，這仍可能是 0。
傳回類型：整數

注意事項

此作業會在一個交易內執行。當支援的最上層目標啟用 cascade 時，會同時確認或倒回設定檔刪除和所有作用領域子項刪除。

範例

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

方法 `delete_thread`

刪除執行緒及其關聯的儲存資料列。

參數： thread_id str – 應移除其資料列的繫線 ID，包括繫線資料列、相依子項資料列，以及明確的區塊資料列清除。
傳回：已刪除的繫線資料列數目 (0 或 1)。
傳回類型：整數

注意事項

當您需要執行緒作用領域的連鎖清除時，請使用此作業。在資料庫備份存放區中，刪除繫線會移除受管理繫線資料列與相關聯的訊息和記憶體資料列，以及保留供擷取的記錄區塊資料列。這比訊息階層刪除大，僅會移除原始訊息列。執行緒刪除會移除從 THREAD 參考的相依訊息與記憶體資料列，以及相同交易中相符的 RECORD_CHUNKS 資料列。

範例

store.delete_thread("c1")
0

方法 `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'

方法 `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 時，只會傳回沒有儲存中繼資料的記錄。設定為字典時，儲存的中繼資料必須包含所有要求的關鍵碼與值。巢狀字典會遞迴比對。清單值會比對完全相等而非遞迴子集比對，因此清單順序與長度也必須相符。
退貨：依插入順序排序的記錄。
傳回類型： 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

方法 `list_thread_messages`

傳回繫線的持續訊息。

參數：
- thread_id str – 應傳回其訊息的繫線 ID。
- last_n int | None – 要傳回之最近訊息的選擇性數目。
傳回：依插入順序排列的訊息記錄。
傳回類型： list[ MessageRecord ]

範例

store.list_thread_messages("c1")
[]

方法 `search`

依相似性搜尋記錄。

參數：
- 查詢 str | None – 自然語言查詢。省略 query_vector 時必須提供。
- query_vector list[float] | None – 選用的預先計算查詢內嵌。只能提供 query 和 query_vector 其中之一。
- k int – 要傳回的結果數目上限。明確值必須至少為 1。
- thread_id str | None – 選擇性繫線範圍 ID。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 – 選擇性部分中繼資料對應。只有當記錄的已儲存中繼資料包含所有要求的索引鍵與值時，記錄才會相符。巢狀字典會遞迴比對。清單值會比對完全相等而非遞迴子集比對，因此清單順序與長度也必須相符。
傳回：以增加距離排序的 (record, distance) 組。
傳回類型： list[tuple[ 記錄，浮動 ]]
發出：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

方法 `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 – 選用的僅限內嵌有效負載 (Payload)。省略時，會內嵌 text。
- embedding list[float] | ndarray | None – 可選的預先計算嵌入向量。提供時，會直接使用，不會呼叫內嵌程式。傳送 None 以清除儲存的內嵌。
- 中繼資料 dict[str, Any] | None – 序列化至 JSON 並儲存在 metadata 中的選擇性中繼資料對應。
傳回：更新的資料列數目 (0 或 1)。當沒有符合 record_type 和 record_id 的邏輯記錄時，傳回 0。
傳回類型：整數
發出：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'

綱要原則

類別 `oracleagentmemory.core.SchemaPolicy`

基礎：str、Enum

Oracle DB 存放區的綱要建立原則。

需求 _ 現有

驗證完整受管理綱要已經存在且為最新狀態。請勿建立或修改資料庫物件。

空白建立 (_I)

如果沒有受管理物件，啟動安裝綱要。如果物件已經存在，則需要完整且最新的受管理綱要。

需要建立 (_I)

只建立遺漏的受管理物件，包括描述資料。

重新建立

刪除並重新建立所有受管理綱要物件。這是破壞性的。

商店與綱要

儲存 API

類別 oracleagentmemory.core.OracleMemoryStore

方法 search (摘要)

Oracle DB 商店

類別 oracleagentmemory.core.OracleDBMemoryStore

方法 add_agent

方法 add_user

方法 delete

方法 delete_thread

方法 get

方法 list

方法 list_thread_messages

方法 search

方法 update

綱要原則

類別 oracleagentmemory.core.SchemaPolicy

需求 _ 現有

空白建立 (_I)

需要建立 (_I)

重新建立

類別 `oracleagentmemory.core.OracleMemoryStore`

方法 `search` (摘要)

類別 `oracleagentmemory.core.OracleDBMemoryStore`

方法 `add_agent`

方法 `add_user`

方法 `delete`

方法 `delete_thread`

方法 `get`

方法 `list`

方法 `list_thread_messages`

方法 `search`

方法 `update`

類別 `oracleagentmemory.core.SchemaPolicy`