商店與綱要

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

儲存 API

類別 `oracleagentmemory.core.OracleMemoryStore`

基本：IMemoryStore

OracleAgentMemory 使用的通用儲存介面。

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

方法 `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] – 儲存在記錄中的選擇性範圍識別碼。
- 角色 str | None | list[str | None] – 訊息記錄的選擇性交談角色。
- 時間戳記 str | None | list[str | None] – 選擇性時間戳記或每個記錄時間戳記。
- 中繼資料 dict[str, Any] | list[dict[str, Any] | None] | None – 選擇性中繼資料對應或每個記錄中繼資料對應。中繼資料可以包含 "content" 作為省略文字值的備用來源。
- **store_kwargs ( 任一 ) – 由較高層級 API 轉送的存放區特定寫入選項。
傳回：插入每個輸入內容項目的 ID。若有提供，則比對 record_ids；否則會儲存產生識別碼。
傳回類型： list[str]

範例

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

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

新增記錄至記憶體存放區。

參數：
- 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] – 儲存在記錄中的選擇性範圍識別碼。
- 角色 str | None | list[str | None] – 訊息記錄的選擇性交談角色。
- 時間戳記 str | None | list[str | None] – 選擇性呼叫程式提供的事件時間戳記。
- 中繼資料 dict[str, Any] | list[dict[str, Any] | None] | None – 選擇性呼叫程式提供的中繼資料字典。中繼資料可以包含 "content" 作為省略文字值的備用來源。
- **store_kwargs ( 任一 ) – 儲存特定寫入選項。支援的金鑰目前包含 batch_size，適用於 Oracle executemany 批次處理。
傳回：插入每個輸入內容項目的 ID。若有提供，則比對 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']

方法 `add_agent`

新增專員資料檔記錄。

參數：
- agent_id str – 代理程式 ID。
- 資訊 str – 代理程式的任意格式資訊。
傳回：插入的專員資料檔記錄的識別碼。
傳回類型： str

範例

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

方法 `add_user`

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

參數：
- user_id str – 使用者 ID。
- 資訊 str – 使用者的任意格式資訊。
傳回：插入之使用者設定檔記錄的識別碼。
傳回類型： str

範例

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

方法 `delete`

刪除受管理向量記錄資料列及其依識別碼的區塊資料列。

參數：
- record_type str – 受管理表格的目標記錄類型標籤，例如 "message"、"memory"、"guideline"、"fact" 或 "preference"
- record_id str – 要移除之資料列的識別碼。
傳回：移除的資料列數目 (找不到 ID 時為 0)。
傳回類型：整數

範例

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)。
傳回類型：整數

範例

store.delete_thread("c1")
0

方法 `get`

依 ID 擷取儲存的訊息或記憶體。

參數：
- 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'

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

方法 `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 – 要包含的選擇性記錄類型集合。省略時，搜尋會涵蓋任何記錄類型。
- 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)
- record_id str – 要更新之訊息或記憶體資料列的 ID。
- 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

方法 add (摘要)

方法 search (摘要)

Oracle DB 商店

類別 oracleagentmemory.core.OracleDBMemoryStore

方法 add

方法 add_agent

方法 add_user

方法 delete

方法 delete_thread

方法 get

方法 list

方法 list_thread_messages

方法 search

方法 update