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