實戰手冊 · Field Manual 2026 夏季號
github.com/supermemoryai/supermemory · 28,554 ★
s
GitHub 實戰手冊 · AI 記憶基礎設施

AI Agent 的
持久 記憶層

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

28.6k
GitHub Stars
4
MCP 核心工具
7
主要 SDK 方法
MIT
開放原始碼授權
01
產品定位

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

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

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

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

Supermemory · 內容與記憶生命週期
輸入→ 抽取→ 切塊→ 索引→ 更新→ 檢索→ 遺忘
“Supermemory is the memory and context layer for AI.”
— supermemoryai/supermemory README
02
四種進入方式

先選運行邊界
再接上記憶

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

# 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 標頭。

{ "mcpServers": { "supermemory": { "url": "https://mcp.supermemory.ai/mcp" } } }
本機自架。執行 curl -fsSL https://supermemory.ai/install | bash，或以 npx supermemory local 安裝，再用 supermemory-server 啟動。API 位於 http://localhost:6767，資料集中在 ./.supermemory；首次啟動會設定圖形引擎、嵌入模型與憑證。
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 伺服器說明。

TIP 01

先定義穩定的容器標籤

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

來源 · 官方 Quickstart
TIP 02

用連線標頭鎖定 MCP 專案

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

來源 · apps/mcp/README.md
TIP 03

把金鑰留在伺服器端

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

來源 · 官方 Quickstart 與 MCP 說明
TIP 04

先取回情境再生成回應

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

來源 · skills/supermemory Quickstart
TIP 05

依問題切換搜尋模式

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

來源 · 官方 README
TIP 06

區分長期事實與近期情境

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

來源 · skills/supermemory Architecture
TIP 07

用中繼資料保留來源脈絡

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

來源 · 官方 API Reference
TIP 08

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

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

來源 · 官方 README
TIP 09

刪除前先盤點已抽取記憶

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

來源 · apps/mcp/README.md
TIP 10

把本機資料目錄納入備份

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

來源 · 官方 README · Self-host
05
API 實作範例

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

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

~/projects/memory-demo · TypeScript · hosted API
You › npm install supermemory export SUPERMEMORY_API_KEY="your_api_key_here"
[建立 memory.ts]
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
[示意回應結構；實際內容依帳戶資料而異] profile.static → 長期事實 profile.dynamic → 近期情境 searchResults → 依相似度排序的相關記憶
“Your AI forgets everything between conversations.
Supermemory fixes that.”
— supermemoryai/supermemory README

範例中的資料流

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

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

06
部署前檢查

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

  • API 金鑰不得進入前端程式。Hosted API 以 Bearer token 驗證。金鑰應留在伺服器端或受控環境變數中，MCP 可改用 OAuth 登入。
  • 容器標籤不是應用程式授權。containerTag 負責資料分區；產品仍需在呼叫 Supermemory 前驗證使用者，並確保他只能使用自己的容器識別碼。
  • 新記憶具有處理延遲。內容會經過抽取、切塊、嵌入與索引。MCP 的端對端測試也以輪詢等待 recall，產品介面不應假設寫入後立刻可查。
  • 記憶不是逐字對話備份。系統會抽取事實並排除雜訊。若法規、稽核或客服流程要求保存原文，應另設原始紀錄與保留政策。
  • 忘記操作也可能需要等待。MCP 專案的端對端測試將刪除確認標記為較慢的最佳努力檢查。需要強制刪除時，應在產品層追蹤狀態並重新驗證。
  • 靜態記憶只適合長期事實。isStatic 用於名稱、角色等不常變動的資料。近期活動與可能被新資訊取代的偏好應保留為動態記憶。
  • 本機運行仍需檢查模型去向。Supermemory local 可使用本機嵌入與 Ollama，也能連接外部模型供應商。資料是否離開機器取決於實際模型與端點設定。
  • 外部連接器會擴大資料範圍。啟用雲端硬碟、信箱或程式碼連接器前，先確認來源權限、資料保留需求與容器規則，再驗證搜尋結果沒有跨租戶內容。
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