人工智能（AI）技術發展迅速，大型語言模型（LLMs）極大地簡化了許多任務。然而，它們面臨一個基本限制：會話之間無法保留記憶。

圖片

如果能夠擁有一個本地的、便攜的 LLM “記憶層”，完全掌控您的數據，會怎樣呢？

今天，我們將介紹 OpenMemory MCP，一個基于 Mem0（AI 代理的記憶層）構建的私有、本地優先的記憶層。它支持跨 MCP 兼容客戶端（如 Cursor、Claude Desktop、Windsurf、Cline 等）實現持久化、上下文感知的 AI。

本指南將詳細說明如何安裝、配置和運行 OpenMemory MCP 服務器，同時涵蓋其內部架構、流程、底層組件以及實際應用案例和示例。

涵蓋內容

簡而言之，本文將詳細探討以下主題：

?什么是 OpenMemory MCP 服務器及其重要性？?逐步設置和運行 OpenMemory 的指南。?儀表板可用功能（及其背后的技術）。?安全性、訪問控制和架構概述。?實際應用案例及示例。

一、什么是 OpenMemory 及其重要性？

OpenMemory MCP 是一個為 MCP 客戶端設計的私有、本地記憶層。它提供了存儲、管理和跨平臺利用 AI 記憶的基礎設施，同時確保所有數據存儲在本地系統上。

簡單來說，它是一個基于向量的記憶層，適用于使用標準 MCP 協議的任何 LLM 客戶端，并與 Mem0 等工具無縫協作。

核心功能：

?跨會話存儲和調用任意文本片段（記憶），確保 AI 無需從零開始。

?底層使用向量存儲（Qdrant）進行基于相關性的檢索，而非僅限于關鍵詞匹配。

?完全運行在您的基礎設施上（Docker + Postgres + Qdrant），數據不會外傳。

?支持在應用或記憶級別暫停或撤銷客戶端訪問權限，并為每次讀寫操作生成審計日志。

?提供儀表板（基于 Next.js 和 Redux），展示誰在讀寫記憶以及狀態變更歷史。

工作原理（基本流程）

核心流程如下：

1.通過單一 docker-compose 命令啟動 OpenMemory（API、Qdrant、Postgres）。

2.API 進程托管一個使用 Mem0 的 MCP 服務器，通過 SSE（Server-Sent Events）支持標準 MCP 協議。

3.LLM 客戶端通過 SSE 流連接到 OpenMemory 的 /mcp/... 端點，調用 add_memories()、search_memory() 或 list_memories() 等方法。

4.向量索引、審計日志和訪問控制等其他功能由 OpenMemory 服務自動處理。

您可以觀看官方演示并在 mem0.ai/openmemory-mcp^[1] 上了解更多！

二、逐步設置和運行 OpenMemory

本節將指導您如何在本地設置和運行 OpenMemory。

項目包含兩個主要組件：

?api/ - 后端 API 和 MCP 服務器?ui/ - 前端 React 應用程序（儀表板）

步驟 1：系統要求

在開始之前，請確保您的系統已安裝以下內容，并附上文檔鏈接以便參考：

?Docker 和 Docker Compose?Python 3.9+ — 后端開發所需

?Node.js — 前端開發所需?OpenAI API 密鑰 — 用于 LLM 交互?GNU Make — 構建自動化工具，用于設置過程

請確保 Docker Desktop 已運行，然后繼續下一步。

步驟 2：克隆倉庫并設置 OpenAI API 密鑰

通過以下命令克隆位于 github.com/mem0ai/mem0^[2] 的倉庫：

git clone https://github.com/mem0ai/mem0.git
cd openmemory

接下來，將您的 OpenAI API 密鑰設置為環境變量：

export OPENAI_API_KEY=your_api_key_here

圖片

注意：此命令僅為當前終端會話設置密鑰，關閉終端窗口后失效。

圖片

步驟 3：設置后端

后端運行在 Docker 容器中。在根目錄運行以下命令啟動后端：

# 復制環境文件并編輯以更新 OPENAI_API_KEY 和其他密鑰
make env


# 構建所有 Docker 鏡像
make build


# 啟動 Postgres、Qdrant 和 FastAPI/MCP 服務器
make up

.env.local 文件遵循以下格式：

OPENAI_API_KEY=your_api_key

圖片

圖片

設置完成后，API 將在 http://localhost:8000 上運行。您可以在 Docker Desktop 中查看運行中的容器。

以下是一些其他有用的后端命令：

# 運行數據庫遷移
make migrate


# 查看日志
make logs


# 進入 API 容器 shell
make shell


# 運行測試
make test


# 停止服務
make down

步驟 4：設置前端

前端是一個 Next.js 應用程序。啟動前端只需運行：

# 使用 pnpm 安裝依賴并運行 Next.js 開發服務器
make ui

圖片

安裝成功后，訪問 http://localhost:3000 查看 OpenMemory 儀表板，儀表板將指導您在 MCP 客戶端中安裝 MCP 服務器。

儀表板界面如下所示：

圖片

MCP 客戶端通過 SSE 通道連接到 GET /mcp/{client_name}/sse/{user_id}，綁定兩個上下文變量（user_id 和 client_name）。

在儀表板中，您將找到基于您選擇的客戶端（如 Cursor、Claude、Cline、Windsurf）的一行安裝命令。例如，在 Cursor 中安裝的命令如下：

npx install-mcp i https://mcp.openmemory.ai/xyz_id/sse --client cursor

如果尚未安裝 install-mcp，系統會提示您安裝，然后您只需為服務器提供一個名稱。

注意：上述為示例命令，請忽略具體內容。打開 Cursor 設置，在側邊欄檢查 MCP 選項以驗證連接。

圖片

在 Cursor 中打開新聊天，輸入類似“我希望它記住我的 GitHub 簡介信息”的提示。這將觸發 add_memories() 調用并存儲記憶。刷新儀表板，進入“Memories”選項卡查看所有記憶。

圖片

記憶會自動分類（通過 GPT-4o 分類），作為可選標簽。

圖片

您還可以連接其他 MCP 客戶端，如 Windsurf。

圖片

每個 MCP 客戶端可調用以下四種標準記憶操作：

?add_memories(text) → 將文本存儲在 Qdrant，插入/更新 Memory 行和審計條目?search_memory(query) → 嵌入查詢，運行向量搜索（帶可選 ACL 過濾），記錄每次訪問?list_memories() → 檢索用戶的所有存儲向量（按 ACL 過濾）并記錄列表操作?delete_all_memories() → 清除所有記憶

所有響應通過同一 SSE 連接流式傳輸。儀表板顯示所有活動連接、訪問記憶的應用程序以及讀寫詳情。

圖片

三、儀表板功能（及其背后的技術）

OpenMemory 儀表板包含三個主要路由：

?/ – 儀表板首頁?/memories – 查看和管理存儲的記憶?/apps – 查看連接的應用程序

以下是儀表板提供的主要功能概覽：

1) 安裝 OpenMemory 客戶端

?獲取您的唯一 SSE 端點或使用一行安裝命令。?在 MCP Link 和不同客戶端選項卡（Claude、Cursor、Cline 等）之間切換。

2) 查看記憶和應用統計

?查看存儲的記憶數量。?查看連接的應用程序數量。

?輸入任意文本以實時搜索所有記憶（去抖動處理）。

?相關代碼位于 ui/components/dashboard/Stats.tsx，功能包括：

?從 Redux 讀取（profile.totalMemories、profile.totalApps、profile.apps[]）。?在掛載時調用 useStats().fetchStats() 填充存儲。

?渲染“總記憶數”和“連接的應用總數”，顯示最多 4 個應用圖標。

圖片

3) 刷新或手動創建記憶

?刷新按鈕：重新調用當前路由的相應獲取器。?創建記憶按鈕：打開 CreateMemoryDialog 模態框。

圖片

4) 過濾面板

?可選擇：?包含哪些應用?包含哪些類別?是否顯示歸檔項目?按哪列排序（記憶、應用名稱、創建時間）?一鍵清除所有過濾器。

圖片

5) 檢查和管理單個記憶

?點擊任意記憶可：

圖片

?歸檔、暫停、恢復或刪除記憶?查看訪問日志和相關記憶?支持選擇多個記憶并執行批量操作。

圖片

??? 背后技術：關鍵組件

以下是涉及的主要前端組件：

?ui/app/memories/components/MemoryFilters.tsx：處理搜索輸入、過濾對話框觸發器、批量操作（如歸檔/暫停/刪除），并管理行選擇狀態。

?ui/app/memories/components/MemoriesSection.tsx：加載、分頁和顯示記憶列表的主容器。

?ui/app/memories/components/MemoryTable.tsx：渲染記憶表格（ID、內容、客戶端、標簽、創建日期、狀態）。每行通過 MemoryActions 提供操作（編輯、刪除、復制鏈接）。

?狀態管理和 API 調用使用以下鉤子：

?useStats.ts：加載高級統計數據，如總記憶數和應用數。

?useMemoriesApi.ts：處理記憶的獲取、刪除和更新。

?useAppsApi.ts：檢索應用信息和每個應用的記憶詳情。

?useFiltersApi.ts：支持獲取類別和更新過濾器狀態。

這些組件共同打造了一個響應式、實時的儀表板，讓您完全掌控 AI 記憶層。

四、安全性、訪問控制和架構概述

在處理 MCP 協議或任何 AI 代理系統時，安全性至關重要。以下是簡要討論。

安全性

OpenMemory 遵循隱私優先原則，所有記憶數據存儲在您的本地基礎設施中，使用 Docker 化的組件（FastAPI、Postgres、Qdrant）。

敏感輸入通過 SQLAlchemy 的參數綁定安全處理，防止注入攻擊。每次記憶交互（添加、檢索、狀態變更）都會通過 MemoryStatusHistory 和 MemoryAccessLog 表記錄以確保可追溯性。

雖然未內置認證，但所有端點需要 user_id，并可通過外部認證網關（如 OAuth 或 JWT）保護。

FastAPI 的 CORS 在本地/開發環境中為開放狀態（allow_origins=["*"]），但在生產環境中，您應收緊此設置以限制僅信任客戶端訪問。

訪問控制

OpenMemory 注重細粒度訪問控制。access_controls 表定義了應用與特定記憶之間的允許/拒絕規則。

這些規則通過 check_memory_access_permissions 函數強制執行，考慮記憶狀態（活動、暫停等）、應用活動狀態（is_active）和 ACL 規則。

在實踐中，您可以暫停整個應用（禁用寫入）、歸檔或暫停單個記憶，或按類別或用戶應用過濾器。暫停或非活動條目對工具訪問和搜索不可見。這種分層訪問模型確保您可以自信地控制記憶訪問。

圖片

架構

以下是系統架構的簡要概述，更多詳情可參考代碼庫：

1.后端（FastAPI + FastMCP over SSE）：?提供 REST 接口（/api/v1/memories、/api/v1/apps、/api/v1/stats）和 MCP “工具”接口（/mcp/messages、/mcp/sse/<client>/<user>），代理通過 SSE 調用 add_memories、search_memory、list_memories。?連接 Postgres 存儲關系元數據，連接 Qdrant 進行向量搜索。2.向量存儲（通過 mem0 客戶端的 Qdrant）：?所有記憶在 Qdrant 中進行語義索引，查詢時應用用戶和應用特定過濾器。3.關系元數據（SQLAlchemy + Alembic）：?跟蹤用戶、應用、記憶條目、訪問日志、類別和訪問控制。?Alembic 管理架構遷移。?默認數據庫為 SQLite（openmemory.db），但可通過 DATABASE_URL 指向 Postgres。4.前端儀表板（Next.js）：?Redux 提供實時可觀察性界面。?Hooks + Redux Toolkit 管理狀態，Axios 與 FastAPI 端點通信。?使用 Recharts 實現實時圖表、輪播和 React Hook Form 處理表單。5.基礎設施與開發工作流：?docker-compose.yml（api/docker-compose.yml）包含 Qdrant 服務和 API 服務。?Makefile 提供遷移、測試、熱重載的快捷方式。?測試與后端邏輯共存（通過 pytest）。

這些組件共同打造了一個自托管的 LLM 記憶平臺：

?? 在關系數據庫和向量索引中存儲和版本化聊天記憶?? 通過每個應用的 ACL 和狀態轉換（活動/暫停/歸檔）保護數據?? 通過 Qdrant 進行語義搜索?? 通過豐富的 Next.js UI 觀察和控制

五、實際應用案例及示例

熟悉 OpenMemory 后，您會發現它可用于任何需要 AI 跨交互記憶的場景，從而實現高度個性化。

以下是一些高級和創造性的使用方式：

? 多代理研究助手與記憶層

想象構建一個工具，其中不同 LLM 代理專注于不同研究領域（例如，一個處理學術論文，一個處理 GitHub 倉庫，另一個處理新聞）。每個代理通過 add_memories(text) 存儲其發現，主代理隨后通過 search_memory(query) 檢索所有先前結果。

技術流程：

?每個子代理為 MCP 客戶端：?將檢索數據的摘要添加到 OpenMemory。?使用 GPT 自動分類為記憶添加標簽。?主代理打開 SSE 通道，使用 search_memory("最新擴散模型論文") 提取相關上下文。?儀表板顯示每個代理存儲的內容，您可通過 ACL 限制代理間的記憶訪問。

提示：可添加 LangGraph 編排層，每個代理作為一個節點，跟蹤記憶的寫入/讀取，可視化每個研究線程的知識流和來源。

? 具有跨會話持久記憶的智能會議助手

可構建一個會議記錄工具（支持 Zoom、Google Meet 等），功能包括：

?通過 LLM 提取摘要。?跨會議記憶行動項。?在未來會議中自動檢索相關上下文。

技術流程：

?每次會議后通過 add_memories(text) 存儲會議記錄和行動項。?下次會議前運行 search_memory("Project X 的未完成項")。?相關記憶（按適當類別標記）顯示在 UI 中，審計日志跟蹤記憶的讀取時間和內容。

提示：與 Google Drive、Notion、GitHub 等工具集成，存儲的行動項可鏈接到實時文檔和任務。

? 隨使用進化的代理編碼助手

您的 CLI 編碼助手可通過存儲使用模式、常見問題、編碼偏好和項目特定提示來學習您的工作方式。

技術流程：

?當您詢問“為什么我的 SQLAlchemy 查詢失敗？”，助手通過 add_memories 存儲錯誤和修復。?下次您輸入“再次遇到 SQLAlchemy 連接問題”，助手自動運行 search_memory("sqlalchemy join issue") 檢索先前修復。?通過 /memories 儀表板檢查所有存儲記憶，暫停過時或錯誤的記憶。

提示：可連接到 codemod 工具（如 jscodeshift），根據存儲的偏好自動重構代碼，隨代碼庫發展而演進。

在上述案例中，OpenMemory 的向量搜索（用于語義召回）、關系元數據（用于審計/日志記錄）和實時儀表板（用于可觀察性和即時訪問控制）讓您能夠構建上下文感知的應用程序，感覺就像它們擁有記憶。

現在，您的 MCP 客戶端擁有真正的記憶能力。

您可以跟蹤每次訪問、暫停所需內容并在一個儀表板中審計所有操作。最棒的是，所有內容都存儲在您的本地系統上。

References

[1] mem0.ai/openmemory-mcp: https://mem0.ai/openmemory-mcp

[2] github.com/mem0ai/mem0: https://github.com/mem0ai/mem0