：從寫入管線、混合檢索到四維多租戶作用域)
深入 Mem0 Platform 記憶架構(gòu)從寫入管線、混合檢索到四維多租戶作用域【免費下載鏈接】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 是一個托管式 AI 記憶層它封裝了記憶抽取、去重、沖突消解與語義檢索的全部復雜性讓你的應(yīng)用只需調(diào)用search()與add()兩個接口。本文基于 Mem0 Platform 架構(gòu)參考文檔結(jié)合倉庫中 Python 客戶端源碼 與 類型定義完整拆解記憶的處理管線、檢索管線、生命周期、記憶對象結(jié)構(gòu)、多租戶作用域與性能特征讀完你可以準確理解 v3 版本的 ADD-only 模型、異步處理語義以及user_id/agent_id/app_id/run_id四維作用域的存儲與查詢規(guī)則。核心概念應(yīng)用與記憶層之間的三步循環(huán)Mem0 Platform 的定位是受管記憶層managed memory layer位于你的 AI 應(yīng)用與用戶之間。所有集成本質(zhì)上都遵循同一個三步循環(huán)User Input → Retrieve relevant memories → Enrich LLM prompt → Generate response → Store new memories即檢索相關(guān)記憶 → 用記憶增強 LLM 提示詞 → 生成回復 → 把新事實存回記憶庫。正如 SKILL.md 中總結(jié)的 retrieve → generate → store 模式抽取、去重、沖突消解和語義檢索的復雜性全部由 Mem0 承擔。底層存儲由兩部分構(gòu)成向量存儲Vector store存放嵌入向量支撐語義相似度檢索實體存儲Entity store在add()時自動抽取實體并建立實體鏈接entity linking為關(guān)系感知的檢索提供圖譜側(cè)信號。從源碼結(jié)構(gòu)看這一存儲分工對應(yīng) v3 的兩處演進實體鏈接取代了 v2 的圖記憶graph memory且無需任何配置、在add()期間自動完成——這也是 v2 配置中enable_graph與graph_store參數(shù)被移除的原因詳見 Platform v2 → v3 遷移指南。記憶處理管線client.add()內(nèi)部發(fā)生了什么當調(diào)用client.add()時消息會依次經(jīng)過三個階段Messages In │ ▼ ┌─────────────────────┐ │ 1. EXTRACTION │ 單次 LLM 調(diào)用抽取所有新的獨立事實 │ (inferTrue) │ 若 inferFalse則原文照存 └─────────┬───────────┘ │ ▼ ┌─────────────────────┐ │ 2. DEDUPLICATION │ 基于哈希的去重MD5 攔截完全重復 │ │ 無 UPDATE/DELETE —— v3 是 ADD-only └─────────┬───────────┘ │ ▼ ┌─────────────────────┐ │ 3. STORAGE │ 批量嵌入 → 向量存儲 │ │ 實體抽取 → 實體存儲 └─────────┬───────────┘ │ ▼ Memory Object階段一抽取Extraction抽取有infer參數(shù)控制兩種模式推斷模式inferTrue默認LLM 從對話中抽取結(jié)構(gòu)化事實抽取階段附帶沖突消解重復內(nèi)容被去重矛盾內(nèi)容被消解適用于自然對話 → 記憶的典型場景。原文模式inferFalse文本原樣存儲不經(jīng)過任何 LLM 處理跳過沖突消解——同一事實可能被存兩次只存儲user角色的消息assistant消息被忽略適用于批量導入、預結(jié)構(gòu)化數(shù)據(jù)、數(shù)據(jù)遷移。警告不要對同一份數(shù)據(jù)混用inferTrue與inferFalse否則同一事實會被存兩次。這一點在 SDK 中有對應(yīng)的類型定義AddMemoryOptions 中infer是一個可選布爾字段此外還提供custom_categories自定義分類標簽、custom_instructions定制事實抽取指令、timestamp與expiration_date時間屬性、structured_data_schema結(jié)構(gòu)化數(shù)據(jù)抽取模式等可選參數(shù)用于在同一管線上進一步定制抽取行為。階段二去重Deduplicationv3 的去重采用基于哈希MD5的精確重復攔截且不產(chǎn)生 UPDATE/DELETE 操作——v3 抽取是單遍的 ADD-only 模型。這意味著記憶隨時間累積accumulate而非被持續(xù)合并consolidate同一實體的認知演化通過新增記憶體現(xiàn)由檢索階段的多信號打分決定哪條記憶更相關(guān)。階段三存儲Storage通過去重后的記憶會被批量嵌入batch embed寫入向量存儲同時完成實體抽取寫入實體存儲最終落庫為一條 Memory Object結(jié)構(gòu)見下文。v3 的異步處理模型v3 默認異步處理add()API 立即返回{status: PENDING, event_id: evt-...}通過GET /v1/event/{event_id}/輪詢處理狀態(tài)也可以配置 Webhook 在處理完成時接收實時通知。從源碼看MemoryClient.add() 對POST /v3/memories/add/發(fā)起請求L217并把響應(yīng)原樣返回——PENDINGevent_id正是這個響應(yīng)的內(nèi)容。這一模型的實際影響是剛調(diào)用完add()立即search()可能查不到新記憶SKILL.md 建議等待 2~3 秒這是異步管線的直接推論。檢索管線client.search()的三信號融合當調(diào)用client.search()時查詢經(jīng)過三個階段Query In │ ▼ ┌─────────────────────┐ │ 1. PREPROCESSING │ 關(guān)鍵詞詞形還原lemmatize、實體抽取 └─────────┬───────────┘ │ ▼ ┌─────────────────────┐ │ 2. PARALLEL SCORING │ 語義檢索向量相似度 │ │ BM25 關(guān)鍵詞檢索詞項匹配 │ │ 實體匹配實體圖加權(quán) └─────────┬───────────┘ │ ▼ ┌─────────────────────┐ │ 3. SCORE FUSION │ 多路信號融合為單一分數(shù) │ │ 可選rerankTrue 深度重排 └─────────┬───────────┘ │ ▼ Results (combined score per memory)三路并行打分分別覆蓋三種匹配形態(tài)向量相似度捕捉語義等價不吃肉 ≈ 素食主義者BM25 詞項匹配捕捉精確關(guān)鍵詞型號、代號等實體匹配則利用實體存儲中自動建立的實體鏈接做關(guān)系加權(quán)。三路信號在融合階段合成單一score開啟rerankTrue后還會經(jīng)過一輪深度重排代價是額外延遲見性能章節(jié)。v3 檢索默認值參數(shù)默認值備注top_k20v2 中為 100threshold0.1v2 中為 NonererankFalsev2 中為 True這些默認值對應(yīng) SDK 中的可選參數(shù)定義SearchMemoryOptions 暴露了top_k、threshold、rerank、filters、categories、keyword_search純關(guān)鍵詞檢索、show_expired、latest_only、reference_date相對時間查詢的參考日期等字段全部為可選——不傳即使用上表默認值。隱式空值作用域Implicit null scoping這是 v3 檢索中最容易踩坑的語義當 filters 只帶user_id時Mem0 只返回agent_id、app_id、run_id全部為空null的記憶。這一設(shè)計從默認行為上防止了跨作用域泄漏cross-scope leakage。若需要包含帶非空作用域字段的記憶必須改用顯式 OR 過濾# 獲取 alice 的所有記憶無論 agent/app/run 是什么 filters{OR: [{user_id: alice}]}這一點在 SDK 層有硬約束佐證。mem0/client/main.py 中定義了ENTITY_PARAMS frozenset({user_id, agent_id, app_id, run_id})search() 與 get_all() 都會攔截并拒絕頂層傳入這四個實體參數(shù)L267-L273、L316-L322 拋出ValueError強制要求把它們放進filters字典——v3 API 不接受頂層實體參數(shù)。這與 types.py 模塊文檔的說明一致Identity fields (user_id, agent_id, app_id, run_id) must be passed inside thefiltersdict。也就是說作用域語義不僅在服務(wù)端生效SDK 在客戶端就先行校驗確保作用域信息以統(tǒng)一的 filters 結(jié)構(gòu)下發(fā)。記憶生命周期v3v3 使用 ADD-only 抽取記憶隨時間累積而不被合并。完整的生命周期操作在 MemoryClient 中都有對應(yīng)實現(xiàn)創(chuàng)建client.add(messages, user_idalice)單遍抽取 → 去重 → 存儲返回{event_id: ..., status: PENDING}。更新client.update(memory_id, text...) # 替換文本 client.batch_update([...]) # 批量每批最多 1000 條從源碼看batch_update()走PUT /v1/batch/L571-L595batch_delete()走DELETE /v1/batch/L598-L621二者共用 batch 端點、以 HTTP 方法區(qū)分。刪除client.delete(memory_id) # 單條 client.batch_delete([...]) # 批量 client.delete_all(filters{user_id: alice}) # 按條件批量清除delete_all()對應(yīng)DELETE /v1/memories/L414-L442而針對整個實體的清理刪除某 user/agent/app/run 下的一切由 delete_users() 通過DELETE /v2/entities/{type}/{name}/完成reset()則調(diào)用它實現(xiàn)全量清空。端點級細節(jié)可繼續(xù)查閱 docs/api-reference/memory/ 下的delete-memory.mdx、batch-update.mdx、batch-delete.mdx等頁面。記憶對象Memory Object結(jié)構(gòu)每條記憶落庫后的完整結(jié)構(gòu)如下{ id: uuid-string, memory: Extracted memory text, user_id: user-identifier, agent_id: null, app_id: null, run_id: null, metadata: { source: chat, priority: high }, categories: [health, preferences], created_at: 2025-03-12T12:34:56Z, updated_at: 2025-03-12T12:34:56Z, structured_attributes: { day: 12, month: 3, year: 2025, hour: 12, minute: 34, day_of_week: wednesday, is_weekend: false, quarter: 1, week_of_year: 11 }, score: 0.85 }字段類型說明idUUID唯一標識符用于 update/deletememorystring抽取或存儲的文本內(nèi)容user_idstring用戶作用域主實體agent_idstringAgent 作用域app_idstring應(yīng)用作用域run_idstring會話/運行作用域metadataobject自定義鍵值對可用于過濾categoriesarray自動分配或自定義的分類標簽created_atdatetime創(chuàng)建時間戳updated_atdatetime最后修改時間戳structured_attributesobject時間維度拆解支持基于時間的查詢scorefloat語義相似度僅檢索結(jié)果中出現(xiàn)0–1值得注意的兩個設(shè)計點structured_attributes是對add()時間參數(shù)的落庫體現(xiàn)。在 AddMemoryOptions 中傳入timestampUnix 時間戳或expiration_dateYYYY-MM-DD后服務(wù)端會把時間戳拆解為天/月/年、時/分、星期、是否周末、季度、年度周次等字段——這是時間感知檢索如reference_date相對時間查詢的底層依據(jù)。categories支持自動與自定義兩條來源。add()時可通過custom_categories傳入標簽 schema 覆蓋自動分類檢索時又可用SearchMemoryOptions.categories按標簽過濾。作用域與多租戶Scoping Multi-TenancyMem0 沿四個維度隔離記憶防止數(shù)據(jù)混用維度字段用途示例用戶user_id持久化的人物畫像或賬戶customer_6412Agentagent_id獨立的智能體或工具meal_planner應(yīng)用app_id產(chǎn)品表面或部署ios_retail_app會話run_id短生命周期的流程或線程ticket-9241存儲模型每個實體組合獨立成記錄每個實體組合entity combination都會生成獨立的記錄user_idalice的記憶與user_idaliceagent_idbot的記憶是兩條不同的存儲記錄。這與 SDK 中ENTITY_PARAMS常量main.py L40所約束的四個身份字段一一對應(yīng)。關(guān)鍵陷阱跨實體查詢# 這樣查不到任何結(jié)果 —— user 記憶與 agent 記憶是分開存的 filters{AND: [{user_id: alice}, {agent_id: bot}]} # 用 OR 查詢多個作用域 filters{OR: [{user_id: alice}, {agent_id: bot}]} # 用通配符 * 匹配任意非空值 filters{AND: [{user_id: *}]} # 所有用戶不含 null第一條查詢返回空不是 bug 而是設(shè)計AND 語義要求同一條記憶同時滿足 user 和 agent 兩個條件而兩者各自獨立存儲、從不落在同一條記錄上。SKILL.md 的常見邊界情況一節(jié)把這條列為高頻誤區(qū)。推薦的作用域模式# 用戶級持久化偏好 client.add(messages, user_idalice) # 會話級臨時上下文 client.add(messages, user_idalice, run_idsession_123) # 用完即清client.delete_all(run_idsession_123) # Agent 級agent 專屬知識 client.add(messages, agent_idsupport_bot, app_idhelpdesk) # 多租戶完全隔離 client.add(messages, user_idalice, agent_idbot, app_idacme_corp, run_idticket_42)記憶分層從單輪到終身Mem0 支持三層記憶按生命周期從短到長排列對話記憶Conversation memory單個回合內(nèi)的進行中消息包含工具調(diào)用、思維鏈推理生命周期單次響應(yīng)——回合結(jié)束即消失管理者你的應(yīng)用而不是 Mem0。會話記憶Session memory面向當前任務(wù)或頻道的短期事實多步流程入職引導、調(diào)試、客服工單生命周期數(shù)分鐘到數(shù)小時管理者Mem0通過run_id參數(shù)清理方式client.delete_all(run_idsession_id)。用戶記憶User memory與人或賬戶綁定的長期知識個人偏好、賬戶狀態(tài)、合規(guī)信息生命周期數(shù)周到永久管理者Mem0通過user_id參數(shù)跨所有會話與交互持久存在。分層在實際代碼中的組合方式def chat(user_input: str, user_id: str, session_id: str) - str: # 1. 檢索用戶記憶長期偏好 user_mems mem0.search(user_input, filters{user_id: user_id}) # 2. 檢索會話記憶當前任務(wù)上下文 session_mems mem0.search(user_input, filters{ AND: [{user_id: user_id}, {run_id: session_id}] }) # 3. 兩層記憶合并為 LLM 上下文 context format_memories(user_mems) format_memories(session_mems) # 4. 生成響應(yīng) response llm.generate(contextcontext, inputuser_input) # 5. 分別寫入會話作用域臨時與用戶作用域持久 messages [{role: user, content: user_input}, {role: assistant, content: response}] mem0.add(messages, user_iduser_id, run_idsession_id) return response注意第 2 步用了AND過濾——這里之所以安全是因為兩個條件user run指向的是同一批帶run_id的記憶記錄而非跨記錄組合這與上文跨實體查詢陷阱并不矛盾。性能特征延遲文檔給出的典型參考值操作典型延遲混合檢索v3 默認~100–150ms rerank額外 150–200msAdd異步響應(yīng) 50msadd()之所以能壓到 50ms 以內(nèi)響應(yīng)正因為 v3 把 LLM 抽取挪到了異步后臺API 只做受理并返回event_id。處理模型異步默認立即返回后臺處理批量操作batch_update/batch_delete每批最多 1000 條記憶Webhooks異步處理完成時實時通知。面向性能的作用域策略面向用戶的所有查詢都帶上user_id最常見、最快追加run_id做會話隔離收窄檢索空間避免在大數(shù)據(jù)集上使用*通配過濾會掃描所有非空記錄只需要少量記憶時用top_k限制返回數(shù)量。與其他方案的取舍對比方案優(yōu)點缺點裸向量數(shù)據(jù)庫快、完全可控無抽取、無去重、無沖突消解內(nèi)存中的聊天歷史零延遲重啟即丟失、無跨會話能力、無界增長基于文檔的 RAG適合靜態(tài)知識無個性化、記憶不可更新Mem0 Platform托管式抽取 去重 實體鏈接 作用域外部依賴、異步處理延遲Mem0 Platform 的差異化在于把向量檢索語義召回、LLM 抽取、沖突消解去重與結(jié)構(gòu)化多租戶作用域組合進同一個托管 API以換取應(yīng)用側(cè)零基礎(chǔ)設(shè)施成本。小結(jié)與延伸閱讀回顧本文的核心結(jié)論寫入側(cè)是單遍抽取 哈希去重 雙存儲落庫的 ADD-only 管線add()默認異步、以event_id受理add() 實現(xiàn)檢索側(cè)是語義 BM25 實體三信號并行打分再融合默認top_k20 / threshold0.1 / rerankFalsesearch() 實現(xiàn)作用域側(cè)由user_id / agent_id / app_id / run_id四維獨立存儲隱式空值作用域防止跨域泄漏SDK 用ENTITY_PARAMS強制 filters 傳參main.py L40分層記憶對話/會話/用戶通過run_id與user_id的組合落地配合delete_all完成會話級清理。想繼續(xù)深入可以沿以下倉庫內(nèi)資料閱讀Mem0 技能入口 SKILL.mdv3 API 變更總覽、常見邊界情況與技能參考索引SDK 指南 與 API 參考雙語言全部方法與端點細節(jié)docs/api-reference/memory/add-memories.mdx、search-memories.mdx、update-memory.mdx等端點級文檔Platform v2 → v3 遷移指南端點、參數(shù)移除org_id/project_id/enable_graph與默認值變化的完整對照客戶端類型定義AddMemoryOptions/SearchMemoryOptions等 Pydantic 模型是各參數(shù)取值與默認行為的第一手參照?！久赓M下載鏈接】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)作聲明：本文部分內(nèi)容由AI輔助生成（AIGC），僅供參考 深入 Mem0 Platform 記憶架構(gòu)：從寫入管線、混合檢索到四維多租戶作用域
深入 Mem0 Platform 記憶架構(gòu)從寫入管線、混合檢索到四維多租戶作用域【免費下載鏈接】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 是一個托管式 AI 記憶層它封裝了記憶抽取、去重、沖突消解與語義檢索的全部復雜性讓你的應(yīng)用只需調(diào)用search()與add()兩個接口。本文基于 Mem0 Platform 架構(gòu)參考文檔結(jié)合倉庫中 Python 客戶端源碼 與 類型定義完整拆解記憶的處理管線、檢索管線、生命周期、記憶對象結(jié)構(gòu)、多租戶作用域與性能特征讀完你可以準確理解 v3 版本的 ADD-only 模型、異步處理語義以及user_id/agent_id/app_id/run_id四維作用域的存儲與查詢規(guī)則。核心概念應(yīng)用與記憶層之間的三步循環(huán)Mem0 Platform 的定位是受管記憶層managed memory layer位于你的 AI 應(yīng)用與用戶之間。所有集成本質(zhì)上都遵循同一個三步循環(huán)User Input → Retrieve relevant memories → Enrich LLM prompt → Generate response → Store new memories即檢索相關(guān)記憶 → 用記憶增強 LLM 提示詞 → 生成回復 → 把新事實存回記憶庫。正如 SKILL.md 中總結(jié)的 retrieve → generate → store 模式抽取、去重、沖突消解和語義檢索的復雜性全部由 Mem0 承擔。底層存儲由兩部分構(gòu)成向量存儲Vector store存放嵌入向量支撐語義相似度檢索實體存儲Entity store在add()時自動抽取實體并建立實體鏈接entity linking為關(guān)系感知的檢索提供圖譜側(cè)信號。從源碼結(jié)構(gòu)看這一存儲分工對應(yīng) v3 的兩處演進實體鏈接取代了 v2 的圖記憶graph memory且無需任何配置、在add()期間自動完成——這也是 v2 配置中enable_graph與graph_store參數(shù)被移除的原因詳見 Platform v2 → v3 遷移指南。記憶處理管線client.add()內(nèi)部發(fā)生了什么當調(diào)用client.add()時消息會依次經(jīng)過三個階段Messages In │ ▼ ┌─────────────────────┐ │ 1. EXTRACTION │ 單次 LLM 調(diào)用抽取所有新的獨立事實 │ (inferTrue) │ 若 inferFalse則原文照存 └─────────┬───────────┘ │ ▼ ┌─────────────────────┐ │ 2. DEDUPLICATION │ 基于哈希的去重MD5 攔截完全重復 │ │ 無 UPDATE/DELETE —— v3 是 ADD-only └─────────┬───────────┘ │ ▼ ┌─────────────────────┐ │ 3. STORAGE │ 批量嵌入 → 向量存儲 │ │ 實體抽取 → 實體存儲 └─────────┬───────────┘ │ ▼ Memory Object階段一抽取Extraction抽取有infer參數(shù)控制兩種模式推斷模式inferTrue默認LLM 從對話中抽取結(jié)構(gòu)化事實抽取階段附帶沖突消解重復內(nèi)容被去重矛盾內(nèi)容被消解適用于自然對話 → 記憶的典型場景。原文模式inferFalse文本原樣存儲不經(jīng)過任何 LLM 處理跳過沖突消解——同一事實可能被存兩次只存儲user角色的消息assistant消息被忽略適用于批量導入、預結(jié)構(gòu)化數(shù)據(jù)、數(shù)據(jù)遷移。警告不要對同一份數(shù)據(jù)混用inferTrue與inferFalse否則同一事實會被存兩次。這一點在 SDK 中有對應(yīng)的類型定義AddMemoryOptions 中infer是一個可選布爾字段此外還提供custom_categories自定義分類標簽、custom_instructions定制事實抽取指令、timestamp與expiration_date時間屬性、structured_data_schema結(jié)構(gòu)化數(shù)據(jù)抽取模式等可選參數(shù)用于在同一管線上進一步定制抽取行為。階段二去重Deduplicationv3 的去重采用基于哈希MD5的精確重復攔截且不產(chǎn)生 UPDATE/DELETE 操作——v3 抽取是單遍的 ADD-only 模型。這意味著記憶隨時間累積accumulate而非被持續(xù)合并consolidate同一實體的認知演化通過新增記憶體現(xiàn)由檢索階段的多信號打分決定哪條記憶更相關(guān)。階段三存儲Storage通過去重后的記憶會被批量嵌入batch embed寫入向量存儲同時完成實體抽取寫入實體存儲最終落庫為一條 Memory Object結(jié)構(gòu)見下文。v3 的異步處理模型v3 默認異步處理add()API 立即返回{status: PENDING, event_id: evt-...}通過GET /v1/event/{event_id}/輪詢處理狀態(tài)也可以配置 Webhook 在處理完成時接收實時通知。從源碼看MemoryClient.add() 對POST /v3/memories/add/發(fā)起請求L217并把響應(yīng)原樣返回——PENDINGevent_id正是這個響應(yīng)的內(nèi)容。這一模型的實際影響是剛調(diào)用完add()立即search()可能查不到新記憶SKILL.md 建議等待 2~3 秒這是異步管線的直接推論。檢索管線client.search()的三信號融合當調(diào)用client.search()時查詢經(jīng)過三個階段Query In │ ▼ ┌─────────────────────┐ │ 1. PREPROCESSING │ 關(guān)鍵詞詞形還原lemmatize、實體抽取 └─────────┬───────────┘ │ ▼ ┌─────────────────────┐ │ 2. PARALLEL SCORING │ 語義檢索向量相似度 │ │ BM25 關(guān)鍵詞檢索詞項匹配 │ │ 實體匹配實體圖加權(quán) └─────────┬───────────┘ │ ▼ ┌─────────────────────┐ │ 3. SCORE FUSION │ 多路信號融合為單一分數(shù) │ │ 可選rerankTrue 深度重排 └─────────┬───────────┘ │ ▼ Results (combined score per memory)三路并行打分分別覆蓋三種匹配形態(tài)向量相似度捕捉語義等價不吃肉 ≈ 素食主義者BM25 詞項匹配捕捉精確關(guān)鍵詞型號、代號等實體匹配則利用實體存儲中自動建立的實體鏈接做關(guān)系加權(quán)。三路信號在融合階段合成單一score開啟rerankTrue后還會經(jīng)過一輪深度重排代價是額外延遲見性能章節(jié)。v3 檢索默認值參數(shù)默認值備注top_k20v2 中為 100threshold0.1v2 中為 NonererankFalsev2 中為 True這些默認值對應(yīng) SDK 中的可選參數(shù)定義SearchMemoryOptions 暴露了top_k、threshold、rerank、filters、categories、keyword_search純關(guān)鍵詞檢索、show_expired、latest_only、reference_date相對時間查詢的參考日期等字段全部為可選——不傳即使用上表默認值。隱式空值作用域Implicit null scoping這是 v3 檢索中最容易踩坑的語義當 filters 只帶user_id時Mem0 只返回agent_id、app_id、run_id全部為空null的記憶。這一設(shè)計從默認行為上防止了跨作用域泄漏cross-scope leakage。若需要包含帶非空作用域字段的記憶必須改用顯式 OR 過濾# 獲取 alice 的所有記憶無論 agent/app/run 是什么 filters{OR: [{user_id: alice}]}這一點在 SDK 層有硬約束佐證。mem0/client/main.py 中定義了ENTITY_PARAMS frozenset({user_id, agent_id, app_id, run_id})search() 與 get_all() 都會攔截并拒絕頂層傳入這四個實體參數(shù)L267-L273、L316-L322 拋出ValueError強制要求把它們放進filters字典——v3 API 不接受頂層實體參數(shù)。這與 types.py 模塊文檔的說明一致Identity fields (user_id, agent_id, app_id, run_id) must be passed inside thefiltersdict。也就是說作用域語義不僅在服務(wù)端生效SDK 在客戶端就先行校驗確保作用域信息以統(tǒng)一的 filters 結(jié)構(gòu)下發(fā)。記憶生命周期v3v3 使用 ADD-only 抽取記憶隨時間累積而不被合并。完整的生命周期操作在 MemoryClient 中都有對應(yīng)實現(xiàn)創(chuàng)建client.add(messages, user_idalice)單遍抽取 → 去重 → 存儲返回{event_id: ..., status: PENDING}。更新client.update(memory_id, text...) # 替換文本 client.batch_update([...]) # 批量每批最多 1000 條從源碼看batch_update()走PUT /v1/batch/L571-L595batch_delete()走DELETE /v1/batch/L598-L621二者共用 batch 端點、以 HTTP 方法區(qū)分。刪除client.delete(memory_id) # 單條 client.batch_delete([...]) # 批量 client.delete_all(filters{user_id: alice}) # 按條件批量清除delete_all()對應(yīng)DELETE /v1/memories/L414-L442而針對整個實體的清理刪除某 user/agent/app/run 下的一切由 delete_users() 通過DELETE /v2/entities/{type}/{name}/完成reset()則調(diào)用它實現(xiàn)全量清空。端點級細節(jié)可繼續(xù)查閱 docs/api-reference/memory/ 下的delete-memory.mdx、batch-update.mdx、batch-delete.mdx等頁面。記憶對象Memory Object結(jié)構(gòu)每條記憶落庫后的完整結(jié)構(gòu)如下{ id: uuid-string, memory: Extracted memory text, user_id: user-identifier, agent_id: null, app_id: null, run_id: null, metadata: { source: chat, priority: high }, categories: [health, preferences], created_at: 2025-03-12T12:34:56Z, updated_at: 2025-03-12T12:34:56Z, structured_attributes: { day: 12, month: 3, year: 2025, hour: 12, minute: 34, day_of_week: wednesday, is_weekend: false, quarter: 1, week_of_year: 11 }, score: 0.85 }字段類型說明idUUID唯一標識符用于 update/deletememorystring抽取或存儲的文本內(nèi)容user_idstring用戶作用域主實體agent_idstringAgent 作用域app_idstring應(yīng)用作用域run_idstring會話/運行作用域metadataobject自定義鍵值對可用于過濾categoriesarray自動分配或自定義的分類標簽created_atdatetime創(chuàng)建時間戳updated_atdatetime最后修改時間戳structured_attributesobject時間維度拆解支持基于時間的查詢scorefloat語義相似度僅檢索結(jié)果中出現(xiàn)0–1值得注意的兩個設(shè)計點structured_attributes是對add()時間參數(shù)的落庫體現(xiàn)。在 AddMemoryOptions 中傳入timestampUnix 時間戳或expiration_dateYYYY-MM-DD后服務(wù)端會把時間戳拆解為天/月/年、時/分、星期、是否周末、季度、年度周次等字段——這是時間感知檢索如reference_date相對時間查詢的底層依據(jù)。categories支持自動與自定義兩條來源。add()時可通過custom_categories傳入標簽 schema 覆蓋自動分類檢索時又可用SearchMemoryOptions.categories按標簽過濾。作用域與多租戶Scoping Multi-TenancyMem0 沿四個維度隔離記憶防止數(shù)據(jù)混用維度字段用途示例用戶user_id持久化的人物畫像或賬戶customer_6412Agentagent_id獨立的智能體或工具meal_planner應(yīng)用app_id產(chǎn)品表面或部署ios_retail_app會話run_id短生命周期的流程或線程ticket-9241存儲模型每個實體組合獨立成記錄每個實體組合entity combination都會生成獨立的記錄user_idalice的記憶與user_idaliceagent_idbot的記憶是兩條不同的存儲記錄。這與 SDK 中ENTITY_PARAMS常量main.py L40所約束的四個身份字段一一對應(yīng)。關(guān)鍵陷阱跨實體查詢# 這樣查不到任何結(jié)果 —— user 記憶與 agent 記憶是分開存的 filters{AND: [{user_id: alice}, {agent_id: bot}]} # 用 OR 查詢多個作用域 filters{OR: [{user_id: alice}, {agent_id: bot}]} # 用通配符 * 匹配任意非空值 filters{AND: [{user_id: *}]} # 所有用戶不含 null第一條查詢返回空不是 bug 而是設(shè)計AND 語義要求同一條記憶同時滿足 user 和 agent 兩個條件而兩者各自獨立存儲、從不落在同一條記錄上。SKILL.md 的常見邊界情況一節(jié)把這條列為高頻誤區(qū)。推薦的作用域模式# 用戶級持久化偏好 client.add(messages, user_idalice) # 會話級臨時上下文 client.add(messages, user_idalice, run_idsession_123) # 用完即清client.delete_all(run_idsession_123) # Agent 級agent 專屬知識 client.add(messages, agent_idsupport_bot, app_idhelpdesk) # 多租戶完全隔離 client.add(messages, user_idalice, agent_idbot, app_idacme_corp, run_idticket_42)記憶分層從單輪到終身Mem0 支持三層記憶按生命周期從短到長排列對話記憶Conversation memory單個回合內(nèi)的進行中消息包含工具調(diào)用、思維鏈推理生命周期單次響應(yīng)——回合結(jié)束即消失管理者你的應(yīng)用而不是 Mem0。會話記憶Session memory面向當前任務(wù)或頻道的短期事實多步流程入職引導、調(diào)試、客服工單生命周期數(shù)分鐘到數(shù)小時管理者Mem0通過run_id參數(shù)清理方式client.delete_all(run_idsession_id)。用戶記憶User memory與人或賬戶綁定的長期知識個人偏好、賬戶狀態(tài)、合規(guī)信息生命周期數(shù)周到永久管理者Mem0通過user_id參數(shù)跨所有會話與交互持久存在。分層在實際代碼中的組合方式def chat(user_input: str, user_id: str, session_id: str) - str: # 1. 檢索用戶記憶長期偏好 user_mems mem0.search(user_input, filters{user_id: user_id}) # 2. 檢索會話記憶當前任務(wù)上下文 session_mems mem0.search(user_input, filters{ AND: [{user_id: user_id}, {run_id: session_id}] }) # 3. 兩層記憶合并為 LLM 上下文 context format_memories(user_mems) format_memories(session_mems) # 4. 生成響應(yīng) response llm.generate(contextcontext, inputuser_input) # 5. 分別寫入會話作用域臨時與用戶作用域持久 messages [{role: user, content: user_input}, {role: assistant, content: response}] mem0.add(messages, user_iduser_id, run_idsession_id) return response注意第 2 步用了AND過濾——這里之所以安全是因為兩個條件user run指向的是同一批帶run_id的記憶記錄而非跨記錄組合這與上文跨實體查詢陷阱并不矛盾。性能特征延遲文檔給出的典型參考值操作典型延遲混合檢索v3 默認~100–150ms rerank額外 150–200msAdd異步響應(yīng) 50msadd()之所以能壓到 50ms 以內(nèi)響應(yīng)正因為 v3 把 LLM 抽取挪到了異步后臺API 只做受理并返回event_id。處理模型異步默認立即返回后臺處理批量操作batch_update/batch_delete每批最多 1000 條記憶Webhooks異步處理完成時實時通知。面向性能的作用域策略面向用戶的所有查詢都帶上user_id最常見、最快追加run_id做會話隔離收窄檢索空間避免在大數(shù)據(jù)集上使用*通配過濾會掃描所有非空記錄只需要少量記憶時用top_k限制返回數(shù)量。與其他方案的取舍對比方案優(yōu)點缺點裸向量數(shù)據(jù)庫快、完全可控無抽取、無去重、無沖突消解內(nèi)存中的聊天歷史零延遲重啟即丟失、無跨會話能力、無界增長基于文檔的 RAG適合靜態(tài)知識無個性化、記憶不可更新Mem0 Platform托管式抽取 去重 實體鏈接 作用域外部依賴、異步處理延遲Mem0 Platform 的差異化在于把向量檢索語義召回、LLM 抽取、沖突消解去重與結(jié)構(gòu)化多租戶作用域組合進同一個托管 API以換取應(yīng)用側(cè)零基礎(chǔ)設(shè)施成本。小結(jié)與延伸閱讀回顧本文的核心結(jié)論寫入側(cè)是單遍抽取 哈希去重 雙存儲落庫的 ADD-only 管線add()默認異步、以event_id受理add() 實現(xiàn)檢索側(cè)是語義 BM25 實體三信號并行打分再融合默認top_k20 / threshold0.1 / rerankFalsesearch() 實現(xiàn)作用域側(cè)由user_id / agent_id / app_id / run_id四維獨立存儲隱式空值作用域防止跨域泄漏SDK 用ENTITY_PARAMS強制 filters 傳參main.py L40分層記憶對話/會話/用戶通過run_id與user_id的組合落地配合delete_all完成會話級清理。想繼續(xù)深入可以沿以下倉庫內(nèi)資料閱讀Mem0 技能入口 SKILL.mdv3 API 變更總覽、常見邊界情況與技能參考索引SDK 指南 與 API 參考雙語言全部方法與端點細節(jié)docs/api-reference/memory/add-memories.mdx、search-memories.mdx、update-memory.mdx等端點級文檔Platform v2 → v3 遷移指南端點、參數(shù)移除org_id/project_id/enable_graph與默認值變化的完整對照客戶端類型定義AddMemoryOptions/SearchMemoryOptions等 Pydantic 模型是各參數(shù)取值與默認行為的第一手參照?！久赓M下載鏈接】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)作聲明：本文部分內(nèi)容由AI輔助生成（AIGC），僅供參考