使用手冊

GitHub 實戰手冊 · AI 記憶基礎設施

AI Agent 的持久 記憶層

Supermemory 繁體中文實戰手冊：比較 App、MCP、API 與本機自架路徑，說明記憶、使用者輪廓、混合搜尋、容器隔離與部署邊界。

Supermemory 是面向 AI 應用的記憶與情境引擎，將對話與文件轉成可更新的事實、使用者輪廓及可檢索內容。這份手冊整理 App、MCP、API 與本機自架四種入口，並以容器隔離、混合搜尋與資料邊界協助選型。

supermemoryai/supermemory
星標
—
分支
—
授權
—
資料截至
—
閱讀時間
7 分
更新日期
開啟原始報告
GitHub Stars
28.6k
MCP 核心工具
4
主要 SDK 方法
7
開放原始碼授權
MIT
本頁章節

01產品定位

文件檢索之外的記憶與情境層

Supermemory 接收對話、文字、網址與檔案，從內容中抽取可重用的事實，建立使用者輪廓，並在後續請求中回傳相關情境。它也處理資訊更新、互相矛盾的敘述與有時效的內容，讓記憶不只是累積紀錄。

**記憶與 RAG 是兩種不同工作。**RAG 從文件片段找答案；記憶則追蹤特定使用者的偏好、活動與事實版本。Supermemory 的預設混合搜尋把文件檢索與個人化記憶放進同一個查詢，也能切換成只搜尋記憶。

每個 containerTag 可代表使用者、專案、組織或知識庫，作為記憶的隔離邊界。輪廓回應區分較穩定的 static 事實與近期的 dynamic 情境；內容處理完成後，也能透過中繼資料與語意條件篩選。

  1. 輸入

  2. 抽取

  3. 切塊

  4. 索引

  5. 更新

  6. 檢索

  7. 遺忘

“Supermemory is the memory and context layer for AI.”

— supermemoryai/supermemory README

02四種進入方式

先選運行邊界再接上記憶

只想建立個人記憶，可直接使用 Supermemory App。要讓 Claude Code、Cursor 等相容客戶端跨對話保留情境，使用 MCP；要把記憶放進產品流程，安裝 TypeScript 或 Python SDK。

bash
# TypeScript / JavaScript
npm install supermemory

# Python
pip install supermemory

# Hosted API 憑證
export SUPERMEMORY_API_KEY="your_api_key_here"

MCP 客戶端設定

MCP 伺服器預設使用 OAuth。將下列設定加入支援遠端 MCP 的客戶端，客戶端會在連線時引導登入；若要把整條連線限制在特定專案，可另加 x-sm-project 標頭。

json
{
  "mcpServers": {
    "supermemory": {
      "url": "https://mcp.supermemory.ai/mcp"
    }
  }
}

03十二個核心介面

同一套記憶核心對應不同使用面

Supermemory 將記憶抽取、使用者輪廓、文件檢索與連接器放在同一個資料模型上，再以 SDK、MCP 與本機伺服器提供不同入口。先確認資料是否屬於單一使用者、專案或組織，再選定穩定的 containerTag。

Ingest · 01

client.add()

內容輸入

新增文字、對話、網址或 HTML，並以容器標籤與中繼資料標記來源。

Memory · 02

Memory Engine

事實演化

從內容抽取事實，追蹤新舊版本、矛盾與有時效的資訊。

Profile · 03

client.profile()

使用者輪廓

回傳穩定事實、近期情境，以及與查詢相關的記憶結果。

Search · 04

client.search()

混合檢索

以混合模式一起搜尋 RAG 文件與記憶，或切換成只搜尋記憶。

Sync · 05

Connectors

外部資料同步

連接 Google Drive、Gmail、Notion、OneDrive、GitHub 與網頁爬取來源。

Files · 06

documents.uploadFile()

多模態處理

上傳 PDF、圖片、影片與程式碼，經抽取、切塊與索引後提供搜尋。

MCP · 07

memory

記憶寫入

讓 AI 助手儲存或忘記一項資訊，並可指定專案容器。

MCP · 08

recall

記憶召回

依查詢搜尋相關記憶，並可同時回傳使用者輪廓摘要。

MCP · 09

listMemories

記憶盤點

按來源文件列出抽取後的記憶，適合在刪除過期資訊前進行稽核。

MCP · 10

whoAmI

連線身分

回傳目前登入者與客戶端工作階段資訊，用於確認授權身分。

MCP · 11

context

輪廓注入

以 MCP prompt 將穩定偏好與近期活動帶入新的 AI 對話。

Local · 12

supermemory-server

本機運行

在連接埠 6767 提供同一套記憶 API，並將資料保存於本機目錄。

入口選擇矩陣

目標建議入口第一個動作
個人知識與對話記憶Supermemory App前往 app.supermemory.ai
現有 AI 助手的跨對話記憶MCP 或官方外掛設定遠端 MCP URL
產品中的個人化與知識檢索TypeScript / Python SDK建立 API 金鑰與容器規則
資料留在自有機器Supermemory local啟動 supermemory-server

04官方操作原則

記憶品質來自清楚的邊界

記憶系統的結果不只取決於模型，也取決於資料如何分區、何時寫入及如何取回。以下原則整理自專案 README、Supermemory skill 參考文件與 MCP 伺服器說明。

先定義穩定的容器標籤

使用內部既有的使用者、專案或組織識別碼。寫入與查詢必須沿用同一個 containerTag，避免記憶落入不同空間。

來源 · 官方 Quickstart

用連線標頭鎖定 MCP 專案

若整個 MCP 連線只服務單一專案，可設定 x-sm-project。伺服器會把該連線的操作固定在指定範圍。

來源 · apps/mcp/README.md

把金鑰留在伺服器端

Hosted API 使用 SUPERMEMORY_API_KEY。不要把金鑰寫進瀏覽器端程式、版本庫或範例輸出；MCP 客戶端可優先採用 OAuth。

來源 · 官方 Quickstart 與 MCP 說明

先取回情境再生成回應

聊天產品的基本循環是先呼叫 profile() 取得相關情境，組入系統訊息，再於對話結束後以 add() 保存新內容。

來源 · skills/supermemory Quickstart

依問題切換搜尋模式

hybrid 同時帶回文件與記憶，適合知識庫問答；memories 只檢索使用者事實，適合偏好與近期活動。

來源 · 官方 README

區分長期事實與近期情境

名稱、角色等長期事實可標記為靜態記憶；對話、活動與可能被後續資訊取代的內容保留為動態記憶。

來源 · skills/supermemory Architecture

用中繼資料保留來源脈絡

在寫入時加入來源、內容類型與時間戳記。後續可透過中繼資料篩選，縮小語意搜尋的候選範圍。

來源 · 官方 API Reference

把連接器視為持續同步來源

Google Drive、Gmail、Notion、OneDrive、GitHub 與網頁內容會進入處理流程。查詢端仍應用容器與中繼資料限制資料範圍。

來源 · 官方 README

刪除前先盤點已抽取記憶

MCP 的 listMemories 按來源文件列出記憶事實。先盤點再執行 memory 的 forget 動作，可降低刪錯範圍的風險。

來源 · apps/mcp/README.md

把本機資料目錄納入備份

Supermemory local 將資料集中於 ./.supermemory。切換主機前先備份該目錄，應用程式只需調整 SDK 的 baseURL。

來源 · 官方 README · Self-host

05API 實作範例

一次寫入下一輪取得個人情境

以下流程沿用官方 README 的 TypeScript 介面：先把一段對話寫入固定容器，再以同一個 containerTag 取得使用者輪廓與相關記憶。範例回應只表示欄位結構，實際內容取決於帳戶中的資料與處理狀態。

~/projects/memory-demo · TypeScript · hosted API


$ You ›
  > npm install supermemory
  > export SUPERMEMORY_API_KEY="your_api_key_here"


# [建立 memory.ts]


claude: memory.ts ›
  import Supermemory from "supermemory";
  const client = new Supermemory();


  await client.add({
    content: "User loves TypeScript and prefers functional patterns",
    containerTag: "user_123",
  });


  const { profile, searchResults } = await client.profile({
    containerTag: "user_123",
    q: "What programming style does the user prefer?",
  });


  console.log(profile.static);
  console.log(profile.dynamic);
  console.log(searchResults);


$ You › npx tsx memory.ts


# [示意回應結構；實際內容依帳戶資料而異]
ok: profile.static  → 長期事實
ok: profile.dynamic → 近期情境
ok: searchResults   → 依相似度排序的相關記憶

“Your AI forgets everything between conversations. Supermemory fixes that.”

— supermemoryai/supermemory README

範例中的資料流

add() 接收原始內容並交給背景處理流程；profile() 則把同一容器中的長期事實、近期情境與相關搜尋結果組成回應。兩次呼叫使用相同的容器標籤，才會落在同一個記憶空間。

實際聊天流程通常在生成回應前呼叫 profile()，將結果放進提示詞；對話完成後再呼叫 add()。若處理尚未完成，搜尋結果可能不會立刻包含剛寫入的內容。

06部署前檢查

記憶會累積邊界也要持續管理

07進階路徑

從單一記憶走向可治理的情境系統

Supermemory 同時提供消費者 App、遠端 MCP、SDK、連接器與本機伺服器。導入順序可從單一使用者與單一容器開始，確認寫入、輪廓、檢索與刪除行為後，再擴大資料來源。

進階玩法地圖

**1. 先用 MCP 驗證個人記憶。**在支援的 AI 客戶端加入遠端 MCP，測試 memory、recall、listMemories 與 context，並確認專案範圍。

**2. 再把 API 放進產品迴圈。**於生成回應前呼叫 profile()，回應完成後呼叫 add()。先定義容器命名、原始紀錄與刪除政策。

**3. 導入文件與連接器。**需要知識庫時再啟用檔案上傳與外部同步，並以混合搜尋同時取得文件證據與個人化情境。

**4. 評估本機運行。**若資料邊界要求自架，可用本機伺服器保留相同 API 介面。備份 ./.supermemory，並記錄模型、嵌入供應商與 baseURL。

**5. 把記憶納入產品治理。**建立可查看、修正與忘記記憶的使用者介面，監控處理延遲與跨容器結果，並定期驗證連接器權限。

官方延伸閱讀

① 專案 README：四種使用入口、SDK 範例、搜尋模式與本機運行。 ② MCP Server 4.0：OAuth、專案範圍、工具、資源與 prompt。 ③ Self-hosting：本機伺服器、設定與模型選擇。 ④ Memory vs. RAG：個人事實追蹤與文件檢索的差異。

“Give your AI a memory.”

— supermemoryai/supermemory README