Mem0 SDK 指南Python 與 TypeScript 的 MemoryClient 全方法實(shí)戰(zhà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/embedchainMem0 為 AI Agent 提供持久化的記憶層能力而面向 Platform API 的官方 SDK 入口統(tǒng)一為MemoryClient。本篇指南以 Mem0 官方技能文檔 sdk-guide.md 為骨架系統(tǒng)覆蓋記憶的寫入add、檢索search/get/getAll、更新update、刪除delete/deleteAll、歷史追蹤history、批量操作與導(dǎo)出等全部方法并給出 v2 到 v3 的遷移對(duì)照。讀完本篇你將能在 Python同步/異步與 TypeScript 中正確初始化客戶端、掌握 filters 過濾語法與命名規(guī)范、避開高頻踩坑點(diǎn)并把各方法對(duì)應(yīng)的源碼實(shí)現(xiàn)mem0/client/main.py、mem0-ts/src/client/mem0.ts與 REST 端點(diǎn)逐一對(duì)應(yīng)起來。需要說明的前提本指南默認(rèn)使用Platform API云端托管、零基礎(chǔ)設(shè)施所有身份參數(shù)user_id、agent_id、run_id等在 v3 中都必須放進(jìn)filters對(duì)象傳遞這一點(diǎn)在 SDK 源碼與 API 文檔中都有強(qiáng)制校驗(yàn)。若你使用 OSS 自托管方案可查閱倉庫內(nèi)更細(xì)分的語言級(jí)參考Python SDK 深度參考、Node.js SDK 深度參考 與 Python 與 TypeScript 差異對(duì)照表。初始化Initialization三種語言的初始化方式完全對(duì)稱構(gòu)造參數(shù)僅兩個(gè)api_key必填。除了顯式傳參Python 與 TypeScript SDK 都會(huì)在缺失時(shí)回退讀取MEM0_API_KEY環(huán)境變量見 mem0/client/main.py 的__init__。host可選默認(rèn)https://api.mem0.ai僅自建或代理場景需要覆蓋。Python同步from mem0 import MemoryClient client MemoryClient(api_keym0-your-api-key)Python異步from mem0 import AsyncMemoryClient client AsyncMemoryClient(api_keym0-your-api-key)TypeScriptimport MemoryClient from mem0ai; const client new MemoryClient({ apiKey: m0-your-api-key });源碼視角構(gòu)造函數(shù)實(shí)際做了什么閱讀 mem0/client/main.py 可以看到初始化并非只保存一個(gè) key而是完成以下四件事解析憑證self.api_key api_key or os.getenv(MEM0_API_KEY)兩者都為空時(shí)直接拋出ValueError(Mem0 API Key not provided...)。創(chuàng)建內(nèi)部 HTTP 客戶端Python 使用httpx.Clientbase_urlself.host并在請求頭寫入Authorization: Token {api_key}與Mem0-User-ID由 API key 的 MD5 計(jì)算而來超時(shí)默認(rèn) 300 秒。校驗(yàn) API key構(gòu)造時(shí)同步請求GET /v1/ping/把響應(yīng)中的org_id、project_id、user_email拉回客戶端用于后續(xù)項(xiàng)目級(jí)調(diào)用。初始化項(xiàng)目管理器self.project Project(...)支持自定義指令、分類、成員管理等平臺(tái)級(jí)能力。TypeScript 端mem0-ts/src/client/mem0.ts采用 axios全部方法均為async默認(rèn)超時(shí) 60 秒無同步變體兩種 SDK 的語言級(jí)差異詳見 differences.md。add()寫入記憶add()是記憶層的數(shù)據(jù)入口輸入一段對(duì)話消息列表由 Mem0 負(fù)責(zé)用 LLM 做事實(shí)抽取、去重與沉淀。Pythonmessages [ {role: user, content: Im a vegetarian and allergic to nuts.}, {role: assistant, content: Got it! Ill remember that.} ] client.add(messages, user_idalice) # 附帶元數(shù)據(jù) client.add(messages, user_idalice, metadata{source: onboarding})TypeScriptawait client.add(messages, { userId: alice }); await client.add(messages, { userId: alice, metadata: { source: onboarding } });參數(shù)說明名稱類型說明messagesarray對(duì)話消息形如[{role: user, content: ...}]user_idstring用戶標(biāo)識(shí)強(qiáng)烈建議提供agent_idstringAgent 標(biāo)識(shí)run_idstring會(huì)話/運(yùn)行標(biāo)識(shí)metadataobject自定義鍵值對(duì)inferboolean設(shè)為false時(shí)跳過 LLM 推斷直接存儲(chǔ)原始文本默認(rèn)true補(bǔ)充說明從 mem0/client/types.py 的AddMemoryOptions可以看出add()還支持custom_categories覆蓋項(xiàng)目分類、custom_instructions/agent_custom_instructions覆蓋抽取指令、timestampUnix 時(shí)間戳或 ISO 8601、expiration_dateYYYY-MM-DD 過期日期等可選字段消息格式方面源碼 mem0/client/main.py 會(huì)自動(dòng)把字符串轉(zhuǎn)換成{role: user, content: ...}、把單個(gè) dict 包裝成列表三種入?yún)⑿问蕉伎山邮堋Ｕ埱笞罱K落在POST /v3/memories/add/端點(diǎn)。高級(jí)用法Agent 與會(huì)話雙維度隔離、跳過推斷# Agent session scoping三維身份隔離 client.add(messages, user_idalice, agent_idnutrition-agent, run_idsession-456) # 原始文本直存 —— 跳過 LLM 推斷 client.add( [{role: user, content: User prefers dark mode.}], user_idalice, inferFalse, )要點(diǎn)雖然user_id、agent_id、run_id在add()中是作為頂層參數(shù)傳入的但在search()、get_all()中則必須下沉到filters里后文詳述這是 v3 最核心的 API 形態(tài)變化。search()語義檢索記憶search()用自然語言查詢做相關(guān)性召回。v3 采用混合檢索——語義向量、BM25 關(guān)鍵詞與實(shí)體匹配并行打分后融合返回結(jié)果里的score是融合后的[0, 1]置信度。詳見倉庫的 Search Memories 接口文檔。Pythonresults client.search(dietary preferences?, filters{user_id: alice}) # 組合 filters 重排 results client.search( querywork experience, filters{AND: [{user_id: alice}, {categories: {contains: professional_details}}]}, top_k5, rerankTrue, threshold0.5 )TypeScriptconst results await client.search(dietary preferences, { filters: { user_id: alice } }); const results await client.search(work experience, { filters: { AND: [{ user_id: alice }, { categories: { contains: professional_details } }] }, topK: 5, rerank: true, });參數(shù)說明名稱類型說明querystring自然語言檢索查詢filtersobject過濾對(duì)象支持 AND/OR 等邏輯運(yùn)算符。用{user_id: ...}按用戶過濾top_knumber返回條數(shù)Platform 默認(rèn) 10取值范圍 1–1000rerankboolean是否啟用重排以提升相關(guān)性默認(rèn)falsethresholdnumber最低相似度閾值默認(rèn) 0.1接口文檔還補(bǔ)充了兩個(gè)常用參數(shù)show_expiredPython 端為show_expiredTypeScript 端為showExpired默認(rèn)隱藏已過期記憶與latest_only僅返回同一記憶的最新版本。從源碼 mem0/client/main.py 可見search()在發(fā)出POST /v3/memories/search/前會(huì)先做一次查詢詞校驗(yàn)空串或純空白字符串直接拋ValueError且會(huì)先strip()去除首尾空白。filters 支持的運(yùn)算符filters對(duì)象支持邏輯運(yùn)算與比較運(yùn)算的組合邏輯運(yùn)算AND、OR、NOT比較運(yùn)算符in匹配枚舉值之一、gte大于等于、lte小于等于、gt大于、lt小于、ne不等于、icontains大小寫不敏感的包含判斷、contains包含通配符*匹配任意內(nèi)容。常用過濾模式全集以下模式同時(shí)給出 Python 與 TypeScript 寫法可直接復(fù)制使用。Python# 單用戶過濾 filters{user_id: alice} # 跨多個(gè) Agent 取并集OR filters{OR: [{user_id: alice}, {agent_id: {in: [travel-agent, sports-agent]}}]} # 分類過濾部分匹配 contains filters{AND: [{user_id: alice}, {categories: {contains: finance}}]} # 分類過濾精確匹配 in filters{AND: [{user_id: alice}, {categories: {in: [personal_information]}}]} # 通配符匹配任意非空 run_id filters{AND: [{user_id: alice}, {run_id: *}]} # 日期區(qū)間 filters{AND: [ {user_id: alice}, {created_at: {gte: 2024-01-01T00:00:00Z}}, {created_at: {lt: 2024-02-01T00:00:00Z}} ]} # 用 NOT 排除分類 filters{AND: [{user_id: user_123}, {NOT: {categories: {in: [spam, test]}}}]} # 多維查詢用戶 關(guān)鍵詞 分類 時(shí)間 filters{AND: [ {user_id: user_123}, {keywords: {icontains: invoice}}, {categories: {in: [finance]}}, {created_at: {gte: 2024-01-01T00:00:00Z}} ]}TypeScript// 單用戶過濾 filters: { user_id: alice } // 跨 Agent 并集OR filters: { OR: [{ user_id: alice }, { agent_id: { in: [travel-agent, sports-agent] } }] } // 分類部分匹配 filters: { AND: [{ user_id: alice }, { categories: { contains: finance } }] } // 分類精確匹配 filters: { AND: [{ user_id: alice }, { categories: { in: [personal_information] } }] }注意一個(gè)高頻誤區(qū)過濾器內(nèi)的鍵一律使用snake_caseuser_id、agent_id、categories、created_at即使你寫的是 TypeScript——TypeScript 只在方法級(jí)參數(shù)上用 camelCasetopK、pageSize過濾器對(duì)象里的鍵名是兩個(gè) SDK 保持一致的。倉庫測試對(duì)上述過濾語義有完整覆蓋例如 tests/test_client.py 中的test_search_passes_and_filters、test_search_passes_or_filters、test_search_passes_not_filters、test_search_passes_complex_nested_filters可作回歸驗(yàn)證參考。get() / getAll()按需讀取記憶按 ID 讀取單條記憶或按過濾器批量拉取記憶列表。Python# 按 ID 讀取單條記憶 memory client.get(memory_idea925981-...) # 讀取某用戶的全部記憶 memories client.get_all(filters{user_id: alice}) # 附帶日期區(qū)間過濾 memories client.get_all( filters{AND: [ {user_id: alex}, {created_at: {gte: 2024-07-01, lte: 2024-07-31}} ]} )TypeScriptconst memory await client.get(ea925981-...); const memories await client.getAll({ filters: { user_id: alice } });注意get_all()的filters中必須包含user_id、agent_id、app_id、run_id四者之一否則無法定位命名空間。同時(shí)v3 禁止把實(shí)體 ID 作為頂層參數(shù)傳給get_all()——mem0/client/main.py 中通過ENTITY_PARAMS常量做了硬校驗(yàn)一旦檢測到頂層出現(xiàn)user_id/agent_id/app_id/run_id會(huì)直接拋出ValueError提示改用filters。get_all()的分頁支持通過page與page_size控制二者在源碼中會(huì)被抽取成 URL 查詢參數(shù)后提交到POST /v3/memories/返回值是{count: ..., next: ..., previous: ..., results: [...]}的分頁結(jié)構(gòu)page/page_size單獨(dú)或同時(shí)傳入的行為差異均有測試覆蓋見 tests/test_client.py。此外get_all()還支持start_date/end_dateISO 8601、categories、show_expired、latest_only等選項(xiàng)見 mem0/client/types.py 的GetAllMemoryOptions。update()修改記憶按 memory ID 更新記憶文本或其元數(shù)據(jù)。Pythonclient.update(memory_idea925981-..., textUpdated: vegan since 2024) client.update(memory_idea925981-..., textUpdated, metadata{verified: True})TypeScriptawait client.update(ea925981-..., { text: Updated: vegan since 2024 });源碼細(xì)節(jié)mem0/client/main.py 對(duì)update()做了兩個(gè)值得注意的處理——其一會(huì)把None值字段過濾掉但expiration_date例外保留這意味著expiration_dateNone可用于清除過期時(shí)間對(duì)應(yīng)測試test_update_preserves_null_expiration_date其二若最終 payload 為空會(huì)拋ValueError提示至少提供text、metadata、timestamp、expiration_date之一。請求走PUT /v1/memories/{memory_id}/。delete() / deleteAll()刪除記憶Pythonclient.delete(memory_idea925981-...) client.delete_all(user_idalice) # 不可逆的批量刪除TypeScriptawait client.delete(ea925981-...); await client.deleteAll({ userId: alice });兩個(gè)方法語義差異明顯務(wù)必分清delete()只刪一條記憶可選參數(shù)delete_linked默認(rèn)False設(shè)為True時(shí)會(huì)連帶刪除該記憶取代過superseded的更早版本鏈linked_memory_ids用于防止刪除當(dāng)前記憶后舊版本復(fù)活。源碼見 mem0/client/main.py請求走DELETE /v1/memories/{memory_id}/。delete_all()是不可逆的批量刪除通過filters或頂層user_id/agent_id/app_id圈定刪除范圍走DELETE /v1/memories/。批量場景請務(wù)必先在get_all()中核對(duì)過濾條件無誤后再執(zhí)行。history()追蹤記憶變更歷史查看某條記憶從創(chuàng)建以來的每次變更記錄適合審計(jì)與調(diào)試。Pythonhistory client.history(memory_idea925981-...) # 返回形如: [{previous_value, new_value, action, timestamps}]TypeScriptconst history await client.history(ea925981-...);每條變更記錄包含變更前值previous_value、變更后值new_value、操作類型action如 ADD/UPDATE/DELETE與時(shí)間戳源碼路徑為 mem0/client/main.py請求走GET /v1/memories/{memory_id}/history/。批量操作TypeScript 示例批量更新 / 刪除在 Python 中對(duì)應(yīng)batch_update()、batch_delete()走PUT /v1/batch/與DELETE /v1/batch/mem0/client/main.pyTypeScript 側(cè)每個(gè)元素同樣只需給memoryId與可選的text/metadata。// 批量更新 await client.batchUpdate([ { memoryId: uuid-1, text: Updated text }, { memoryId: uuid-2, text: Another updated text }, ]); // 批量刪除 await client.batchDelete([uuid-1, uuid-2, uuid-3]);批量操作相比循環(huán)單條調(diào)用能顯著減少 HTTP 往返適合記憶整理、數(shù)據(jù)遷移等場景。附加方法實(shí)體管理、反饋與導(dǎo)出Python# 列出所有已產(chǎn)生記憶的用戶 / Agent / 會(huì)話 users client.users() # 刪除某用戶或 Agent實(shí)體及其全部記憶 client.delete_users(user_idalice) # 為一條記憶提交反饋用于改善抽取質(zhì)量 client.feedback(memory_id..., feedbackPOSITIVE, feedback_reasonAccurate extraction) # 導(dǎo)出記憶先創(chuàng)建導(dǎo)出任務(wù)再按 ID 拉取數(shù)據(jù) export client.create_memory_export(filters{AND: [{user_id: alice}]}) data client.get_memory_export(memory_export_idexport[id])對(duì)應(yīng)源碼與端點(diǎn)users()GET /v1/entities/返回所有存在記憶的實(shí)體用戶/Agent/會(huì)話列表mem0/client/main.py。delete_users()DELETE /v2/entities/{type}/{name}/。只傳一個(gè)身份時(shí)刪對(duì)應(yīng)實(shí)體什么都不傳時(shí)則先枚舉全部實(shí)體再逐一刪除相當(dāng)于全量清空同時(shí)它還支持agent_id、app_id、run_id維度mem0/client/main.py。feedback()枚舉值必須是POSITIVE、NEGATIVE、VERY_NEGATIVE三者之一代碼中用VALID_FEEDBACK_VALUES強(qiáng)制校驗(yàn)其余取值拋ValueError攜帶可選的feedback_reason請求走POST /v1/feedback/mem0/client/main.py。導(dǎo)出相關(guān)create_memory_export()/get_memory_export()對(duì)應(yīng)POST /v1/exports/與POST /v1/exports/get/mem0/client/main.py。Python 獨(dú)有、TypeScript 未覆蓋的能力還包括get_summary()記憶摘要與reset()清空全部用戶與記憶詳見 differences.md。常見踩坑點(diǎn)Common Pitfalls官方技能文檔總結(jié)的高頻坑逐條給出規(guī)避建議實(shí)體跨維度過濾會(huì)靜默返回空結(jié)果——AND組合user_idagent_id返回空集?？鐚?shí)體檢索請改用OR。SQL 風(fēng)格運(yùn)算符會(huì)被拒絕——必須用gte、lt等 Mem0 運(yùn)算符而不是、。metadata 過濾能力有限——僅支持頂層鍵且運(yùn)算符只有eq、contains、ne。通配符*排除空值——它只匹配非 null 的值想匹配任意 run需確認(rèn)該字段確實(shí)有值。默認(rèn) threshold 是 0.1——需要更嚴(yán)格匹配時(shí)主動(dòng)調(diào)高如 0.5接口文檔說明傳0.0可關(guān)閉閾值過濾。記憶處理是異步的——add()寫入后后臺(tái)需要一定時(shí)間完成推斷與落庫搜索前建議等待 2–3 秒文檔與技能源碼均如此提示否則可能查不到剛寫入的內(nèi)容。命名規(guī)范速查Python全程snake_case——user_id、memory_id、get_all()、batch_update()。TypeScript方法名與頂層參數(shù)用camelCasegetAll、deleteAll、batchUpdate、userId、topK、pageSize但filter 鍵名沿用snake_caseuser_id、agent_id、created_at。v2 到 v3 遷移指南如果你從 v2 升級(jí)下面四條是最關(guān)鍵的破壞性變更務(wù)必逐一核對(duì)調(diào)用點(diǎn)。1. search() 與 getAll() 中的實(shí)體 ID 必須移入 filtersv3 強(qiáng)制要求實(shí)體 IDuser_id、agent_id、run_id等放在filters對(duì)象內(nèi)頂層傳參會(huì)直接報(bào)錯(cuò)Python 端由ENTITY_PARAMS常量硬校驗(yàn)攔截見 mem0/client/main.py# v2已廢棄 client.search(query, user_idalice) client.get_all(user_idalice) # v3 client.search(query, filters{user_id: alice}) client.get_all(filters{user_id: alice})// v2已廢棄 await client.search(query, { user_id: alice }); await client.getAll({ user_id: alice }); // v3 await client.search(query, { filters: { user_id: alice } }); await client.getAll({ filters: { user_id: alice } });2. TypeScript 參數(shù)命名改為 camelCasev2v3user_iduserIdagent_idagentIdrun_idrunIdtop_ktopKpage_sizepageSize注意遷移時(shí)頂層參數(shù)按上表替換但filters 內(nèi)部的鍵如{user_id: alice}繼續(xù)使用snake_case不要一并改動(dòng)。3. 默認(rèn)值變化參數(shù)v2 默認(rèn)v3 默認(rèn)threshold0.30.1rerank未明確指定false默認(rèn)閾值從 0.3 降到 0.1意味著同樣的查詢在 v3 下會(huì)返回更多低相關(guān)度結(jié)果遷移后若感覺結(jié)果變雜請顯式調(diào)高threshold。4. 已移除的參數(shù)參數(shù)狀態(tài)enable_graph從 add/search/getAll 中移除keyword_search從 search 中移除filter_memories移除immutable從 add 中移除expiration_date從 add 中移除includes從 add 中移除excludes從 add 中移除async_mode從 add 中移除代碼中仍出現(xiàn)的對(duì)應(yīng)用法都需要清理例如 mem0/client/types.py 中SearchMemoryOptions尚保留keyword_search字段注釋但 v3 語義已不再接受該參數(shù)。建議遷移完成后用 tests/test_client.py 中的搜索/過濾相關(guān)用例作為行為基線對(duì)賬號(hào)內(nèi)數(shù)據(jù)進(jìn)行一次端到端回歸。延伸閱讀Platform 快速上手2 分鐘跑通 add search 的最小示例含 cURL。Python SDK 深度參考Python 端全部方法簽名、參數(shù)表與 OSS 自托管用法。Node.js SDK 深度參考TypeScript 端方法與 OSS 配置命名。Python vs TypeScript 差異方法名、超時(shí)、HTTP 庫、能力差異速查表。API 參考 與 Search Memories 接口文檔REST 端點(diǎn)、過濾器運(yùn)算符與記憶對(duì)象結(jié)構(gòu)。集成模式LangChain、CrewAI、Vercel AI SDK 等框架接入方式?！久赓M(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），僅供參考