Supermemory 完整教學 — AI 記憶與上下文引擎

第 1 章：專案定位與價值主張

核心問題：AI 的「失憶症」

每一次對話結束，AI 都會遺忘一切。你反覆告訴它你的偏好、你正在做的專案、你的技術棧——但下一次對話，它又從零開始。

Supermemory 解決的正是這個根本問題：讓 AI 擁有跨對話的持久記憶 (persistent memory)。

什麼是 Supermemory？

Supermemory 是一個開源的 Memory & Context Engine（記憶與上下文引擎），提供完整的記憶層 API。它不只是一個 vector database (向量資料庫) 或 RAG pipeline（檢索增強生成管線），而是一個完整的記憶系統：

• Memory Engine（記憶引擎）：從對話中自動提取事實，追蹤更新，解決矛盾，自動遺忘過期資訊
• User Profiles（使用者畫像）：自動維護的使用者上下文——靜態事實 (static facts) + 動態活動 (dynamic context)
• Hybrid Search（混合搜尋）：RAG + Memory 結合的單一查詢
• Connectors（連接器）：Google Drive、Gmail、Notion 等資料來源的即時同步
• Multi-modal Processing（多模態處理）：PDF、圖片、影片、程式碼的自動處理

Memory ≠ RAG

這是 Supermemory 最重要的設計理念。RAG (Retrieval-Augmented Generation) 檢索文件片段——無狀態、對所有人回傳相同結果。Memory (記憶) 則是提取並追蹤「關於使用者的事實」，隨時間演化。例如：

• RAG 回傳：「搬家到台北的流程文件」（靜態文件）
• Memory 記住：「使用者上個月從台中搬到台北」→ 取代先前的「使用者住在台中」

Supermemory 預設同時運行兩者，在每次查詢中提供知識庫檢索 + 個人化上下文。

基準測試表現 (Benchmark Results)

專案統計

第 2 章：安裝指南 (Installation Guide)

2.1 使用者模式：給 AI 工具加上記憶

MCP 快速安裝（最推薦）

1# 支援 Claude Desktop / Cursor / Windsurf / VS Code 等
2npx -y install-mcp@latest https://mcp.supermemory.ai/mcp --client claude --oauth=yes

將 claude 替換為你使用的客戶端名稱：cursor、windsurf、vscode 等。

手動 MCP 設定

在 MCP 客戶端設定檔中加入：

1{
2  "mcpServers": {
3    "supermemory": {
4      "url": "https://mcp.supermemory.ai/mcp"
5    }
6  }
7}

或使用 API key (API 金鑰) 而非 OAuth：

 1{
 2  "mcpServers": {
 3    "supermemory": {
 4      "url": "https://mcp.supermemory.ai/mcp",
 5      "headers": {
 6        "Authorization": "Bearer sm_your_api_key_here"
 7      }
 8    }
 9  }
10}

消費者 App

直接使用網頁 App：https://app.supermemory.ai

2.2 開發者模式：用 API 建構應用

TypeScript SDK

1npm install supermemory

Python SDK

1pip install supermemory

2.3 本地開發環境

1# 前置需求：Bun >= 1.2.17
2git clone https://github.com/supermemoryai/supermemory.git
3cd supermemory
4bun install
5cp .env.example .env.local
6# 編輯 .env.local 加入 API keys
7bun run dev

注意：本地開發需要修改 apps/web/proxy.ts，在取得 session cookie 之前加入 localhost bypass。

第 3 章：核心架構解析 (Architecture Deep Dive)

3.1 整體架構

Supermemory 採用 monorepo（單一倉庫） 結構，以 Turborepo + Bun workspaces 管理。整體分為三層：應用層 (apps)、套件層 (packages)、技能層 (skills)。

graph TB
    subgraph "Applications Layer"
        WEB["apps/web
Next.js 消費者 App
(Nova AI Agent)"]
        MCP["apps/mcp
MCP Server
(Hono + CF Workers)"]
        EXT["apps/browser-extension
瀏覽器擴充功能
(WXT)"]
        DOCS["apps/docs
文件站"]
        GRAPH_APP["apps/memory-graph-playground
Memory Graph 遊樂場"]
        RAYCAST["apps/raycast-extension
Raycast 擴充功能"]
    end

    subgraph "Packages Layer"
        MG["packages/memory-graph
Canvas 記憶圖視覺化"]
        SDK_AI["packages/ai-sdk
Vercel AI SDK 整合"]
        TOOLS["packages/tools
多框架整合工具"]
        LIB["packages/lib
共用工具 + 驗證"]
        UI["packages/ui
共用 UI 元件"]
        VAL["packages/validation
API Schema 驗證"]
    end

    subgraph "Python SDKs"
        PY_OAI["packages/openai-sdk-python"]
        PY_PIPE["packages/pipecat-sdk-python"]
        PY_CART["packages/cartesia-sdk-python"]
        PY_AGENT["packages/agent-framework-python"]
    end

    subgraph "Backend (Cloud)"
        API["api.supermemory.ai
核心 API 服務"]
        MEMORY["Memory Engine
事實提取 + 矛盾解決
+ 自動遺忘"]
        PROFILE["User Profile Engine
Static + Dynamic"]
        SEARCH["Hybrid Search
RAG + Memory"]
        CONN["Connectors
Google Drive / Gmail /
Notion / OneDrive / GitHub"]
    end

    WEB --> API
    MCP --> API
    EXT --> API
    TOOLS --> API
    SDK_AI --> TOOLS
    PY_OAI --> API
    PY_AGENT --> API

    API --> MEMORY
    API --> PROFILE
    API --> SEARCH
    API --> CONN

3.2 MCP Server 架構

MCP (Model Context Protocol) server 是 Supermemory 最核心的使用者介面之一。它基於 Hono 框架，部署在 Cloudflare Workers 上，使用 Durable Objects 維護狀態。

提供三個主要工具 (tools)：

3.3 Memory Graph 視覺化

packages/memory-graph 是一個 Canvas-based (畫布) 的記憶圖視覺化元件，使用 force simulation（力模擬） 和 spatial indexing（空間索引） 來呈現記憶之間的關聯。關鍵技術：

• Force-directed graph layout（力導向圖佈局）
• Spatial indexing for hit testing（空間索引碰撞檢測）
• Version chain tracking（版本鏈追蹤）
• Edge logic for relationship rendering（邊邏輯關係渲染）

3.4 多框架整合層

packages/tools 提供多框架整合：

• Vercel AI SDK (@supermemory/tools/ai-sdk)
• OpenAI Agents SDK (@supermemory/tools/openai)
• Claude Memory Tool (@supermemory/tools/claude-memory)
• Mastra (@supermemory/tools/mastra)
• LangChain / LangGraph (@supermemory/tools/langchain)

第 4 章：使用方式詳解 (Usage Guide)

4.1 TypeScript SDK 基本操作

 1import Supermemory from "supermemory";
 2
 3const client = new Supermemory();
 4
 5// 1. 儲存內容
 6await client.add({
 7  content: "使用者偏好 TypeScript，喜歡 functional patterns",
 8  containerTag: "user_123",
 9});
10
11// 2. 取得使用者畫像 + 相關記憶
12const { profile, searchResults } = await client.profile({
13  containerTag: "user_123",
14  q: "使用者的程式設計偏好？",
15});
16// profile.static  → ["喜歡 TypeScript", "偏好 functional patterns"]
17// profile.dynamic → ["正在做 API 整合"]
18
19// 3. 混合搜尋（RAG + Memory）
20const results = await client.search.memories({
21  q: "如何部署？",
22  containerTag: "user_123",
23  searchMode: "hybrid",  // "hybrid" | "memories" | "documents"
24});
25
26// 4. 上傳檔案
27await client.documents.uploadFile(file);
28
29// 5. 列出文件
30const docs = await client.documents.list();

4.2 Python SDK 基本操作

 1from supermemory import Supermemory
 2
 3client = Supermemory()
 4
 5# 儲存
 6client.add(
 7    content="使用者偏好 Python，使用 pytest 測試",
 8    container_tag="user_456"
 9)
10
11# 查詢使用者畫像
12result = client.profile(container_tag="user_456", q="測試偏好")
13print(result.profile.static)   # 長期事實
14print(result.profile.dynamic)  # 近期上下文

4.3 搜尋模式 (Search Modes)

4.4 Framework 整合範例

 1// Vercel AI SDK
 2import { withSupermemory } from "@supermemory/tools/ai-sdk";
 3const model = withSupermemory(
 4  openai("gpt-4o"),
 5  { containerTag: "user_123", customId: "conv-1" }
 6);
 7
 8// Mastra
 9import { withSupermemory } from "@supermemory/tools/mastra";
10const agent = new Agent(
11  withSupermemory(config, "user-123", { mode: "full" })
12);

4.5 Connectors（連接器）

支援的資料來源自動同步：

第 5 章：應用場景 (Use Cases)

5.1 個人 AI 助理記憶

安裝 MCP plugin 後，你的 AI 助理（Claude Desktop、Cursor 等）會自動記住：

• 你的程式設計偏好與風格
• 你正在做的專案與進度
• 過去討論過的解決方案
• 你的工作環境偏好

5.2 企業級 AI 產品

用一個 API 為你的 AI 產品加上完整記憶層：

• 客服 chatbot：記住客戶歷史問題與偏好
• 教育 AI：追蹤學習進度與理解程度
• 健康管理：記錄使用者健康偏好與歷史（須注意隱私合規）
• 開發工具：記住開發者的技術棧、coding style、常用 patterns

5.3 知識管理平台

透過 Connectors 自動同步多個資料來源，建立統一的知識庫：

• 自動處理 PDF、圖片（OCR）、影片（轉錄）、程式碼（AST-aware chunking）
• 文件自動切片 (chunking)、索引、可搜尋

5.4 研究輔助

結合 Hybrid Search，在個人研究記憶與文獻知識庫之間做交叉查詢：

• 「上次我們討論的那篇關於 memory consolidation 的 paper 是哪篇？」
• 同時回傳：相關文獻（RAG）+ 你對該主題的討論歷史（Memory）

第 6 章：資安掃描報告 (Security Scan Report)

整體評級：🟡 中等風險

🟢 低風險項目

🟡 中等風險項目

🔴 高風險項目

資安建議

1. 優先處理 protobufjs CVE：升級至 8.0.1 / 7.5.5 以修補 CVE-2026-41242
2. 修復 CI workflow：限制 claude-auto-fix-ci.yml 只在 same-repo PR 觸發
3. 收斂 CORS：MCP server 的 origin: "*" 應改為白名單
4. sanitize innerHTML：瀏覽器擴充功能應改用 textContent 或 DOM API 取代 innerHTML

第 7 章：常見問題 FAQ

Q1: Supermemory 和 Mem0、Zep 有什麼不同？

Supermemory 在三大 benchmark（LongMemEval、LoCoMo、ConvoMem）均排名第一。它整合了 Memory + RAG + User Profiles + Connectors 成一個統一 API，而非分散的元件。提供官方 MemoryBench 框架可直接對比。

Q2: 免費嗎？

Supermemory 原始碼是 MIT 開源的。消費者 App（app.supermemory.ai）有免費方案。API 使用有計費方案，包括免費 tier。

Q3: 我的資料安全嗎？

MCP server 支援 OAuth 和 API key 驗證。Memory 透過 containerTag 做 scope 隔離。但因為是雲端服務，資料會經過 Supermemory 的 API 伺服器。

Q4: Claude Code plugin 寫入記憶但搜尋回傳空值？

這是已知問題（Issue #792），可能與 API key 或 OAuth 設定有關。建議：

1. 確認 API key 格式正確（以 sm_ 開頭）
2. 確認 containerTag 一致
3. 等待幾秒讓記憶索引完成

Q5: 支援哪些 AI 客戶端？

Claude Desktop、Cursor、Windsurf、VS Code、Claude Code、OpenCode、OpenClaw、Hermes。

Q6: 可以自架 (self-host) 嗎？

目前 MCP server 部署在 Cloudflare Workers 上。原始碼開源可以自行修改，但核心 API（記憶引擎、使用者畫像引擎）是雲端服務。

第 8 章：進階技巧 (Advanced Techniques)

8.1 Project Scoping（專案隔離）

使用 containerTag 將記憶分群：

 1// 工作專案
 2await client.add({
 3  content: "Sprint 目標：完成 auth migration",
 4  containerTag: "work_project_alpha",
 5});
 6
 7// 個人學習
 8await client.add({
 9  content: "正在學 Rust，偏好 systems programming",
10  containerTag: "personal_learning",
11});

8.2 Automatic Forgetting（自動遺忘）

Supermemory 會自動處理：

• 時效性事實：「我明天有考試」→ 日期過後自動遺忘
• 矛盾解決：「我住在台中」→ 後來說「我搬到台北了」→ 舊事實被取代
• 噪音過濾：不重要的對話內容不會成為永久記憶

8.3 Custom Memory Settings

1await client.settings.update({
2  // 自訂記憶提取與切片策略
3});

8.4 MemoryBench 自訂基準測試

1# 安裝 MemoryBench skill
2npx skills add supermemoryai/memorybench
3
4# 執行基準測試
5bun run src/index.ts run -p supermemory -b longmemeval -j gpt-4o -r my-run

第 9 章：整合進其他工作流

9.1 與 n8n 整合

Supermemory 提供 n8n 整合，可在自動化工作流中加入記憶功能。

9.2 與 Zapier 整合

透過 Zapier connector 可將記憶層加入現有自動化流程。

9.3 與 AI Knowledge Template 整合

在本 AI-knowledge_template 系統中，Supermemory 可作為：

1. Layer 5 ai-notebooklm 的補充：NotebookLM 處理結構化問答，Supermemory 處理跨 session 的持久記憶
2. paper-qa-lite 的增強：將研究 session 的上下文持久化，下次回來時不必重新建立
3. MCP 層的標準化記憶：所有 Claude Code session 共享統一記憶

9.4 與 Agent Framework 整合

Python Agent Framework SDK 提供：

 1from supermemory_agent_framework import AgentSupermemory
 2
 3conn = AgentSupermemory(
 4    api_key=os.environ["SUPERMEMORY_API_KEY"],
 5    container_tag="agent-session-1"
 6)
 7
 8# 自動注入上下文到 agent 系統提示
 9context = conn.get_context()
10
11# 儲存 agent 的學習
12conn.add_memory("使用者的專案使用 FastAPI + PostgreSQL")

第 10 章：重點摘要 Checklist

核心概念

• 理解 Memory vs RAG 的差異：Memory 提取追蹤使用者事實，RAG 檢索文件片段
• 理解 Hybrid Search：同時搜尋記憶與文件
• 理解 User Profile：static facts + dynamic context

安裝與設定

• 選擇安裝模式：MCP plugin（使用者）或 SDK（開發者）
• MCP 安裝指令：npx -y install-mcp@latest https://mcp.supermemory.ai/mcp --client <client> --oauth=yes
• SDK 安裝：npm install supermemory 或 pip install supermemory
• 本地開發：bun install + 環境變數設定

開發整合

• 使用 containerTag 做 scope 隔離
• 選擇正確的 searchMode：hybrid / memories / documents
• 整合到 Vercel AI SDK / OpenAI / Mastra / LangChain
• 設定 Connectors 自動同步資料來源

資安注意

• 使用環境變數管理 API key，不要 hardcode
• 注意 protobufjs CVE-2026-41242（待上游修復）
• MCP server CORS 為 origin: "*"，公開部署時需收斂

第 11 章：進一步閱讀 (Further Reading)

官方資源

相關 GitHub Repos

Benchmark 論文與資料集

相關技術

• MCP (Model Context Protocol)：AI 工具的標準化上下文協議
• RAG (Retrieval-Augmented Generation)：檢索增強生成
• Cloudflare Workers + Durable Objects：邊緣運算 + 有狀態服務
• Turborepo + Bun：高效能 monorepo 建構工具鏈