在 n8n 工作流中接入 Mem0 長期記憶mem0/n8n-nodes-mem0 社區(qū)節(jié)點完整實戰(zhàn)指南【免費下載鏈接】embedchainThe Memory Layer for AI Agents - Drop-in memory infrastructure for AI agents and apps. Context that persists. Built for production.項目地址: https://gitcode.com/GitHub_Trending/em/embedchainmem0/n8n-nodes-mem0是一個 n8n 社區(qū)節(jié)點讓工作流具備跨會話的長期記憶從對話消息中提取并存儲記憶再按用戶/代理等實體維度語義檢索回憶。本篇基于倉庫內 README 與官方集成文檔 docs/integrations/n8n.mdx結合節(jié)點源碼 Mem0.node.ts、憑據實現(xiàn) Mem0Api.credentials.ts 和離線測試 Mem0.node.test.ts講清安裝、六個操作的參數(shù)細節(jié)、異步提取與輪詢機制、實體過濾的 OR 語義以及如何把它掛給 n8n 的 AI Agent 當工具用。讀完你可以獨立完成從安裝、建憑據到先查記憶、后寫記憶工作流的完整搭建并能定位超時、空結果等常見問題。節(jié)點定位與包結構Mem0 定位是The Memory Layer for AI Agents——給 AI 代理與應用提供即插即用的記憶基礎設施。該節(jié)點將托管版 Mem0 REST API 封裝為 n8n 原生節(jié)點只需一個Memory資源、六個操作即可覆蓋記憶的完整生命周期add / search / get / get many / update / delete。從 package.json 可以看到關鍵工程事實包名mem0/n8n-nodes-mem0當前版本 0.1.4運行環(huán)境要求node 20.15打包入口為index.js該文件有意留空n8n 實際通過 package.json 中的n8n鍵發(fā)現(xiàn)編譯產物dist/nodes/Mem0/Mem0.node.js與dist/credentials/Mem0Api.credentials.js構建腳本buildtsc編譯 gulp build:iconsgulpfile.js 負責把節(jié)點圖標 svg 與節(jié)點元數(shù)據Mem0.node.json復制到 dist因為 tsc 只產出 .js節(jié)點元數(shù)據 Mem0.node.json 將其歸類為AI / Memory類別即安裝后出現(xiàn)在 n8n 節(jié)點面板的 AI → Memory 分組下。安裝與憑據配置安裝前提按 docs/integrations/n8n.mdx 的說明安裝社區(qū)節(jié)點需要滿足三個前提有一個 Mem0 API Key在 app.mem0.ai 的 Settings → API Keys 頁面創(chuàng)建自托管self-hosted的 n8n 實例——從 npm 安裝社區(qū)節(jié)點是自托管功能n8n Cloud 只提供官方驗證過的節(jié)點實例 Owner 權限因為只有 Owner 能安裝社區(qū)節(jié)點。安裝路徑n8n 中進入Settings → Community Nodes選擇Install輸入mem0/n8n-nodes-mem0勾選風險確認框后安裝。安裝完成后在節(jié)點面板搜索Mem0應能看到帶 Memory 資源的節(jié)點。Mem0 API 憑據憑據類型定義在 Mem0Api.credentials.ts只有兩個字段字段說明API Key必填Mem0 API key以m0-開頭輸入框為密碼類型Base URL默認https://api.mem0.ai僅在自托管或非默認部署時覆蓋鑒權方式在authenticate中聲明為 generic 頭注入authenticate: IAuthenticateGeneric { type: generic, properties: { headers: { Authorization: Token {{$credentials.apiKey}}, }, }, };即每個請求都攜帶Authorization: Token key與 Mem0 官方 SDK 的鑒權方案一致。憑據的Test按鈕會發(fā)起一次廉價的GET /v1/ping/請求來驗證 key 是否有效無需消耗任何記憶配額。六個操作總覽README 中的操作表完整繼承了官方 API 端點映射節(jié)點在 Mem0.node.ts 中為每個操作定義了獨立的參數(shù)面板Operation說明EndpointAdd從消息中提取并存儲記憶POST /v3/memories/add/Search對已存記憶做語義檢索POST /v3/memories/search/Get Many列出已存記憶單頁或Return AllPOST /v3/memories/Get按 ID 取單條記憶GET /v1/memories/{id}/Update更新記憶文本或元數(shù)據PUT /v1/memories/{id}/Delete按 ID 刪除單條記憶DELETE /v1/memories/{id}/Add消息、實體與作用域Add 操作的必填/核心參數(shù)見源碼 L98-L225 的properties定義MessagesfixedCollection每條含Roleuser/assistant/system默認user與Content節(jié)點在調用前會校驗至少一條消息否則報At least one message is requiredUser ID把記憶關聯(lián)到該用戶Wait for Completion布爾默認true決定是否輪詢等待提取完成下一節(jié)詳述Additional Fields集合控制這次調用提取什么字段請求體鍵用途Agent IDagent_id按代理作用域App IDapp_id按應用/項目作用域Run IDrun_id按單次會話/運行作用域Metadata (JSON)metadata附加到每條提取記憶的任意 JSON非法 JSON 會報Invalid JSON in Metadata fieldInferinfer默認true關閉后原文存儲消息不跑 LLM 提取Custom Instructionscustom_instructions自由文本指導提取器本次保留/忽略什么Custom Categoriescustom_categoriesJSON 數(shù)組元素為{category: description}對象為本次調用替換項目級分類目錄Includesincludes僅提取匹配該描述的記憶Excludesexcludes跳過匹配該描述的記憶組裝請求體的邏輯在 execute 中L410-L461infer缺省取true各實體 ID 與includes/excludes非空才寫入 bodymetadata與custom_categories支持字符串或對象兩種形態(tài)字符串會先JSON.parse再傳入。關鍵的一點是節(jié)點在發(fā)請求前做了實體守衛(wèi)// API requires at least one entity id — fail clearly instead of a raw 4xx. if (!body.user_id !body.agent_id !body.run_id !body.app_id) { throw new NodeOperationError( this.getNode(), Add requires at least one of User ID, Agent ID, Run ID, or App ID, ...); }也就是說四個實體 ID 全空時節(jié)點會在本地先失敗并給出清晰錯誤而不是把請求打出去再收到一個裸的 4xx。測試用例 Mem0.node.test.ts 驗證了這一行為同時也驗證了僅填app_id不帶user_id是合法的實體作用域L78-L92。Add 的異步提取與輪詢機制這是該節(jié)點最有工程含量的部分。Add 默認走 LLM 異步提取API 返回event_id與status: PENDING|RUNNING節(jié)點隨后輪詢直到終態(tài)。兩個互相獨立的開關Wait for Completion默認開——決定是否輪詢。關掉則立即返回 event IDInfer默認開位于 Additional Fields——決定 API 是否執(zhí)行 LLM 提取。關掉則消息原文入庫。輪詢常量定義在文件頭部Mem0.node.ts L17-L18const POLL_INTERVAL_MS 1500; const MAX_POLL_ATTEMPTS 40; // ~60s ceiling即每 1.5 秒查詢一次GET /v1/event/{event_id}/最多 40 次、約 60 秒封頂。pollEvent函數(shù)L598-L626的處理邏輯status SUCCEEDED返回results數(shù)組與 Search/Get Many 的輸出形狀保持一致是干凈的數(shù)組而非外層信封status FAILED拋Mem0 memory event {id} failed: {reason}40 次輪詢后仍未終態(tài)拋Timed out waiting for memory event {id} to complete——注意超時不等于寫入失敗只是服務端還在處理若 Add 首次響應本身就是終態(tài)SUCCEEDED/FAILED則跳過輪詢直接解包results。測試中用一個永遠返回PENDING的 mock 驗證了超時路徑test/Mem0.node.test.ts L109-L127并且全局 mock 了n8n-workflow的sleep讓輪詢在測試中瞬時完成。另一個安全細節(jié)輪詢與 Get/Delete 的 URL 拼接都經過encodeURIComponent測試用../v1/entities這類惡意 ID 驗證了路徑穿越會被轉義為..%2Fv1%2FentitiesL173-L181、L183-L199。Search語義檢索Search 的請求體組裝L484-L499const body { query, // Query 參數(shù)必填 output_format: v1.1, // 固定使用 v1.1 輸出格式 top_k, // 來自 Limit 參數(shù)默認 50最小 1 }; body.filters buildEntityFilters({...}); // 實體過濾見下節(jié)Limit是數(shù)值參數(shù)minValue: 1默認 50映射為 API 的top_k。返回results數(shù)組每個元素即一條記憶 item。Get Many分頁與 Return AllGet Many 支持兩種模式L502-L530單頁模式returnAll: false默認使用Page默認 1最小 1與Page Size默認 50查一頁Return AllreturnAll: true節(jié)點自動翻頁——從第 1 頁開始直到某頁結果數(shù)小于pageSize或響應中沒有next指針為止且有一個page 10000的硬上限防失控。測試用例模擬了滿頁 → 短頁的兩輪翻頁L201-L210驗證合并后輸出[a,b,c]。Get / Update / Delete按 ID 操作三者共用Memory ID必填字段L342-L351。Update 額外接受Text新記憶文本與Metadata (JSON)且二者至少要提供一個否則報Provide text or metadata to updateL549-L553只傳了哪個就只更新哪個未傳的鍵不會進入請求體。Delete 無請求體直接DELETE /v1/memories/{id}/。實體過濾的 OR 語義重要設計Search 與 Get Many 都接受User ID / Agent ID / App ID / Run ID四個字段且至少填一個——API 會拒絕沒有實體作用域的查詢節(jié)點則在校驗階段就本地失敗。核心實現(xiàn)是buildEntityFiltersMem0.node.ts L577-L595return clauses.length 1 ? clauses[0] : { OR: clauses };只填一個實體 ID 時過濾條件是扁平的{ user_id: u1 }填多個時組合為OR并集例如{ OR: [{ user_id: u1 }, { agent_id: a1 }, { app_id: p1 }, { run_id: r1 }] }README 對此有一段值得細讀的解釋Mem0 對每個實體分別建索引所以user_id與agent_id之間的 AND 即使對同時寫了兩個 ID 的記憶也匹配不到任何東西。多 ID 用 OR 是有意為之取并集、擴大召回不是偷懶。如果你的目標是收窄而不是放寬正確做法是對每個實體 ID 各跑一次操作。測試用例把這一語義固化下來test L135-L163單 ID 發(fā)扁平 filter、四 ID 發(fā) OR 數(shù)組、空 ID 報錯。作為 AI Agent 的工具使用節(jié)點在描述中聲明了usableAsTool: trueMem0.node.ts L32-L33意味著 n8n 的 AI AgentTools Agent節(jié)點可以把它當工具直接掛載無需額外接線讓 Agent 自主記住與回憶。官方文檔給出的典型形態(tài)docs/integrations/n8n.mdxChat Trigger → AI Agent ──tool──? Mem0 (Search) ──tool──? Mem0 (Add)掛載一個配置為Search的 Mem0 節(jié)點和一個配置為Add的 Mem0 節(jié)點Agent 會在回答前先查記憶、在有效對話后回寫持久事實。注意兩個節(jié)點要使用相同的 User ID否則寫進去的記憶查不出來。還有一個時序要點記憶寫入默認是異步的。即使 Add 開著 Wait for Completion此時節(jié)點已等到終態(tài)才放行如果你的 Add 關了等待、或依賴其他寫入路徑在搜索剛寫入的內容前應留一點間隔——官方 Quickstart 中的兩節(jié)點示例Manual Trigger → Mem0 Add → Mem0 Search之所以能直接跑通正是因為 Wait for Completion 默認開啟Search 節(jié)點執(zhí)行時提取已完成。遙測與歸因README 明確聲明該節(jié)點不發(fā)送任何第三方遙測不接觸獨立的分析服務。它唯一的上報是 Mem0 自己的 API 請求且每個請求都附帶查詢參數(shù)source: N8NMem0.node.ts L387-L388讓 Mem0 能看到該集成路徑的聚合用量。測試用例 test L129-L133 斷言了每個請求的qs.source恒為N8N。測試體系與本地開發(fā)該節(jié)點帶有一套純離線單元測試test/Mem0.node.test.ts通過 stubIExecuteFunctions并 mockhelpers.httpRequestWithAuthentication不依賴任何網絡。覆蓋的關鍵路徑包括Add 無實體 ID 的本地攔截報錯app_id/includes/excludes正確透傳到請求體custom_categories非法 JSON 的報錯事件永不終態(tài)時的輪詢超時單 ID 扁平 filter 與多 ID OR filter 的形狀Memory ID / event ID 的 URL 轉義Return All 的分頁終止條件。本地開發(fā)命令package.json scriptspnpm run devtsc watch、pnpm run build清 dist 編譯 復制圖標、pnpm run lint、pnpm testjest配置見 jest.config.js。常見問題排查綜合 README 與 docs/integrations/n8n.mdx 的故障排查章節(jié)節(jié)點沒出現(xiàn)在面板里社區(qū)節(jié)點只能裝到自托管 n8n且只有實例 Owner 能安裝n8n Cloud 暫不可用。401 UnauthorizedAPI key 錯誤或被吊銷到 API Keys 面板重新生成并更新憑據。Provide at least one of User ID, Agent ID, App ID, or Run IDAdd / Search / Get Many 都必須有實體作用域至少填一個。剛 Add 完 Search 查不到提取是異步的。保持 Wait for Completion 開啟或在兩者之間加一個短暫的 Wait 節(jié)點。同時填兩個實體 ID 結果比預期多多 ID 是 OR 并集屬設計行為要收窄就每個 ID 單獨跑一次操作。Timed out waiting for memory event寫入請求已被接受、服務端仍在處理超時不代表失敗可以稍后重試 Search 確認。小結mem0/n8n-nodes-mem0用相當克制的 API 面一個 Memory 資源、六個操作覆蓋了長期記憶的完整生命周期同時把托管 API 中最容易踩坑的兩件事做了工程化兜底Add 的異步提取用有界輪詢 清晰終態(tài)錯誤收斂成同步體驗實體過濾用本地前置校驗 OR 語義避免無效請求和 AND 空結果。配合usableAsTool它既可以作為工作流中的普通數(shù)據節(jié)點也可以直接交給 n8n AI Agent 自主調用——這正是給工作流加上持久上下文的最低成本路徑。所有實現(xiàn)細節(jié)均可在 integrations/n8n-nodes-mem0 目錄下逐一查證。【免費下載鏈接】embedchainThe Memory Layer for AI Agents - Drop-in memory infrastructure for AI agents and apps. Context that persists. Built for production.項目地址: https://gitcode.com/GitHub_Trending/em/embedchain創(chuàng)作聲明：本文部分內容由AI輔助生成（AIGC），僅供參考