Supermemory 深度调研报告

基于 GitHub 开源项目 supermemoryai/supermemory 的深度技术调研
调研日期：2026-03-27

Supermemory 深度调研报告

基于 GitHub 开源项目 supermemoryai/supermemory 的深度技术调研

调研日期：2026-03-27

一、项目概述

1.1 基本信息

属性	信息
项目名称	Supermemory
GitHub	https://github.com/supermemoryai/supermemory
开发者	supermemoryai
官网	https://supermemory.ai
核心定位	AI 时代的记忆引擎
开源状态	MIT License
Stars	19,747
Forks	1,835
主要语言	TypeScript
创建时间	2024-02-27
活跃状态	持续更新中

1.2 一句话介绍

Supermemory 是一个AI 记忆引擎，让 AI 系统能够跨对话记住信息，自动提取事实、构建用户画像、处理知识更新和矛盾，并在正确的时间交付正确的上下文。

1.3 解决的问题

传统 AI 系统的问题：

┌─────────────────────────────────────────────────────────────┐
│  对话 1: "我喜欢 TypeScript"                                 │
│  AI: "好的，我记住了"                                        │
│                                                             │
│  对话 2: (新对话)                                            │
│  用户: "我之前说我喜欢什么语言？"                             │
│  AI: "抱歉，我不知道..." ← 完全忘记了！                      │
└─────────────────────────────────────────────────────────────┘

                    ↓ Supermemory 解决方案 ↓

┌─────────────────────────────────────────────────────────────┐
│  对话 1: "我喜欢 TypeScript"                                 │
│  AI: "好的，已记录到你的档案中"                              │
│                                                             │
│  对话 2: (新对话)                                            │
│  用户: "我之前说我喜欢什么语言？"                             │
│  AI: "你喜欢 TypeScript" ← 从记忆中检索！                   │
└─────────────────────────────────────────────────────────────┘

1.4 核心能力

能力	描述
记忆提取	从对话中自动提取事实
用户画像	自动维护用户上下文 (~50ms 响应)
知识更新	处理时间变化、矛盾和自动遗忘
混合搜索	RAG + Memory 单一查询
连接器	Google Drive、Gmail、Notion、GitHub 等
多模态处理	PDF、图片(OCR)、视频(转录)、代码(AST 分块)

1.5 基准测试表现

Supermemory 在所有三个主要 AI 记忆基准测试中排名第一：

基准测试	测量内容	结果
LongMemEval	跨会话长期记忆与知识更新	81.6% - #1
LoCoMo	扩展对话中的事实回忆	#1
ConvoMem	个性化和偏好学习	#1

二、核心架构

2.1 整体架构图

┌─────────────────────────────────────────────────────────────────────────┐
│                       Supermemory Architecture                           │
├─────────────────────────────────────────────────────────────────────────┤
│                                                                         │
│   ┌─────────────────────────────────────────────────────────────────┐  │
│   │                      Your App / AI Tool                         │  │
│   │  ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐   │  │
│   │  │Claude   │ │ Cursor  │ │  VSCode │ │  Web    │ │  Mobile │   │  │
│   │  │Desktop  │ │  IDE    │ │  Agent  │ │  App    │ │  App    │   │  │
│   │  └────┬────┘ └────┬────┘ └────┬────┘ └────┬────┘ └────┬────┘   │  │
│   │       │           │           │           │           │         │  │
│   │       └───────────┴───────────┼───────────┴───────────┘         │  │
│   │                               │                                   │  │
│   └───────────────────────────────┼───────────────────────────────────┘  │
│                                   │                                     │
│                                   ▼                                     │
│   ┌─────────────────────────────────────────────────────────────────┐  │
│   │                     Supermemory API                              │  │
│   │  ┌──────────────────────────────────────────────────────────┐   │  │
│   │  │                  Memory Engine                            │   │  │
│   │  │  • 事实提取        • 时间追踪        • 矛盾解决           │   │  │
│   │  │  • 自动遗忘        • 用户画像        • 上下文管理         │   │  │
│   │  └──────────────────────────────────────────────────────────┘   │  │
│   │                              │                                   │  │
│   │  ┌───────────────────────────┼───────────────────────────────┐   │  │
│   │  │                           │                               │   │  │
│   │  │  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐       │   │  │
│   │  │  │   Hybrid    │  │  Connectors │  │   File      │       │   │  │
│   │  │  │   Search    │  │             │  │ Processing  │       │   │  │
│   │  │  │ (RAG+Memory)│  │ Drive/Gmail │  │ PDF/Image   │       │   │  │
│   │  │  │             │  │ Notion/GitHub│ │ Video/Code  │       │   │  │
│   │  │  └─────────────┘  └─────────────┘  └─────────────┘       │   │  │
│   │  │                                                           │   │  │
│   │  └───────────────────────────────────────────────────────────┘   │  │
│   └─────────────────────────────────────────────────────────────────┘  │
│                                                                         │
│   ┌─────────────────────────────────────────────────────────────────┐  │
│   │                    Infrastructure                                │  │
│   │  ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌───────────┐ │  │
│   │  │  Cloudflare │  │ PostgreSQL  │  │  Vector    │  │  Better   │ │  │
│   │  │  Workers    │  │  Drizzle    │  │  Store     │  │  Auth     │ │  │
│   │  └─────────────┘ └─────────────┘ └─────────────┘ └───────────┘ │  │
│   └─────────────────────────────────────────────────────────────────┘  │
│                                                                         │
└─────────────────────────────────────────────────────────────────────────┘

2.2 仓库结构

supermemory/
├── apps/
│   ├── web/                    # Next.js Web 应用
│   ├── mcp/                    # MCP 服务器
│   ├── browser-extension/      # 浏览器扩展
│   ├── docs/                   # 文档站点
│   └── memory-graph-playground/
├── packages/
│   ├── tools/                  # SDK 集成 (AI SDK, OpenAI, Mastra)
│   ├── memory-graph/           # 可视化组件
│   ├── lib/                    # 共享工具库
│   ├── validation/             # API 验证模式
│   ├── hooks/                  # React Hooks
│   └── ai-sdk/                 # Vercel AI SDK 集成
├── turbo.json                  # Turbo 配置
├── bunfig.toml                 # Bun 配置
└── package.json

2.3 记忆 vs RAG

┌─────────────────────────────────────────────────────────────────────┐
│                    Memory is NOT RAG                                 │
├─────────────────────────────────────────────────────────────────────┤
│                                                                     │
│   RAG (检索增强生成)                                                │
│   ├── 检索文档块                                                    │
│   ├── 无状态：所有人得到相同结果                                     │
│   ├── 不理解时间变化                                                │
│   └── 例: 搜索 "部署文档" → 返回最新部署指南                         │
│                                                                     │
│   Memory (记忆)                                                     │
│   ├── 提取和追踪关于用户的事实                                      │
│   ├── 有状态：个性化结果                                            │
│   ├── 理解时间变化和矛盾                                            │
│   └── 例: "我刚搬到旧金山" 取代 "我住在纽约"                         │
│                                                                     │
│   Supermemory = RAG + Memory 组合                                   │
│   └── 同时返回文档 (RAG) + 用户偏好 (Memory)                        │
│                                                                     │
└─────────────────────────────────────────────────────────────────────┘

三、记忆引擎

3.1 核心操作

操作	描述
Fact Extraction	从对话中自动提取事实
Temporal Tracking	追踪知识的时间变化
Contradiction Resolution	检测并解决矛盾信息
Automatic Forgetting	自动遗忘过期信息

3.2 事实提取

import Supermemory from "supermemory";

const client = new Supermemory();

// 存储对话内容，自动提取事实
await client.add({
  content: "用户喜欢 TypeScript，偏好函数式编程模式",
  containerTag: "user_123",  // 用户标识
});

3.3 用户画像系统

用户画像自动分为两类：

类型	内容	示例
Static	永久事实	"喜欢 TypeScript", "使用 Vim", "偏好深色模式"
Dynamic	近期上下文	"正在做 API 集成", "调试速率限制"

// 获取用户画像 (~50ms 响应)
const { profile } = await client.profile({
  containerTag: "user_123"
});

console.log(profile.static);   // ["喜欢 TypeScript", "使用 Vim"]
console.log(profile.dynamic);  // ["正在做 API 集成"]

3.4 矛盾解决

时间线示例：

t1: 用户说 "我住在纽约"
    → 记忆: location = "纽约"

t2: 用户说 "我刚搬到旧金山"
    → 检测矛盾: 旧位置 vs 新位置
    → 更新: location = "旧金山"
    → 遗忘: "住在纽约" (过期信息)

去重逻辑：

export function deduplicateMemories(data: ProfileWithMemories): DeduplicatedMemories {
  // 优先级: Static > Dynamic > Search Results
  // 使用 Set 进行 O(1) 查重
}

3.5 自动遗忘

// 软删除过期的记忆
await client.memories.forget({
  containerTag: "user_123",
  memoryContent: "用户住在纽约",  // 现已过期
  reason: "用户搬到了旧金山"
});

四、混合搜索

4.1 RAG + Memory 组合

// 混合搜索模式
const results = await client.search.memories({
  q: "如何部署？",
  containerTag: "user_123",
  searchMode: "hybrid",  // 组合 RAG 文档 + Memory
});

// 返回:
// - 部署文档 (RAG)
// - 用户的部署偏好 (Memory)

4.2 相似度计算

// 余弦相似度计算
export const cosineSimilarity = (vectorA: number[], vectorB: number[]): number => {
  let dotProduct = 0;
  for (let i = 0; i < vectorA.length; i++) {
    dotProduct += vectorA[i] * vectorB[i];
  }
  return dotProduct;  // 归一化向量等于余弦相似度
};

// 语义相似度
export const calculateSemanticSimilarity = (
  doc1Embedding: number[] | null,
  doc2Embedding: number[] | null
): number => {
  const similarity = cosineSimilarity(doc1Embedding, doc2Embedding);
  return similarity >= 0 ? similarity : 0;
};

4.3 向量嵌入

使用 Cloudflare AI 生成
与文档和记忆一起存储
用于语义搜索

五、连接器

5.1 支持的集成

连接器	同步方式	功能
Google Drive	实时 Webhook	文档自动同步
Gmail	实时 Webhook	邮件处理
Notion	实时 Webhook	页面/数据库同步
OneDrive	实时 Webhook	文档同步
GitHub	实时 Webhook	仓库内容
Web Crawler	按需	URL 抓取

5.2 数据同步流程

┌─────────────────────────────────────────────────────────────────┐
│                    Content Processing Pipeline                   │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│   连接器触发 (每 4 小时 + Webhook)                               │
│              │                                                  │
│              ▼                                                  │
│   ┌─────────────────┐                                          │
│   │ 内容类型检测     │                                          │
│   └────────┬────────┘                                          │
│            │                                                    │
│            ▼                                                    │
│   ┌─────────────────┐                                          │
│   │ AI 摘要生成     │                                          │
│   └────────┬────────┘                                          │
│            │                                                    │
│            ▼                                                    │
│   ┌─────────────────┐                                          │
│   │ 自动标签        │                                          │
│   └────────┬────────┘                                          │
│            │                                                    │
│            ▼                                                    │
│   ┌─────────────────┐                                          │
│   │ 向量嵌入生成     │                                          │
│   └────────┬────────┘                                          │
│            │                                                    │
│            ▼                                                    │
│   ┌─────────────────┐                                          │
│   │ 语义分块        │                                          │
│   └────────┬────────┘                                          │
│            │                                                    │
│            ▼                                                    │
│   ┌─────────────────┐                                          │
│   │ 存入数据库      │                                          │
│   └─────────────────┘                                          │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

六、文件处理

6.1 多模态提取器

类型	处理方式
PDF	文本提取
图片	OCR 处理
视频	语音转录
代码	AST 感知分块

6.2 文件上传 API

// 上传文件
await client.documents.uploadFile({
  file: fileBlob,
  containerTags: ["project_123"],
  metadata: { title: "设计文档" }
});

// 列出文档
const docs = await client.documents.list({
  containerTag: "project_123"
});

七、API 设计

7.1 核心 API 方法

方法	用途
`client.add()`	存储内容 (文本、对话、URL、HTML)
`client.profile()`	用户画像 + 可选搜索
`client.search.memories()`	混合搜索
`client.search.documents()`	文档搜索
`client.documents.uploadFile()`	上传文件
`client.documents.list()`	列出文档
`client.settings.update()`	配置记忆提取和分块

7.2 完整使用示例

import Supermemory from "supermemory";

const client = new Supermemory({ apiKey: "sm_..." });

// 1. 存储对话
await client.add({
  content: "用户喜欢 TypeScript 和函数式编程",
  containerTag: "user_123",
});

// 2. 获取用户画像 + 相关记忆
const { profile, searchResults } = await client.profile({
  containerTag: "user_123",
  q: "用户偏好什么编程风格？",
});

// 3. 混合搜索
const results = await client.search.memories({
  q: "部署流程",
  containerTag: "user_123",
  searchMode: "hybrid",
});

// 4. 上传文档
await client.documents.uploadFile({
  file: pdfBlob,
  containerTags: ["project_abc"],
});

八、集成模式

8.1 Vercel AI SDK

import { withSupermemory } from "@supermemory/tools/ai-sdk";
import { openai } from "@ai-sdk/openai";

const modelWithMemory = withSupermemory(openai("gpt-4o"), "user_123", {
  mode: "full",
  addMemory: "always"
});

// 模式选项:
// - "profile": 获取用户画像，不过滤查询
// - "query": 基于用户消息搜索记忆
// - "full": 组合 profile + query 结果

8.2 OpenAI Agents SDK

import { withSupermemory } from "@supermemory/tools/openai";

const openaiWithMemory = withSupermemory("user-123", {
  conversationId: "conversation-456",
  mode: "full",
  addMemory: "always"
});

const completion = await openaiWithMemory.chat.completions.create({
  model: "gpt-4o-mini",
  messages: [{ role: "user", content: "你还记得什么？" }],
});

8.3 Mastra

import { Agent } from "@mastra/core/agent";
import { withSupermemory } from "@supermemory/tools/mastra";

const agent = new Agent(withSupermemory(
  { id: "assistant", name: "Assistant", model: openai("gpt-4o") },
  "user-123",
  { mode: "full", addMemory: "always" }
));

8.4 MCP Server

# 安装 MCP 服务器
npx -y install-mcp@latest https://mcp.supermemory.ai/mcp \
  --client claude --oauth=yes

MCP 工具列表：

工具	功能
`memory`	保存或遗忘信息
`recall`	搜索记忆
`whoAmI`	获取当前用户信息
`listProjects`	列出可用项目
`memory-graph`	可视化记忆图谱

九、MCP 服务器架构

┌─────────────────┐                    ┌──────────────────┐
│   MCP Client    │◄──── OAuth/API ───►│  Supermemory API │
│ (Claude, Cursor)│       Key          │ (api.supermemory.ai)
└────────┬────────┘                    └──────────────────┘
         │                                       ▲
         │ MCP Protocol                          │ Auth Validation
         ▼                                       │
┌─────────────────────────────────────────────────────────────────┐
│                   Supermemory MCP Server                         │
│                 (mcp.supermemory.ai/mcp)                        │
│  ┌─────────────────────────────────────────────────────────┐   │
│  │             Cloudflare Durable Object                    │   │
│  │  • 会话状态                                              │   │
│  │  • 客户端信息持久化                                       │   │
│  │  • MCP 协议处理                                          │   │
│  └─────────────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────────────┘

十、技术栈

10.1 运行时与框架

组件	技术
运行时	Bun
Web 框架	Next.js (Web), Hono (API/MCP)
语言	TypeScript
Monorepo	Turbo
包管理	Bun

10.2 后端基础设施

组件	技术
Serverless	Cloudflare Workers
状态	Durable Objects + SQLite
数据库	PostgreSQL + Drizzle ORM
向量存储	Cloudflare AI
KV 存储	Cloudflare KV

10.3 认证与安全

组件	技术
认证	Better Auth
API Keys	`sm_` 前缀
OAuth	支持 MCP

10.4 主要依赖

{
  "better-auth": "1.3.3",
  "drizzle-orm": "latest",
  "hono": "latest",
  "zod": "^3.25.76",
  "@tanstack/react-query": "^5.90.14",
  "@ai-sdk/openai": "latest",
  "@anthropic-ai/sdk": "latest"
}

十一、与其他框架对比

11.1 vs Mem0

维度	Supermemory	Mem0
开源	MIT	MIT
Stars	19.7K	25K+
基准测试	LongMemEval #1	有参与
连接器	6+	多种
MCP 支持	原生	需要适配
混合搜索	原生支持	分别处理

11.2 vs LangChain Memory

维度	Supermemory	LangChain Memory
类型	独立服务	框架组件
持久化	内置	需要配置
连接器	内置	需要集成
用户画像	自动维护	需要实现
API	简单统一	多种方式

11.3 vs Letta

维度	Supermemory	Letta
定位	记忆引擎	Agent 框架
核心功能	记忆管理	Agent 构建
集成	多框架	自带框架
部署	SaaS + 自托管	自托管

十二、使用场景

12.1 典型应用场景

场景	描述
AI 助手	让助手记住用户偏好和历史
客户服务	记住客户问题和解决方案
编程助手	记住项目上下文和编码风格
学习平台	追踪学习进度和偏好
健康应用	记住健康目标和偏好

12.2 最佳实践

// 1. 使用容器标签隔离数据
await client.add({
  content: "项目使用 React 18",
  containerTag: "project_abc",  // 项目级别
});

await client.add({
  content: "用户偏好深色模式",
  containerTag: "user_123",     // 用户级别
});

// 2. 定期清理过期记忆
await client.memories.forget({
  containerTag: "user_123",
  memoryContent: "旧的技术栈偏好",
  reason: "技术栈已更新"
});

// 3. 使用混合搜索获得最佳结果
const results = await client.search.memories({
  q: "部署配置",
  containerTag: "user_123",
  searchMode: "hybrid",
});

参考资源

GitHub: https://github.com/supermemoryai/supermemory
文档: https://supermemory.ai/docs
快速开始: https://supermemory.ai/docs/quickstart
Dashboard: https://console.supermemory.ai
Web App: https://app.supermemory.ai
Discord: https://supermemory.link/discord
Twitter: https://twitter.com/supermemory

报告生成时间：2026-03-27