mem0ai/mem0 詳細教學

把 mem0 從「給 AI 加記憶」這句口號，拆成可實作、可評估、可資安審查的工程文件。

1. 專案定位（Project Positioning）

1.1 解決什麼問題

大型語言模型 (LLM; Large Language Model) 在單次 context window 內非常聰明，但跨 session 之間沒有狀態。每次對話結束，使用者所有偏好、之前的決定、實體關係都會消失。傳統解法有兩種：

解法	缺點
長 context（把所有歷史塞進 prompt）	token 成本爆炸，且 LLM attention 對長 context 衰減
檢索增強生成 (RAG; Retrieval-Augmented Generation)	只是檢索，不是「記憶」— 沒有更新 / 矛盾消解 / 重要性權重

mem0 的定位是介於 LLM 與 vector store 之間的智慧 memory layer，它做四件事：

抽取：從原始對話自動萃取 fact（事實）/ preference（偏好）/ entity（實體）
存儲：寫入 vector store（嵌入語意向量）+ 選用 graph store（建構實體關係）
更新：用 LLM 判斷新資訊與舊記憶的衝突 → 自動 ADD / UPDATE / DELETE / NONE
檢索：給 query，回相關記憶 + 重排序 (reranking)

1.2 三大產品形態

形態	對應目錄	適用情境
Mem0 Platform（hosted SaaS）	`mem0/client/`	不想自己跑 vector store，直接 call `mem0.ai` API
Mem0 OSS Server（self-hosted REST API）	`server/`	內部部署，FastAPI + PostgreSQL/pgvector + Neo4j
Mem0 SDK（library import）	`mem0/memory/`	嵌入你自己的應用，自己控制 vector store

1.3 為什麼受矚目（56K stars）

Y Combinator S24 入選
論文 / blog 聲稱在 LOCOMO benchmark 對 OpenAI Memory 有 +26% LLM-as-judge 評分
與 30+ vector store / 24 LLM / 15 embedding provider 整合，生態系廣
MCP（Model Context Protocol）原生支援：能直接被 Claude Code / Cursor / Codex 當記憶層使用

2. 安裝指南（Installation）

2.1 三條安裝路徑


flowchart TD
    A[要怎麼用 mem0?] --> B{使用情境}
    B -->|嵌入自己的 Python app| C[pip install mem0ai
= SDK only]
    B -->|嵌入自己的 Node/TS app| D[npm install mem0ai
or pnpm add mem0ai]
    B -->|想要 REST API + DB| E[git clone + cd server
make bootstrap]
    B -->|想要 Claude Code 整合| F[mem0-plugin 走 MCP]
    
    C --> G[from mem0 import Memory]
    D --> H[import Memory from mem0ai/oss]
    E --> I[localhost:8888 / FastAPI]
    F --> J[Claude Code 自動裝載]

2.2 Python SDK（最常見）

 1# 1) 環境準備（用 uv 隔離，避免污染系統 Python）
 2uv venv mem0-env
 3source mem0-env/bin/activate
 4uv pip install mem0ai
 5
 6# 2) 額外裝想用的 vector store / LLM
 7uv pip install qdrant-client      # 預設 vector store
 8uv pip install openai             # 預設 LLM
 9
10# 3) 設定 API key
11export OPENAI_API_KEY=sk-...
12
13# 4) 最小範例
14python -c "
15from mem0 import Memory
16m = Memory()
17m.add('我喜歡騎公路車', user_id='alice')
18print(m.search('運動偏好', user_id='alice'))
19"

⚠️ 避免 pip install mem0ai 在系統 Python 直接裝 — mem0 會拉一大堆 transitive dependency（LangChain、Pydantic v2、Qdrant client…），與其他專案容易衝突。請用 uv venv 或 conda 隔離。

2.3 TypeScript SDK

1# 一律用 pnpm，repo 內所有 TS 套件都是 pnpm
2pnpm add mem0ai
3
4# OSS 版（self-hosted）
5import { Memory } from 'mem0ai/oss';
6
7# Hosted 版
8import { MemoryClient } from 'mem0ai';

2.4 Self-hosted Server（推薦給內部部署）

 1git clone https://github.com/mem0ai/mem0.git
 2cd mem0/server
 3
 4# 一鍵啟動：FastAPI + PostgreSQL(pgvector) + Neo4j
 5make bootstrap
 6
 7# 服務埠：
 8# - Mem0 API: localhost:8888
 9# - PostgreSQL: localhost:8432
10# - Neo4j HTTP: localhost:8474, Bolt: localhost:8687

.env.example 結構（不要把 key 寫在程式碼）：

1OPENAI_API_KEY=
2ANTHROPIC_API_KEY=         # optional
3POSTGRES_HOST=
4POSTGRES_PASSWORD=
5ADMIN_API_KEY=
6JWT_SECRET=
7AUTH_DISABLED=false        # 上 production 一定要 false
8MEM0_DEFAULT_LLM_MODEL=gpt-4.1-nano-2025-04-14
9MEM0_DEFAULT_EMBEDDER_MODEL=text-embedding-3-small

2.5 OpenMemory（即將 sunset，先別用）

openmemory/ 提供本地 MCP server + dashboard UI，但官方已標註 Sunsetting Notice，推薦改用 server/。

3. 核心架構解析（Core Architecture）

3.1 整體分層


flowchart TB
    subgraph 應用層
        A1[使用者 / AI Agent]
    end
    
    subgraph "mem0 SDK 層"
        B1[Memory / AsyncMemory
OSS Class]
        B2[MemoryClient / AsyncMemoryClient
Platform Client]
    end
    
    subgraph "Provider 層 - 5 大類 plugin pattern"
        P1[LLMs
24 種]
        P2[Embeddings
15 種]
        P3[Vector Stores
30 種]
        P4[Graph Stores
4 種 - 選用]
        P5[Rerankers
5 種 - 選用]
    end
    
    subgraph 儲存層
        S1[(Qdrant / Chroma /
Pinecone / pgvector ...)]
        S2[(Neo4j / Memgraph
選用)]
    end
    
    subgraph "整合層"
        I1[mem0-plugin
Claude/Cursor/Codex MCP]
        I2[openmemory
Local MCP Server]
        I3[server/
REST API]
    end
    
    A1 --> B1
    A1 --> B2
    A1 --> I1
    A1 --> I3
    B1 --> P1
    B1 --> P2
    B1 --> P3
    B1 --> P4
    B1 --> P5
    P3 --> S1
    P4 --> S2
    B2 -.HTTPS.-> Cloud[mem0.ai Cloud]
    I1 --> B2
    I2 --> B1
    I3 --> B1

3.2 Provider Pattern（5 個目錄一致的設計）

目錄	數量	代表 provider
`mem0/llms/`	24	openai, anthropic, aws_bedrock, gemini, groq, ollama, vllm, litellm, lmstudio, xai, deepseek, …
`mem0/embeddings/`	15	openai, fastembed, huggingface, ollama, vertexai, …
`mem0/vector_stores/`	30	qdrant, chroma, pinecone, milvus, weaviate, mongodb, pgvector, supabase, redis, elasticsearch, faiss, s3_vectors, …
`mem0/reranker/`	5	cohere, huggingface, llm-based, sentence_transformer, zero_entropy
`mem0/memory/`	—	核心 Memory class + storage / telemetry / utils

每個 provider 目錄都長一樣：

base.py — 抽象基底類別
configs.py — Pydantic v2 config 模型
<provider>.py — 具體實作（繼承 base）
__init__.py — 註冊

→ 想加新 provider 只要照模板實作 5 個 method 即可。

3.3 Memory 物件的核心方法

Method	用途
`add(messages, *, user_id, agent_id, run_id, metadata)`	寫入新記憶（會走 LLM 抽取 fact）
`search(query, *, user_id, agent_id, run_id, limit, filters)`	查記憶（語意檢索 + 選用 reranker）
`get(memory_id)`	取單筆
`get_all(...)`	列出該 user/agent/run 的所有記憶
`update(memory_id, data)`	改記憶
`delete(memory_id)`	刪記憶
`delete_all(...)`	刪該 user/agent/run 的所有記憶
`history(memory_id)`	看一筆記憶的變更歷史（v1.1 後支援）

3.4 新版（2026-04）記憶更新演算法


sequenceDiagram
    participant App
    participant Mem0
    participant LLM
    participant VS as Vector Store
    
    App->>Mem0: add("我改喝拿鐵，不是美式了")
    Mem0->>LLM: 抽取 fact
    LLM-->>Mem0: ["使用者偏好拿鐵"]
    Mem0->>VS: 搜尋相關現有記憶
    VS-->>Mem0: ["使用者偏好美式咖啡"]
    Mem0->>LLM: 衝突判斷 (new vs existing)
    LLM-->>Mem0: action=UPDATE
old=美式 → new=拿鐵
    Mem0->>VS: update(memory_id, new_text)
    Mem0-->>App: ok

關鍵設計：LLM 不是只用來抽取，更用來做「該怎麼合併新舊記憶」的決策（ADD / UPDATE / DELETE / NONE 四種 action）。這是 mem0 與一般 RAG 系統的本質差別。

3.5 兩種模式對應的目錄

模式	目錄	入口 class
Self-hosted（OSS）	`mem0/memory/main.py`	`Memory`, `AsyncMemory`
Hosted（Platform）	`mem0/client/main.py`	`MemoryClient`, `AsyncMemoryClient`

4. Helper Scripts / CLI 詳細用法

4.1 mem0-cli（Python CLI）

1# 安裝
2pip install mem0-cli      # 或 pipx install mem0-cli
3
4# 註冊一個 agent identity（v0.2.6+）
5mem0 whoami                       # 看當前身份
6mem0 signup --as claude-code      # 註冊一個 agent name
7
8# 一鍵把 mem0 整合進現有 repo（v0.2.7 新增 agent-rush）
9mem0 agent-rush

4.2 @mem0/cli（Node CLI）

1pnpm dlx @mem0/cli login           # OAuth 流程
2pnpm dlx @mem0/cli init            # 在 repo 內建立 .mem0/ 設定
3pnpm dlx @mem0/cli sync            # 把 mem0 platform 的記憶同步到本地

4.3 Makefile 入口（開發者用）

1make install          # hatch env create
2make install_all      # 裝所有 optional dependency（30 種 vector store + 24 種 LLM 全裝）
3make format           # ruff format
4make lint             # ruff check
5make test             # hatch run test（跑 pytest）
6make test-py-3.10     # 指定 Python 版本跑測試
7make build            # hatch build
8make docs             # cd docs && mintlify dev（本地預覽文件）

4.4 server/ 入口

1cd server
2make bootstrap        # 一鍵起 FastAPI + Postgres + Neo4j
3make dev              # 開發模式
4make test             # API 測試

REST endpoints（節選 server/main.py）：

Method	Path	用途
`GET`	`/configure`	看目前 LLM / embedder / vector store 設定
`POST`	`/memories`	add 一筆記憶
`GET`	`/memories`	列記憶（支援 user_id / agent_id filter）
`POST`	`/search`	語意搜尋記憶
`PATCH`	`/memories/{id}`	改一筆記憶
`DELETE`	`/memories/{id}`	刪一筆記憶
`POST`	`/auth/...`	API key / JWT 認證

4.5 openmemory/run.sh（即將 sunset，僅供參考）

1curl -sL https://raw.githubusercontent.com/mem0ai/mem0/main/openmemory/run.sh | \
2  OPENAI_API_KEY=sk-... bash
3
4# 起 4 個服務：
5# - Qdrant:  localhost:6333
6# - MCP API: localhost:8765
7# - UI:      localhost:3000

5. 應用場景（Use Cases）

5.1 場景 A：個人化 ChatGPT 替代品

把每次對話中使用者透露的偏好寫進 mem0，下次對話自動帶上。

 1from mem0 import Memory
 2m = Memory()
 3
 4# 第一次對話
 5m.add([
 6    {"role": "user", "content": "我對花生過敏"},
 7    {"role": "assistant", "content": "記下了，會避免推薦含花生的食譜"}
 8], user_id="alice")
 9
10# 一週後新 session
11context = m.search("使用者的飲食限制", user_id="alice", limit=3)
12# → [{"text": "使用者對花生過敏", "score": 0.92, ...}]

5.2 場景 B：客服 chatbot 跨工單記憶

每位客戶 = 一個 user_id，每張工單 = 一個 run_id。客服 agent 處理新工單前先 search 該 user 的歷史記憶。

5.3 場景 C：Multi-agent 系統共享記憶

agent_id 維度允許多個 agent 共享同一個 user 的 memory pool。examples/multiagents/ 有 LangGraph 範例。

5.4 場景 D：把 mem0 當作 Claude Code 的記憶層

裝 mem0-plugin → Claude Code 透過 MCP 自動 call mem0 的 9 個 tools（add_memory / search_memories / update_memory / …）。這是這次發展最快的整合方向。

5.5 場景 E：論文 / 文獻記憶（RAG over papers）

把 paper-search / paper-tutorial 抓回來的論文摘要寫進 mem0（agent_id="literature-reviewer"），讓 agent 在查新主題時自動 recall 已讀過的相關 paper。

6. 資安掃描報告（Security Scan）

掃描日期：2026-05-22，掃描範圍：mem0/ + server/ + openmemory/

6.1 風險摘要

等級	項目	處理建議
🔴 高	Memory poisoning（OWASP ASI06）— 攻擊者透過注入毒化記憶讓 agent 後續行為偏移；mem0 GitHub 上有 4+ 個 open issue 在追這條（#5151 / #5195 / #5130 / #5148）	上 production 前必須加 input validation 層；參考 issue #5151 的揭露細節
🟡 中	`subprocess.check_call([sys.executable, "-m", "pip", "install", ...])` 出現在 `mem0/embeddings/ollama.py` 與 `mem0/proxy/main.py`，做 optional dependency 的 lazy install	套件名為 hardcoded，攻擊面有限；但建議改用 try-import + 提示使用者手動裝
🟡 中	Transitive dependency CVE — 近兩次 commit (#5217, #5219) 才剛修 langchain / starlette / mcp / cryptography / lodash 的 CVE	鎖 `mem0ai>=2.0.2` 並建立每月 `pip-audit` / `npm audit` 流程
🟡 中	`Memory.search()` 接受空白 query 不做 input validation，可能導致 crash 或回傳意外資料（issue #5220）	上層 wrap 一層 sanitize；等官方 fix
🟡 中	`__import__()` dynamic loading 出現在 `mem0/vector_stores/configs.py:48` 做 provider 動態載入	只 import hardcoded 的 provider key，無使用者輸入；風險低，但 audit 時注意
🟢 低	無 `eval()` / `os.system()` / `shell=True` / `pickle.loads()` 等典型 RCE pattern
🟢 低	無 hardcoded secret；`.env.example` 範例完整、`server/main.py` 有 `_redact_config()` 函式做日誌脫敏
🟢 低	server 有 rate limiter（`SlowAPI`），有 `RateLimitExceeded` exception handler

6.2 進 production 必做 checklist

把 AUTH_DISABLED=false 寫死在 production env，並 review JWT_SECRET 強度
設一個 _validate_bundled_providers() 的 allowlist（server/main.py 已有，確認你的 provider 在內）
對所有 user-supplied 的 memory text 做長度上限與字元 sanitize（OWASP ASI06）
監控 mem0.search() 的回傳，若 top-k 出現意外語言或非預期實體 → 觸發 alert
每月跑 pip-audit + pnpm audit + GitHub Dependabot
不要把 graph memory（Neo4j）與 vector memory 共用 ADMIN credentials（#5151 揭露的攻擊面）

6.3 結論

🟡 中等風險。核心程式碼乾淨、無典型 RCE pattern、有近期積極修補 CVE。主要風險來自 mem0 這類「LLM 記憶層」的本質攻擊面（memory poisoning），這不是實作 bug，而是設計層面要 layer-up 防禦。建議：上 production 前讀完 issue #5151 / #5195，並在你的 wrapper 加一層 input/output sanitization。

7. FAQ

Q1: mem0 vs LangChain Memory / LlamaIndex memory 差在哪？ A1: LangChain Memory 只是 chat history buffer + summarization；mem0 做的是 fact-level 抽取與衝突合併。LlamaIndex 偏 RAG over documents；mem0 是 RAG over user/agent state。

Q2: 需要 Graph Store（Neo4j）嗎？ A2: 預設不需要。只在需要實體關係查詢（“alice 認識誰” / “X 影響 Y”）時開。否則純 vector store 就夠。

Q3: Vector Store 該選哪一個？ A3:

開發 / 本地測試：qdrant（預設）或 chroma（無需服務、檔案模式）
production 小規模：pgvector（複用 Postgres）
production 大規模：pinecone（hosted）或 milvus（self-hosted）
多模態 + 大量 metadata filtering：weaviate

Q4: 為什麼 search 出來的記憶會重複？ A4: 因為 mem0 的 UPDATE / DELETE 判斷依賴 LLM，便宜 LLM（如 gpt-4o-mini）可能漏判導致 ADD 重複。對策：用較強的 LLM 做 memory operation，但可以用便宜 LLM 做最終回應。

Q5: Hosted vs Self-hosted 怎麼選？ A5:

快速 PoC / demo：Hosted（不用管 vector store）
資料合規 / 內部部署 / 大量 query：Self-hosted server（server/ 目錄）
嵌入單一 app 不想跑額外服務：直接 import Memory class

Q6: 怎麼 evaluate 我的 mem0 設定好不好？ A6: 看 evaluation/ 目錄，內含 LOCOMO benchmark 跑法（generate_scores.py + run_experiments.py）。可拿來測你選的 LLM + embedder 組合。

Q7: mem0 可以離線跑（無外部 LLM API）嗎？ A7: 可以。mem0/llms/ollama.py + mem0/embeddings/ollama.py + mem0/vector_stores/chroma.py 全套都在本地。但 memory operation 的 LLM 品質會直接影響最終效果，本地 7B 模型品質不夠。

8. 進階技巧

8.1 Multi-tier Memory（短期 + 長期）

把 metadata: {"tier": "short"} 用於對話 buffer，{"tier": "long"} 用於持久偏好。search 時用 filters 區分。

8.2 Reranker 提升 search 精度

1config = {
2    "vector_store": {"provider": "qdrant", "config": {...}},
3    "llm": {"provider": "openai", "config": {...}},
4    "embedder": {"provider": "openai", "config": {...}},
5    "reranker": {"provider": "cohere", "config": {"api_key": "..."}}
6}
7m = Memory.from_config(config)

→ search 會先取 top 20 vector，再用 Cohere reranker 重排到 top 5。對 ambiguous query 提升明顯。

8.3 自定義 fact-extraction prompt

Memory.__init__ 可以傳 custom_prompt（v1.1+），讓你針對 domain（醫療 / 法務 / 金融）改 LLM 抽 fact 的 prompt。

8.4 與 LangGraph / AutoGen 整合

cookbooks/ 有 autogen 範例；examples/multiagents/ 有 LangGraph 範例。模式都一樣：在 agent 每次 turn 結束時 m.add(messages)，下次 turn 開始時 m.search(query) 注入到 system prompt。

8.5 把 mem0 包成 MCP server

openmemory/api/ 就是現成範例：FastAPI + mcp SDK 包裝 Memory class。可以 fork 做你自己的 MCP 整合。

9. 整合進其他工作流

對 AI-knowledge_template 而言，mem0 可以填補三個位置：

位置	用法
paper-tutorial / paper-search 之間的記憶層	跑完 paper-search 後把 abstract 寫入 mem0（`agent_id="lit-review"`），下次查相關主題自動 recall
patent-creator 的程式碼分析記憶	Phase A 分析過的程式碼 / 法律觀點存進 mem0（機密 session 內請改用本地 Ollama LLM + Chroma，禁止 cloud API）
meeting-intel 的廠商歷史記憶	每次 meeting prep 把廠商背景 / 之前討論寫進 mem0，下次同個廠商 prep 直接 recall

⚠️ 機密邊界：mem0 預設會 call OpenAI 做 fact extraction。patent-creator session 內不可使用 mem0（會把專利 draft 送到 OpenAI）。若一定要用，請改用 mem0/llms/ollama.py + mem0/embeddings/ollama.py 全本地配置。


flowchart LR
    A[paper-search] -->|abstract| M[(mem0)]
    B[meeting-intel] -->|廠商背景| M
    C[ai-gh-save] -->|repo 摘要| M
    M --> D[未來 session
自動 recall]
    
    P[patent-creator] -.X 禁止.-> M
    M2[(mem0 本地配置
Ollama + Chroma)] -.可選.-> P

10. 重點摘要 Checklist

mem0 是 LLM 與 vector store 之間的智慧 memory layer，不只 RAG，還做衝突消解
三種使用形態：hosted (MemoryClient) / self-hosted server (server/) / library (Memory class)
5 大 provider 類別共 78 種 plugin（24 LLM + 15 embedding + 30 vector store + 4 graph + 5 reranker）
核心 4 個 method：add / search / update / delete + history
2026-04 新演算法：LLM 判斷 ADD / UPDATE / DELETE / NONE，自動衝突合併
與 Claude Code / Cursor / Codex 透過 MCP 整合（mem0-plugin/）
資安：核心程式乾淨，但 memory poisoning 是本質攻擊面（看 #5151）；transitive CVE 已積極修補
整合進本專案：可接 paper-search / meeting-intel / ai-gh-save 作為跨 session 記憶層；patent-creator 不可用 cloud 版本

11. 進一步閱讀

資源	連結
官方文件	https://docs.mem0.ai
Mem0 platform	https://mem0.ai
論文 / blog	https://mem0.ai/research
MCP server	https://mcp.mem0.ai
Discord	https://mem0.dev/DiG
LOCOMO benchmark	`evaluation/` 目錄
關鍵 issue	#5151（安全揭露）/ #5195（OWASP ASI06）/ #5220（input validation）
同類專案	LangChain Memory, LlamaIndex, Letta（前 MemGPT）, Zep

Generated by: AI-knowledge_template gh-tutorial-qd workflow · 2026-05-22

mem0ai/mem0 詳細教學 — Universal Memory Layer for AI Agents

Contents