全部產品
Search

搜尋本產品

    Tablestore：記憶庫操作

    文件中心

    Tablestore：記憶庫操作

    更新時間：Jul 03, 2026

    本文檔介紹命令列工具中記憶庫（Agent Memory）相關的命令及參數，覆蓋記憶庫管理、記憶寫入、記憶檢索、記憶單元管理、審計查詢和 Scope 使用規則。

    前置條件

    • 已完成命令列工具的安裝與訪問憑證配置。具體操作，請參見命令列工具。

    • 推薦預先配置預設 scope（如 memory_store_name、memory_app_id 等），以便後續命令省略對應參數。

    記憶庫管理

    記憶庫是 Agent 長期記憶的儲存容器，支援寫入、檢索、審計的全流程操作。

    建立記憶庫

    tablestore-agent-cli memory create --store agent_memory --description "長期記憶庫"

    如果已通過 configure set memory_store_name 配置預設記憶庫名，可省略 --store：

    tablestore-agent-cli configure set memory_store_name agent_memory
tablestore-agent-cli memory create --description "長期記憶庫"

    列出記憶庫

    tablestore-agent-cli memory ls
tablestore-agent-cli memory list --limit 50 --next-token <token>

    memory ls 是 memory list 的別名。

    說明

    記憶庫的 list 命令不會自動翻頁，僅返回單頁結果。如需擷取下一頁，請將響應中的 nextToken 通過 --next-token 參數傳入。

    查看記憶庫

    tablestore-agent-cli memory describe --store agent_memory
tablestore-agent-cli memory show --store agent_memory

    memory show 是 memory describe 的別名。

    更新記憶庫描述

    tablestore-agent-cli memory update --store agent_memory --description "新的描述"

    刪除記憶庫

    重要

    刪除記憶庫會清除其下全部記憶資料，且不可恢複。請謹慎操作。

    tablestore-agent-cli memory delete --store agent_memory   # TTY 環境下會提示確認
tablestore-agent-cli memory rm --store agent_memory -y    # 跳過確認

    memory rm 是 memory delete 的別名。

    寫入記憶

    向指定 scope 寫入一條或多條記憶。

    單條文本寫入

    tablestore-agent-cli memory add --store agent_memory --app-id app-001 --text "使用者喜歡麻婆豆腐"

    同步等待提取完成

    預設情況下，寫入命令非同步返回。如需等待記憶提取完成後再返回，使用 --sync 參數：

    tablestore-agent-cli memory add --store agent_memory --app-id app-001 --text "使用者偏好川菜" --sync

    通過 JSON 檔案批量寫入

    tablestore-agent-cli memory add --store agent_memory --app-id app-001 --messages-file ./messages.json

    messages.json 需包含一個 JSON 數組。

    附加中繼資料

    tablestore-agent-cli memory add --store agent_memory --app-id app-001 --text "使用者偏好川菜" --metadata '{"source":"chat","confidence":"high"}'

    參數說明

    參數

    必填

    預設值

    說明

    --store

    否

    配置項 memory_store_name

    記憶庫名稱。

    --app-id

    未配置預設值時必填

    配置項 memory_app_id

    scope 中最關鍵的參數，用於業務隔離。

    --tenant-id

    否

    配置項 memory_tenant_id

    租戶 ID。

    --agent-id

    否

    配置項 memory_agent_id

    Agent ID。

    --run-id

    否

    配置項 memory_run_id

    單次會話或運行 ID。

    --text

    二選一

    —

    記憶常值內容。

    --messages-file

    二選一

    —

    批量寫入的 JSON 檔案路徑。

    --metadata

    否

    —

    Metadata JSON 字串。必須是 string key / string value 的對象。與 --metadata-file 互斥。

    --metadata-file

    否

    —

    Metadata JSON 檔案路徑。

    --sync

    否

    false

    是否等待提取完成。
    重要

    寫入命令的 scope 參數不允許使用萬用字元 *。

    記憶檢索

    針對指定 scope 執行語義檢索。

    基礎檢索

    tablestore-agent-cli memory search --store agent_memory --app-id app-001 --tenant-id tenant-001 --query "使用者喜歡什麼食物" --top-k 5

    關閉重排

    tablestore-agent-cli memory search --store agent_memory --app-id app-001 --tenant-id tenant-001 --query "使用者偏好" --disable-rerank

    通過 Metadata 過濾

    tablestore-agent-cli memory search --store agent_memory --app-id app-001 --tenant-id tenant-001 --query "使用者偏好" --metadata '{"source":{"equals":"chat"}}'

    參數說明

    參數

    預設值

    說明

    --top-k

    10

    返回結果數量。取值範圍 0~50。

    --enable-rerank

    true

    是否啟用重排。使用 --disable-rerank 關閉。

    --metadata

    —

    Metadata 過濾 JSON 字串。與 --metadata-file 互斥。

    --metadata-file

    —

    Metadata 過濾 JSON 檔案路徑。
    說明

    檢索命令的 scope 參數允許使用萬用字元 *。

    返回樣本

    {"items":[{"memory":{"id":"mem-001","text":"使用者喜歡麻婆豆腐"},"score":0.91}],"totalCount":1}

    管理記憶單元

    記憶單元（Memory Unit）是記憶庫的最小資料單位。

    列出記憶單元

    tablestore-agent-cli memory list-units --store agent_memory --app-id app-001
tablestore-agent-cli memory ls-units --store agent_memory --app-id app-001 --limit 20 --next-token <token>

    memory ls-units 是 memory list-units 的別名。該命令僅返回單頁結果，如需翻頁請手動傳入 --next-token。

    查看記憶單元

    tablestore-agent-cli memory get --store agent_memory --memory-id mem-001 --app-id app-001
tablestore-agent-cli memory cat --store agent_memory --memory-id mem-001 --app-id app-001

    memory cat 是 memory get 的別名。

    更新記憶單元

    # 更新文本
tablestore-agent-cli memory update-unit --store agent_memory --memory-id mem-001 --app-id app-001 --text "使用者強烈偏好辛辣食物"

# 更新 Metadata
tablestore-agent-cli memory update-unit --store agent_memory --memory-id mem-001 --app-id app-001 --metadata '{"confidence":"very_high"}'

    --text 和 --metadata 至少需要指定一個。

    刪除記憶單元

    tablestore-agent-cli memory delete-unit --store agent_memory --memory-id mem-001 --app-id app-001
tablestore-agent-cli memory rm-unit --store agent_memory --memory-id mem-001 --app-id app-001 -y

    memory rm-unit 是 memory delete-unit 的別名。

    Scope 萬用字元使用規則

    命令

    是否允許萬用字元 *

    list-units / ls-units

    允許

    get / cat

    不允許

    update-unit

    不允許

    delete-unit / rm-unit

    不允許

    審計：訊息與請求

    查看原始訊息記錄

    tablestore-agent-cli memory msg-list --store agent_memory --app-id app-001
tablestore-agent-cli memory ls-msgs --store agent_memory --app-id app-001

    memory ls-msgs 是 memory msg-list 的別名。

    查看請求審計記錄

    tablestore-agent-cli memory req-list --store agent_memory --app-id app-001
tablestore-agent-cli memory req-list --store agent_memory --app-id app-001 --operation AddMemories
tablestore-agent-cli memory ls-reqs --store agent_memory --app-id app-001

    memory ls-reqs 是 memory req-list 的別名。--operation 用於按操作類型過濾，如 AddMemories、SearchMemories 等。

    參數說明

    參數

    預設值

    說明

    --limit

    msg-list: 200；req-list: 50

    單頁返回數量。

    --next-token

    —

    翻頁 token。

    --operation

    —

    操作類型過濾。僅 req-list 支援。
    說明

    審計類命令僅返回單頁結果，如需擷取後續資料請手動傳入 --next-token。

    Scope 層級與萬用字元

    記憶庫的 scope 由四級 ID 組成，層級從大到小依次為：

    appId  →  tenantId  →  agentId  →  runId

    Scope 參數

    是否必填

    說明

    --app-id

    未配置預設值時必填

    業務應用 ID。scope 中最關鍵的參數。

    --tenant-id

    否

    租戶 ID。

    --agent-id

    因命令而異（詳見下方）

    Agent ID。

    --run-id

    否

    單次會話或運行 ID。

    --agent-id 必填規則：以下命令實際調用時要求 --agent-id 必傳（即使已通過 configure set memory_agent_id 配置預設值，也需要顯式傳入）：

    • get / cat

    • update-unit

    • delete-unit / rm-unit

    • msg-list / ls-msgs

    其餘命令（add、search、list-units、req-list 等）可省略 --agent-id，Server 將使用配置項或預設值。

    萬用字元 * 的使用規則：

    • 允許使用萬用字元的命令：檢索類（search）、列表類（list-units、msg-list、req-list）。

    • 不允許使用萬用字元的命令：寫入類（add）、單條擷取（get）、更新（update-unit）、刪除（delete-unit）。

    分頁說明

    記憶庫的所有 list 類命令僅返回單頁結果，不會自動翻頁。如需繼續擷取，請手動將響應中的 nextToken 通過 --next-token 參數傳入：

    tablestore-agent-cli memory list-units --store agent_memory --app-id app-001 --next-token <token>

    這與知識庫的 kb list、kb doc-list 自動翻頁行為不同，使用時請注意區分。