記憶庫使用指南 - AgentLoop

AgentLoop 記憶庫能夠從應用對話中提取長期記憶，供應用後續互動時檢索和使用。本文介紹如何建立記憶庫、配置應用接入、寫入對話並檢索長期記憶，最後通過一個烹飪助手樣本示範完整流程。首次使用建議依次完成三個檢查：對話寫入請求成功、能夠檢索到相關長期記憶、應用將檢索結果加入 Agent 請求。基礎概念請參見記憶庫產品介紹。

前提條件

已建立智能體空間，並能夠進入該空間的 AgentLoop 控制台。
已確定要接入的應用和一組用於驗證的樣本對話。
準備通過介面寫入時，本地或應用運行環境能夠存取控制台提供的 Endpoint。本文的 HTTP 樣本使用 curl。

步驟一：建立記憶庫

重要

建立的記憶庫需要資源準備，準備完成前無法寫入對話。首次寫入前，請按整合方式頁簽的提示預留準備時間，並確認資源已就緒。

登入 AgentLoop 控制台，選擇目標地區和智能體空間。
從左側導覽列選擇上下文工程，切換到記憶庫頁簽。

單擊建立記憶庫，填寫以下資訊。

參數	是否必填	說明
記憶庫名稱	是	輸入便於識別的名稱，例如 `cooking_memory`
記憶庫描述資訊	否	說明用途和適用應用，例如“儲存烹飪助手使用者的飲食偏好”

單擊確認。
建立後，在記憶庫的概覽頁簽檢查名稱和描述，確認後續操作的是目標記憶庫。頁面還會展示建立時間、更新時間等資訊。

步驟二：建立 API Key

進入記憶庫詳情頁，切換到 API Key 頁簽。
尚未建立 API Key 時，單擊立即建立，按頁面提示完成建立。
複製 API Key，供應用接入時使用。
API Key 為訪問對應記憶庫的請求提供鑒權，與記憶庫和智能體空間綁定。使用當前頁面提供的記憶介面時，無需另外傳入記憶庫名稱和空間名稱。建議通過服務端環境變數或應用的密鑰管理方式儲存 API Key，避免寫入代碼倉庫或暴露在瀏覽器前端。

步驟三：接入應用並寫入對話

選擇接入方式

進入整合方式頁簽，可以選擇以下方式：

方式	適用情況	操作入口
HTTP API	希望先用命令列驗證，或從其他語言發起 HTTP 要求	選擇 HTTP API，複製訪問配置和請求樣本
Python SDK	希望在 Python 應用內使用 mem0 相容介面；不等於任意 SDK 版本和所有擴充方法都已經完成適配	選擇 Python SDK，按頁面提供的安裝和調用樣本接入

本文後續以 HTTP API 為例示範。建議使用頁面中的複製按鈕擷取目標記憶庫的配置：Endpoint 應與所選地區對應，API Key 應來自當前記憶庫。

配置訪問參數

將以下佔位內容替換為控制台中的實際值：

export AGENTLOOP_ENDPOINT="<從整合方式頁簽複製的 Endpoint>"
export AGENTLOOP_API_KEY="<該記憶庫的 API Key>"

寫入一段對話

下面的請求與控制台 HTTP 樣本使用相同的介面和參數結構，將一段對話關聯到業務使用者 user-001。

curl -X POST "$AGENTLOOP_ENDPOINT/v1/memories" \
  -H "Authorization: Token $AGENTLOOP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      {"role": "user", "content": "我住在杭州，喜歡喝無糖美式咖啡"},
      {"role": "assistant", "content": "好的，已記住你住在杭州、喜歡無糖美式。"}
    ],
    "user_id": "user-001",
    "infer": true
  }'

參數	說明
`messages`	本次寫入的對話訊息列表。每條訊息使用 `role` 表示角色，`content` 表示常值內容
`user_id`	對話關聯的業務使用者標識。後續檢索該使用者的記憶時使用同一標識
`infer`	樣本設為 `true`，請求從對話中提取記憶

檢查 HTTP 響應，確認請求成功；如果請求失敗，先根據響應檢查 Endpoint、API Key 和請求內容。記憶提取需要處理時間，寫入成功後繼續執行下一步檢索，確認相關長期記憶已經可用；不要僅憑對話中的“已記住”或寫入請求返回成功判斷提取結果。

選擇使用者標識與篩選條件

寫入請求中的 user_id 對應控制台長期記憶檢索頁面的使用者識別碼 欄位，本文統稱使用者標識。使用者標識將記憶關聯到業務使用者並限定檢索對象，由應用根據已登入使用者確定，寫入和檢索保持一致。user_id 是業務資料標識，應用仍需根據自身的使用者身份和許可權確定可查詢的範圍。接入應用時建議使用穩定的業務使用者標識：同一使用者跨會話複用相同的 user_id，不同使用者使用各自的標識。驗證上文樣本時，查詢使用者為 user-001。

查詢語句用於表達當前需要瞭解的資訊，例如“使用者的飲食偏好”或“使用者喜歡喝什麼咖啡”；ID 篩選項用於限定查詢對象，兩者應配合使用。控制台還提供 App ID、Agent ID 和 Run ID 篩選項，使用時應與實際寫入資料關聯的標識對應。跨會話查詢使用者偏好時，按使用者範圍檢索；只有需要查詢某次運行相關記憶時，再增加 Run ID 條件，避免把其他會話中的相關記憶排除在外。

步驟四：檢索長期記憶

控制台長期記憶檢索頁簽用於人工驗證檢索效果；應用通過代碼檢索記憶時，按整合方式頁簽提供的介面樣本調用。

進入記憶庫的長期記憶檢索頁簽。
輸入查詢語句，例如“這個使用者喜歡喝什麼咖啡？”。

按需填寫以下參數。

參數	說明
topK	指定期望返回的記憶數量上限，例如 `5`；實際返回數量以結果為準
使用者識別碼	按記憶關聯的業務使用者標識篩選，本樣本填寫 `user-001`
App ID	按記憶關聯的 App 標識篩選
Agent ID	按記憶關聯的 Agent 標識篩選
Run ID	按記憶關聯的運行標識篩選

單擊開始檢索，在檢索結果地區查看記憶內容。
檢索上述樣本時，可重點檢查是否返回與“無糖美式咖啡”有關的資訊。實際提取文字、語言和條目數可能不同，請判斷含義是否與輸入一致。頁面中的分數表示檢索匹配信賴度，可以協助判斷結果與當前問題的匹配程度；分數不代表記憶內容已經經過事實核實，也不代表應用必須將所有返回結果都交給 Agent。

步驟五：讓 Agent 使用記憶

應用接入記憶後，可以採用以下流程：

收到新問題：從應用的登入態或業務上下文確定使用者標識。
檢索記憶：按當前問題和該使用者標識查詢相關記憶。具體介面調用使用整合方式頁簽中的樣本。
組織模型輸入：將相關記憶作為背景資料，與當前問題、必要的近期對話一起加入請求。
產生回答：由 Agent 結合當前要求和歷史背景回答問題。
寫入本輪對話：將本輪實際發生的互動寫入記憶庫，供後續提取和檢索。
應用應保留當前問題中的明確要求。例如，歷史記憶為“喜歡咖啡”，但使用者本次要求“推薦不含咖啡的飲品”時，應將本次要求一併提供給 Agent。檢索結果為空白時，也可以由應用使用當前問題和已有會話上下文繼續處理。

完整樣本：為烹飪助手補充使用者偏好

本樣本複用步驟三的寫入請求結構、步驟四的檢索操作和步驟五的輸入組織方式，說明應用後續互動時如何使用記憶，不依賴特定 Agent 架構。

階段	操作	檢查重點
寫入偏好	使用步驟三的 HTTP 要求結構，將訊息內容替換為“我喜歡清淡、少辣的家常菜”，仍關聯 `user-001`	請求成功，使用者標識正確
驗證提取	在控制台查詢“使用者的飲食偏好”，使用者識別碼填寫 `user-001`	檢索結果含有與清淡、少辣有關的資訊
新會話提問	同一使用者開啟新會話詢問“今晚吃什嗎？”	應用繼續使用相同使用者標識檢索相關記憶
組織回答	將相關偏好與新問題一起提供給 Agent	應用確實將檢索結果加入請求，回答參考了相關偏好

可按以下結構組織輸入，其中的記憶內容應來自實際檢索結果：

當前問題：
今晚吃什嗎？
相關使用者記憶（背景資料）：
使用者偏好清淡、少辣的家常菜。
回答要求：
結合當前問題和相關偏好給出建議；使用者本次提出的明確要求優先。

這是上下文組織樣本，具體回答取決於當前問題、檢索結果和模型。驗證時先確認記憶被檢索到，再確認應用確實使用了這些記憶，不要僅憑一次回答推斷整個接入流程已經正確。

常見問題

剛建立記憶庫，為什麼還不能立即寫入？

建立資源需要準備時間。請按整合方式頁簽的提示預留準備時間並確認就緒，參見步驟一開頭的提示；資源準備完成後，仍需檢查寫入請求的響應並驗證長期記憶檢索。

寫入成功，但沒有檢索結果，應該檢查什嗎？

按以下順序檢查：

當前控制台中的記憶庫是否與寫入請求使用的 API Key 對應。
寫入時的 user_id 是否與檢索時的使用者識別碼 一致。
App ID、Agent ID、Run ID 等附加條件是否排除了目標資料。
查詢語句是否與輸入內容相關，可以先使用“使用者的咖啡偏好”等明確的問題驗證。
對話是否仍在處理，可以稍後重試檢索。
暫時沒有結果不能單獨說明資料已經丟失。排查時請結合寫入響應、查詢條件和後續檢索結果判斷，使用者標識與篩選條件的取值原則參見上文“選擇使用者標識與篩選條件”。

建立記憶庫後，Agent 會自動記住使用者嗎？

應用需要接入對話寫入和記憶檢索，並將相關結果加入模型請求。控制台建立記憶庫和 API Key 只是接入準備。

是否需要把全部歷史對話都放入每次模型請求？

應用可以根據當前任務，將相關長期記憶與必要的近期對話組合使用。長期記憶用於補充可複用的背景；本次問題中的具體指代、臨時要求等仍需要當前會話上下文。

可以直接使用其他記憶 SDK 的所有方法嗎？

接入時請以當前記憶庫的整合方式頁簽為準，使用其中提供的方法、參數和 Endpoint，並逐項驗證應用所需的操作。mem0 相容介面不等於任意 SDK 版本和所有擴充方法都已經完成適配。