Supermemory 深度实战：AI 时代的记忆引擎完全指南——从混合检索到知识图谱的架构全解析（2026）

摘要：Supermemory 作为 GitHub Trending 榜单上的黑马（24,537 ⭐，单日新增 677 stars），正在重新定义 AI Agent 的记忆层。本文将深入剖析 Supermemory 的五层架构（User Profiles、Memory Graph、Retrieval、Extractors、Connectors），通过完整的代码示例演示如何从零构建具备长期记忆的 AI Agent，并对比传统 RAG 方案的性能差异。无论你是构建个人助手、企业知识库，还是多模态数据处理管道，这篇指南都能让你掌握下一代 AI 记忆基础设施的核心技术。

目录

1. 为什么 AI 需要专用记忆系统？
2. Supermemory 架构深度解析
3. 快速上手：5 分钟接入 Memory API
4. 核心概念详解
   • 4.1 User Profiles：动态用户画像
   • 4.2 Memory Graph：时序感知的知识图谱
   • 4.3 Retrieval：混合检索与重排序
   • 4.4 Extractors：多模态内容提取
   • 4.5 Connectors：数据源无缝同步
5. 实战案例：构建个人 AI 助手
6. 生产级部署：性能优化与成本控制
7. 基准测试：LongMemEval 85.2% 的秘密
8. 与其他方案对比：为何选择 Supermemory
9. 总结与展望

为什么 AI 需要专用记忆系统？

1.1 传统 RAG 的困境

在 2026 年，大多数 AI 应用仍然采用传统的 RAG（Retrieval-Augmented Generation）架构：

用户提问 → 向量检索 → 拼接上下文 → LLM 生成 → 返回答案

这个流程存在三个致命缺陷：

问题 1：无状态对话
每次对话都是全新的开始。如果用户昨天说了"我叫张三，喜欢 Python"，今天的对话 AI 完全不记得。解决方案通常是把历史消息直接塞进上下文窗口，但这会导致：

• Token 消耗爆炸（每次都重复发送历史）
• 长对话后上下文溢出
• 无法跨会话持久化

问题 2：静态知识库
传统的向量数据库（Pinecone、Weaviate、Qdrant）只是"存储"，不具备"理解"能力：

• 无法处理知识更新（用户纠正了错误信息，向量库不会自动修正）
• 无法处理时序变化（"我上个月喜欢 Java，这个月转 Go 了"）
• 无法建立实体关系（"张三"和"Python"之间的关系是什么？）

问题 3：多模态割裂
PDF、网页、图片、音频各自为战，缺乏统一的处理管道。你可能需要：

• 用 PyPDF2 提取 PDF 文本
• 用 BeautifulSoup 爬取网页
• 用 Whisper 转写音频
• 分别向量化后存入不同的 Collection

结果：你的 AI 应用变成了"失忆症患者"——每次对话都像第一次见面。

1.2 Supermemory 的破局思路

Supermemory 的核心设计哲学是：记忆不是存储，而是理解。

它不是一个简单的向量数据库，而是一个完整的 Context Engineering Platform（上下文工程平台），提供五层抽象：

关键突破：

1. 实时演化：新知识自动合并/覆盖旧知识（解决"遗忘"问题）
2. 关系推理：不仅存储事实，还存储事实之间的关系（"张三 → 喜欢 → Python"）
3. 零重复计费：相同内容只计费一次（SM Token 去重机制）

Supermemory 架构深度解析

2.1 系统架构图

┌─────────────────────────────────────────────────────────────┐
│                     Your AI Application                      │
│  (Claude Code / Cursor / OpenClaw / Custom Agent)         │
└────────────────────┬────────────────────────────────────────┘
                     │ API Calls (REST / SDK / MCP)
                     ▼
┌─────────────────────────────────────────────────────────────┐
│                  Supermemory API Layer                       │
│  POST /v3/add  •  POST /v3/search  •  POST /v3/sync     │
└────────────────────┬────────────────────────────────────────┘
                     │
                     ▼
┌─────────────────────────────────────────────────────────────┐
│                   Five Core Layers                           │
├─────────────────────────────────────────────────────────────┤
│  1. Connectors (Data Ingestion)                            │
│     Notion │ Google Drive │ Gmail │ S3 │ GitHub │ Web     │
├─────────────────────────────────────────────────────────────┤
│  2. Extractors (Content Understanding)                      │
│     PDF Parser │ Web Scraper │ Image OCR │ Audio Transcriber│
├─────────────────────────────────────────────────────────────┤
│  3. Memory Graph (Knowledge Storage)                       │
│     Vector Store + Knowledge Graph + Temporal Tracker        │
├─────────────────────────────────────────────────────────────┤
│  4. User Profiles (Context Synthesis)                      │
│     Static Facts + Dynamic Episodic Memory                  │
├─────────────────────────────────────────────────────────────┤
│  5. Retrieval (Intelligent Query)                          │
│     Hybrid Search + Reranking + Context Injection           │
└─────────────────────────────────────────────────────────────┘
                     │
                     ▼
┌─────────────────────────────────────────────────────────────┐
│              Your LLM (Context-Augmented)                   │
│   "根据张三的偏好（Python/Go），推荐适合他的开源项目..."       │
└─────────────────────────────────────────────────────────────┘

2.2 数据流转详解

让我们追踪一条数据从进入到被检索的完整生命周期：

Phase 1：数据接入（Ingestion）

// 示例：添加一段对话记忆
await fetch('https://api.supermemory.ai/v3/add', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${API_KEY}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    containerTag: 'user_12345',  // 用户 ID（记忆容器）
    content: '用户喜欢用 Go 语言写微服务，特别关注性能优化',
    metadata: {
      type: 'preference',
      timestamp: Date.now(),
      source: 'conversation'
    }
  })
})

关键设计：

• containerTag 是记忆的"归属容器"，可以是用户 ID、项目 ID、组织 ID
• metadata 支持任意 JSON，用于后续过滤和排序

Phase 2：内容提取（Extraction）

Supermemory 会自动识别内容类型并选择合适的提取器：

示例：处理 PDF 简历

import requests

response = requests.post(
    'https://api.supermemory.ai/v3/add',
    headers={'Authorization': f'Bearer {API_KEY}'},
    json={
        'containerTag': 'candidate_001',
        'content': open('resume.pdf', 'rb'),  # 直接传文件
        'metadata': {
            'type': 'document',
            'format': 'pdf',
            'category': 'resume'
        }
    }
)

# Supermemory 自动提取：
# - 姓名、联系方式
# - 技能列表
# - 工作经历（时序）
# - 项目描述

Phase 3：知识图谱构建（Graph Construction）

这是 Supermemory 与传统向量数据库最大的区别所在。

传统向量库：

"张三喜欢Python" → embedding → [0.12, -0.34, ..., 0.56]
"张三会Go语言"  → embedding → [0.15, -0.31, ..., 0.52]

检索时只做向量相似度匹配，不知道两句话的关系。

Supermemory Memory Graph：

(Entity: 张三) --[likes]--> (Concept: Python)
(Entity: 张三) --[skilled_at]--> (Concept: Go)
(Concept: Python) --[related_to]--> (Concept: Django)

检索时可以：

1. 沿着关系链推理（"张三喜欢 Python，Python 常用框架是 Django，推荐 Django 项目"）
2. 处理矛盾信息（"张三之前喜欢 Java，现在转 Go 了" → 时序覆盖）
3. 自动遗忘（超过阈值 time window 的旧信息自动降权）

实现细节（基于官方文档和基准测试反向推导）：

// Memory Graph 的底层存储结构（概念模型）
interface MemoryNode {
  id: string;
  entity: string;          // 实体（如 "张三"）
  attribute: string;       // 属性（如 "language_preference"）
  value: any;              // 值（如 "Go"）
  timestamp: number;       // 创建时间
  confidence: number;      // 置信度（0-1）
  source: string;          // 来源（conversation / document / manual）
}

interface MemoryEdge {
  from: string;            // 源节点 ID
  to: string;              // 目标节点 ID
  relation: string;        // 关系类型（likes / skilled_at / related_to）
  weight: number;          // 关系强度
  temporal: {              // 时序信息
    start: number;
    end?: number;          // 如果是过时信息，有 end 时间
  };
}

关键算法：

1. 实体解析（Entity Resolution）："张三" 和 "张老师" 指向同一个实体
2. 关系抽取（Relation Extraction）：从文本中识别主语-谓词-宾语三元组
3. 时序融合（Temporal Fusion）：新旧信息冲突时，根据时间戳和置信度决定保留哪个
4. 自动遗忘（Forgetting Mechanism）：超过 TTL 或置信度低于阈值的信息自动降权

Phase 4：检索与重排序（Retrieval & Reranking）

// 搜索与 "Go 微服务性能优化" 相关的记忆
const result = await fetch('https://api.supermemory.ai/v3/search', {
  method: 'POST',
  headers: {...},
  body: JSON.stringify({
    containerTag: 'user_12345',
    query: 'Go 微服务性能优化',
    limit: 10,
    filters: {
      type: ['preference', 'project'],  // 只检索偏好和项目相关
      timeRange: {
        start: Date.now() - 30 * 24 * 3600 * 1000,  // 最近 30 天
        end: Date.now()
      }
    },
    reranking: {
      enabled: true,
      strategy: 'context_aware',  // 考虑对话上下文的重排序
    }
  })
})

混合检索策略：

1. 向量检索（Dense Retrieval）：query embedding → ANN 搜索（HNSW 算法）
2. 关键词检索（Sparse Retrieval）：BM25 全文索引
3. 图谱遍历（Graph Traversal）：从初始结果出发，沿关系链扩展
4. 重排序（Reranking）：用 Cross-Encoder 对 Top-K 结果重新打分

性能数据（来自 LongMemEval 基准测试）：

• P50 延迟：< 300ms
• P99 延迟：< 800ms
• 准确率：85.2%（SOTA）

快速上手：5 分钟接入 Memory API

3.1 注册与获取 API Key

1. 访问 https://console.supermemory.ai
2. 注册账号（支持 GitHub / Google 登录）
3. 在 Dashboard 创建 API Key（免费版每月 $5 额度）

3.2 TypeScript SDK 安装

npm install @supermemory/sdk

3.3 第一个完整示例

import { Supermemory } from '@supermemory/sdk';

const sm = new Supermemory({
  apiKey: process.env.SUPERMEMORY_API_KEY!
});

// ========== 1. 添加记忆 ==========
await sm.documents.add({
  containerTag: 'user_alice',
  content: 'Alice 是一名前端工程师，熟悉 React 和 TypeScript，最近在学习 WebGL',
  metadata: {
    type: 'user_profile',
    source: 'onboarding'
  }
});

await sm.documents.add({
  containerTag: 'user_alice',
  content: 'Alice 提到她喜欢可视化项目，特别是 3D 图形相关',
  metadata: {
    type: 'preference',
    source: 'conversation',
    timestamp: Date.now()
  }
});

// ========== 2. 搜索记忆 ==========
const results = await sm.search.query({
  containerTag: 'user_alice',
  query: '适合 Alice 的开源项目',
  limit: 5,
  includeProfile: true  // 自动合并用户画像
});

console.log(results);

// 输出：
// {
//   "memories": [
//     {
//       "content": "Alice 是一名前端工程师，熟悉 React 和 TypeScript",
//       "score": 0.92,
//       "metadata": { "type": "user_profile", ... }
//     },
//     {
//       "content": "Alice 提到她喜欢可视化项目，特别是 3D 图形相关",
//       "score": 0.87,
//       "metadata": { "type": "preference", ... }
//     }
//   ],
//   "profile": {
//       "skills": ["React", "TypeScript", "WebGL"],
//       "interests": ["3D Graphics", "Visualization"],
//       "role": "Frontend Engineer"
//   }
// }

// ========== 3. 构建上下文感知的 LLM 调用 ==========
const context = results.memories.map(m => m.content).join('\n');
const prompt = `
基于以下用户背景信息：
${context}

请推荐 5 个适合 Alice 的 GitHub 开源项目，要求：
1. 与前端/可视化相关
2. 适合她的技能水平
3. 有活跃社区
`;

// 调用你的 LLM（OpenAI / Anthropic / 本地模型）
const recommendation = await llm.generate(prompt);
console.log(recommendation);

核心概念详解

4.1 User Profiles：动态用户画像

传统的用户画像系统是静态的：

-- 传统方案：需要手动维护用户表
CREATE TABLE user_profiles (
  user_id VARCHAR(255),
  skills TEXT[],
  interests TEXT[],
  updated_at TIMESTAMP
);

-- 每次对话后都要手动 UPDATE
UPDATE user_profiles
SET skills = array_append(skills, 'WebGL')
WHERE user_id = 'alice';

问题：

• 需要手动编写 extraction 逻辑
• 无法处理时序变化（"Alice 去年会 Vue，今年转 React 了"）
• 无法自动遗忘过时信息

Supermemory 方案：全自动、时序感知、支持遗忘

// 无需手动维护，Supermemory 自动构建用户画像
// 每次 add() 调用都会触发 Profile Update 算法

// 示例：连续对话中，Supermemory 自动提取和更新画像
await sm.documents.add({
  containerTag: 'user_alice',
  content: '我之前用 Vue，但现在公司要求用 React',
  metadata: { type: 'conversation', timestamp: Date.now() }
});

// Supermemory 自动处理：
// 1. 提取事实：{ skill: 'Vue', status: 'previously_used' }
// 2. 提取事实：{ skill: 'React', status: 'currently_using' }
// 3. 更新画像：
//    - skills: ['React', 'TypeScript', 'WebGL']
//    - previously_used: ['Vue']
//    - current_focus: 'React'

User Profile 的数据结构（通过 API 获取）：

const profile = await sm.profiles.get({ containerTag: 'user_alice' });

// 返回：
{
  "static": {
    // 永不遗忘的核心事实
    "name": "Alice",
    "role": "Frontend Engineer",
    "location": "Shanghai"
  },
  "dynamic": {
    // 会随时间演化的事实
    "skills": ["React", "TypeScript", "WebGL"],
    "current_projects": ["3D Dashboard"],
    "learning_goals": ["WebGPU", "Rust"]
  },
  "episodic": {
    // 最近 N 次对话的摘要（滑动窗口）
    "recent_topics": ["WebGL optimization", "Three.js camera control"],
    "last_interaction": "2026-06-02T19:30:00Z"
  },
  "preferences": {
    // 从行为中推断的偏好
    "ui_framework": "React",
    "state_management": "Zustand",
    "build_tool": "Vite"
  }
}

配置静态 vs 动态字段：

// 通过 API 配置哪些字段是静态的（永久记忆）
await sm.profiles.configure({
  containerTag: 'user_alice',
  staticFields: ['name', 'role', 'location'],  // 永不遗忘
  dynamicFields: ['skills', 'projects', 'preferences'],  // 可演化
  episodicWindow: 10  // 保留最近 10 次对话
});

4.2 Memory Graph：时序感知的知识图谱

这是 Supermemory 的杀手级特性。

4.2.1 为什么需要图谱？

向量检索的局限：

// 用户问："张三最近在学什么？"
// 向量检索会返回：
"张三喜欢 Python"           // 相似度 0.89
"张三在做机器学习项目"     // 相似度 0.85
"Python 适合机器学习"      // 相似度 0.82

// 问题：无法知道哪条信息是最新的！

图谱检索的优势：

(张三) --[learning]--> (Python) [2026-01 ~ 2026-03]
(张三) --[learning]--> (Go)    [2026-04 ~ present]
(张三) --[project]--> (ML项目) [2026-02 ~ 2026-03]

查询："张三最近在学什么？"
图谱遍历：从"张三"节点出发 → 找 learning 边 → 按 timestamp 排序 → 返回 "Go"

4.2.2 图谱构建实战

// 添加多条记忆，Supermemory 自动构建图谱
await sm.documents.add({
  containerTag: 'user_zhangsan',
  content: '张三是一名后端工程师，目前在使用 Go 语言',
  metadata: { type: 'profile' }
});

await sm.documents.add({
  containerTag: 'user_zhangsan',
  content: '张三之前用 Python 做数据分析，但现在转 Go 了',
  metadata: { type: 'preference', timestamp: Date.now() }
});

await sm.documents.add({
  containerTag: 'user_zhangsan',
  content: '张三在公司负责微服务架构，用 gRPC 做 RPC 通信',
  metadata: { type: 'project' }
});

// Supermemory 自动构建的图谱（概念视图）：
//
// (张三) --[role]--> (后端工程师)
// (张三) --[uses]--> (Go) [current, since 2026-04]
// (张三) --[used_to_use]--> (Python) [past, until 2026-03]
// (张三) --[responsible_for]--> (微服务架构)
// (微服务架构) --[uses]--> (gRPC)
// (Go) --[common_frameworks]--> (Gin, gRPC)

4.2.3 图谱查询

// 查询 1：沿着关系链推理
const result1 = await sm.search.query({
  containerTag: 'user_zhangsan',
  query: '张三需要学习哪些 Go 框架？',
  useGraph: true,  // 启用图谱遍历
  maxHops: 2       // 最多跳 2 步
});

// 检索过程：
// 1. 找到 (张三) --[uses]--> (Go)
// 2. 从 (Go) 出发，找 --[common_frameworks]--> (Gin, gRPC)
// 3. 返回："推荐学习 Gin（HTTP）和 gRPC（RPC）"

// 查询 2：处理时序问题
const result2 = await sm.search.query({
  containerTag: 'user_zhangsan',
  query: '张三最近在用什么语言？',
  useGraph: true,
  temporalFilter: 'recent'  // 只返回最新信息
});

// 检索过程：
// 1. 找到 (张三) --[uses]--> (Go) [2026-04 ~ present]
// 2. 找到 (张三) --[used_to_use]--> (Python) [2026-01 ~ 2026-03]
// 3. 时序过滤，只保留 present 的关系
// 4. 返回："Go"

4.2.4 知识更新与冲突解决

// 场景：用户纠正了之前的信息
await sm.documents.add({
  containerTag: 'user_zhangsan',
  content: '我之前说错了，我现在主要用 Rust，不是 Go',
  metadata: { type: 'correction', timestamp: Date.now() }
});

// Supermemory 自动处理冲突：
// 1. 识别矛盾：新信息 (uses: Rust) 与旧信息 (uses: Go) 冲突
// 2. 时序判断：新信息 timestamp 更晚 → 置信度更高
// 3. 图谱更新：
//    - (张三) --[uses]--> (Go) 的 temporal.end = now
//    - (张三) --[uses]--> (Rust) 的 temporal.start = now
// 4. 以后查询 "张三用什么语言" → 返回 "Rust"

冲突解决策略（可配置）：

await sm.configure({
  containerTag: 'user_zhangsan',
  conflictResolution: {
    strategy: 'temporal',  // 默认：相信最新信息
    // 可选：'confidence'（相信置信度高的）
    // 可选：'vote'（多个来源投票决定）
    confidenceThreshold: 0.8
  }
});

4.3 Retrieval：混合检索与重排序

4.3.1 为什么需要混合检索？

单一向量检索的问题：

• 语义漂移：query "如何优化 Go 性能" 可能返回 "Go 性能很差"（负样本）
• 关键词缺失：无法精确匹配专业术语（"gRPC"、"eBPF"）
• 缺乏可解释性：不知道为什么返回这条结果

单一关键词检索的问题：

• 同义词缺失：搜 "AI 助手" 找不到 "智能体"
• 语义理解差：搜 "微服务架构" 找不到 "microservices"

Supermemory 混合检索：向量 + 关键词 + 图谱三者融合

const results = await sm.search.query({
  containerTag: 'user_zhangsan',
  query: 'Go 微服务性能优化',
  strategies: {
    vector: {
      enabled: true,
      weight: 0.5,
      model: 'text-embedding-3-small'  // 可配置 embedding 模型
    },
    keyword: {
      enabled: true,
      weight: 0.3,
      algorithm: 'BM25'
    },
    graph: {
      enabled: true,
      weight: 0.2,
      maxHops: 2
    }
  },
  reranking: {
    enabled: true,
    model: 'cross-encoder/ms-marco-MiniLM-L-6-v2',
    topK: 20  // 先检索 20 条，再重排序取 Top 5
  }
});

4.3.2 重排序详解

问题：混合检索返回的 Top-K 结果仍然可能不相关。

示例：

Query: "Go 微服务性能优化"

初始检索结果（未重排序）：
1. "Go 语言基础教程"                    ← 不相关，但 "Go" 关键词匹配
2. "微服务架构设计"                      ← 部分相关
3. "用 pprof 分析 Go 微服务性能瓶颈"    ← 高度相关
4. "Python 性能优化技巧"                 ← 不相关

重排序（Reranking）：
用更精确的 Cross-Encoder 对初始结果重新打分：

# 伪代码
from sentence_transformers import CrossEncoder

reranker = CrossEncoder('cross-encoder/ms-marco-MiniLM-L-6-v2')

query = "Go 微服务性能优化"
candidates = [
    "Go 语言基础教程",
    "微服务架构设计",
    "用 pprof 分析 Go 微服务性能瓶颈",
    "Python 性能优化技巧"
]

# Cross-Encoder 直接计算 query-document 相关性得分
scores = reranker.predict([(query, doc) for doc in candidates])
# 输出：[0.23, 0.67, 0.94, 0.12]

# 按分数重新排序
reranked = sorted(zip(candidates, scores), key=lambda x: x[1], reverse=True)
# 输出：
# 1. "用 pprof 分析 Go 微服务性能瓶颈" (0.94)
# 2. "微服务架构设计"                   (0.67)
# 3. "Go 语言基础教程"                   (0.23)
# 4. "Python 性能优化技巧"               (0.12)

Supermemory 的重排序策略（可配置）：

reranking: {
  enabled: true,
  strategy: 'context_aware',  // 考虑对话上下文
  // 可选：'simple'（仅用 Cross-Encoder）
  // 可选：'diversified'（保证结果多样性）
  topK: 20,
  finalLimit: 5
}

4.4 Extractors：多模态内容提取

4.4.1 支持的格式

4.4.2 PDF 提取实战

import fs from 'fs';

// 上传 PDF 简历
const pdfBuffer = fs.readFileSync('./alice_resume.pdf');

await sm.documents.add({
  containerTag: 'candidate_alice',
  content: pdfBuffer,
  contentType: 'application/pdf',
  metadata: {
    type: 'resume',
    candidateName: 'Alice',
    position: 'Frontend Engineer'
  }
});

// Supermemory 自动提取结构化信息：
const extracted = await sm.documents.getExtracted({
  containerTag: 'candidate_alice',
  documentId: 'doc_12345'
});

console.log(extracted);
// 输出：
// {
//   "name": "Alice Johnson",
//   "email": "alice@example.com",
//   "skills": ["React", "TypeScript", "WebGL", "Three.js"],
//   "experience": [
//     {
//       "company": "TechCorp",
//       "role": "Senior Frontend Engineer",
//       "duration": "2023-2025",
//       "highlights": ["Led migration to React 18", "Improved perf by 40%"]
//     }
//   ],
//   "education": "BS in Computer Science, Stanford University",
//   "projects": [
//     {
//       "name": "3D Data Visualization Dashboard",
//       "tech_stack": ["React", "Three.js", "WebGL"],
//       "description": "Built an interactive 3D dashboard..."
//     }
//   ]
// }

4.4.3 音频转写实战

// 上传会议录音
const audioBuffer = fs.readFileSync('./meeting_20260602.mp3');

await sm.documents.add({
  containerTag: 'meeting_notes',
  content: audioBuffer,
  contentType: 'audio/mpeg',
  metadata: {
    type: 'meeting',
    participants: ['Alice', 'Bob', 'Charlie'],
    date: '2026-06-02'
  }
});

// 获取转写结果 + 自动提取行动项
const result = await sm.documents.getExtracted({
  containerTag: 'meeting_notes',
  documentId: 'doc_67890'
});

console.log(result);
// 输出：
// {
//   "transcript": "Alice: 我们下周三前完成性能优化...\nBob: 我负责数据库索引...",
//   "summary": "讨论了性能优化方案，分配了任务",
//   "action_items": [
//     { "who": "Alice", "what": "完成 API 性能优化", "deadline": "2026-06-11" },
//     { "who": "Bob", "what": "添加数据库索引", "deadline": "2026-06-09" }
//   ],
//   "decisions": ["采用 Redis 做缓存层", "使用 pprof 做性能分析"]
// }

4.5 Connectors：数据源无缝同步

4.5.1 支持的 Connector

4.5.2 Notion 同步实战

// 1. 授权 Notion（OAuth2）
await sm.connectors.authorize({
  containerTag: 'user_alice',
  connector: 'notion',
  redirectUri: 'https://yourapp.com/callback'
});

// 2. 配置同步规则
await sm.connectors.configure({
  containerTag: 'user_alice',
  connector: 'notion',
  config: {
    databases: ['Pages', 'Projects', 'Daily Notes'],  // 同步哪些数据库
    propertiesToIndex: ['title', 'content', 'tags'],   // 索引哪些属性
    syncInterval: 600                                  // 每 10 分钟同步一次
  }
});

// 3. 启动同步
await sm.connectors.sync({
  containerTag: 'user_alice',
  connector: 'notion'
});

// 4. 实时监控同步状态
setInterval(async () => {
  const status = await sm.connectors.getStatus({
    containerTag: 'user_alice',
    connector: 'notion'
  });
  console.log(status);
  // 输出：
  // {
  //   "lastSync": "2026-06-02T19:30:00Z",
  //   "syncedItems": 142,
  //   "pendingItems": 3,
  //   "errors": []
  // }
}, 60000);

4.5.3 Gmail 同步实战

// 同步邮件到 Supermemory，自动提取重要信息
await sm.connectors.authorize({
  containerTag: 'user_alice',
  connector: 'gmail',
  scopes: ['https://www.googleapis.com/auth/gmail.readonly']
});

await sm.connectors.configure({
  containerTag: 'user_alice',
  connector: 'gmail',
  config: {
    filters: {
      // 只同步重要邮件
      labels: ['IMPORTANT', 'CATEGORY_PERSONAL'],
      excludeLabels: ['CATEGORY_PROMOTIONS', 'SPAM'],
      // 只同步最近 30 天的邮件
      after: Date.now() - 30 * 24 * 3600 * 1000
    },
    extractionRules: {
      // 自动提取
      extractContacts: true,      // 联系人信息
      extractEvents: true,        // 会议/事件
      extractActionItems: true,   // 行动项
      summarizeLongEmails: true  // 长邮件自动摘要
    }
  }
});

// 同步完成后，可以搜索邮件内容
const emails = await sm.search.query({
  containerTag: 'user_alice',
  query: 'Alice 上周关于项目进度的邮件',
  filters: { source: 'gmail' }
});

实战案例：构建个人 AI 助手

5.1 需求分析

我们要构建一个个人 AI 助手，具备以下能力：

1. 记住用户偏好（编程语言、框架、工具）
2. 记住对话历史（跨会话持久化）
3. 访问个人知识库（Notion 笔记、GitHub 项目、本地文档）
4. 主动提醒（基于日历和邮件）

5.2 完整实现

Step 1：初始化 Supermemory

// file: src/memory.ts
import { Supermemory } from '@supermemory/sdk';

export const memory = new Supermemory({
  apiKey: process.env.SUPERMEMORY_API_KEY!
});

// 配置用户容器
export async function initUserMemory(userId: string) {
  await memory.profiles.configure({
    containerTag: userId,
    staticFields: ['name', 'role', 'location'],
    dynamicFields: ['skills', 'projects', 'preferences'],
    episodicWindow: 20  // 记住最近 20 次对话
  });
}

Step 2：集成到 LLM 调用

// file: src/assistant.ts
import { memory } from './memory';
import OpenAI from 'openai';

const openai = new OpenAI({ apiKey: process.env.OPENAI_API_KEY });

export async function chat(userId: string, userMessage: string) {
  // 1. 存储用户消息到 Supermemory
  await memory.documents.add({
    containerTag: userId,
    content: userMessage,
    metadata: {
      type: 'conversation',
      role: 'user',
      timestamp: Date.now()
    }
  });

  // 2. 检索相关记忆
  const relevantMemories = await memory.search.query({
    containerTag: userId,
    query: userMessage,
    limit: 5,
    includeProfile: true
  });

  // 3. 构建上下文增强的 Prompt
  const context = buildContext(relevantMemories);
  const prompt = `
${context}

用户消息：${userMessage}

请基于以上背景信息回复用户。如果涉及到用户的偏好或历史，要自然地引用。
`;

  // 4. 调用 LLM
  const response = await openai.chat.completions.create({
    model: 'gpt-4o',
    messages: [
      { role: 'system', content: prompt }
    ]
  });

  const assistantReply = response.choices[0].message.content;

  // 5. 存储助手回复到 Supermemory
  await memory.documents.add({
    containerTag: userId,
    content: assistantReply!,
    metadata: {
      type: 'conversation',
      role: 'assistant',
      timestamp: Date.now()
    }
  });

  return assistantReply;
}

function buildContext(searchResult: any) {
  const profile = searchResult.profile;
  const memories = searchResult.memories;

  let context = '## 用户背景\n';
  if (profile) {
    context += `姓名：${profile.static.name}\n`;
    context += `职业：${profile.static.role}\n`;
    context += `技能：${profile.dynamic.skills.join(', ')}\n`;
    context += `当前项目：${profile.dynamic.current_projects.join(', ')}\n`;
  }

  context += '\n## 相关记忆\n';
  for (const mem of memories) {
    context += `- ${mem.content}\n`;
  }

  return context;
}

Step 3：接入 Notion 和 GitHub

// file: src/connectors.ts
import { memory } from './memory';

export async function setupConnectors(userId: string) {
  // Notion
  await memory.connectors.authorize({
    containerTag: userId,
    connector: 'notion',
    redirectUri: 'http://localhost:3000/callback'
  });

  await memory.connectors.configure({
    containerTag: userId,
    connector: 'notion',
    config: {
      databases: ['Daily Notes', 'Project Docs', 'Learning Log'],
      syncInterval: 600
    }
  });

  // GitHub
  await memory.connectors.authorize({
    containerTag: userId,
    connector: 'github',
    redirectUri: 'http://localhost:3000/callback'
  });

  await memory.connectors.configure({
    containerTag: userId,
    connector: 'github',
    config: {
      repositories: ['my-project', 'learning-notes'],
      events: ['push', 'issues', 'pull_request'],
      syncInterval: 300
    }
  });

  // 启动同步
  await memory.connectors.sync({ containerTag: userId, connector: 'notion' });
  await memory.connectors.sync({ containerTag: userId, connector: 'github' });
}

Step 4：主动提醒功能

// file: src/reminder.ts
import { memory } from './memory';

export async function checkReminders(userId: string) {
  // 从 Gmail 和日历中提取待办事项
  const actionItems = await memory.search.query({
    containerTag: userId,
    query: '待办事项 截止日期',
    filters: {
      type: 'action_item',
      status: 'pending'
    }
  });

  const now = Date.now();
  const reminders = [];

  for (const item of actionItems.memories) {
    const deadline = item.metadata.deadline;
    if (deadline - now < 24 * 3600 * 1000) {  // 24 小时内到期
      reminders.push({
        task: item.content,
        deadline: new Date(deadline).toLocaleString()
      });
    }
  }

  return reminders;
}

// 定时检查（每小时）
setInterval(async () => {
  const reminders = await checkReminders('user_alice');
  if (reminders.length > 0) {
    console.log('⏰ 提醒：');
    reminders.forEach(r => {
      console.log(`- ${r.task} (截止：${r.deadline})`);
    });
  }
}, 3600000);

5.3 完整对话示例

用户：推荐一个适合我的开源项目

助手：（自动检索到用户背景：前端工程师，熟悉 React/TypeScript，喜欢可视化）
      基于你的背景，推荐以下项目：
      1. react-three-fiber - React + Three.js 绑定
      2. D3.js - 数据可视化库
      3. Deck.gl - Uber 的开源可视化框架

用户：我之前是不是说过我在学 WebGL？

助手：（检索对话历史）
      是的，你在 2026-05-15 的对话中提到"最近在学习 WebGL，
      特别是阴影计算和光照模型"。

用户：把这些信息整理成学习笔记，存到 Notion

助手：（自动调用 Notion Connector）
      已为你创建 Notion 页面 "WebGL 学习笔记"，包含：
      - 你的学习进度
      - 推荐资源
      - 代码示例

生产级部署：性能优化与成本控制

6.1 成本结构分析

Supermemory 的计费单位是 SM Token（Supermemory Token），与 LLM 的 Token 不同：

成本优化策略：

策略 1：利用去重机制

// ❌ 错误做法：每次对话都重新上传知识库
for (const conversation of conversationHistory) {
  await sm.documents.add({
    containerTag: 'user_123',
    content: companyKnowledgeBase  // 每次都传相同的知识库
  });
}
// 结果：被计费 100 次

// ✅ 正确做法：只上传一次，后续对话自动引用
await sm.documents.add({
  containerTag: 'user_123',
  content: companyKnowledgeBase
});
// 结果：只计费 1 次，后续自动去重

策略 2：使用 Rich Mode 时注意成本

// ❌ 错误做法：把所有 PDF 都存为 rich mode
await sm.documents.add({
  containerTag: 'user_123',
  content: pdfBuffer,
  contentType: 'application/pdf',
  extractionMode: 'rich'  // 提取图片、表格、布局 → 贵 2 倍
});

// ✅ 正确做法：根据需求选择模式
if (pdfContainsChartsOrTables) {
  extractionMode = 'rich';  // 需要图表信息
} else {
  extractionMode = 'text';  // 只需要文字
}

策略 3：限制检索数量

// ❌ 错误做法：检索太多结果
const results = await sm.search.query({
  containerTag: 'user_123',
  query: '...',
  limit: 100  // 检索 100 条 → 重排序成本高
});

// ✅ 正确做法：先检索少量，重排序后取 Top K
const results = await sm.search.query({
  containerTag: 'user_123',
  query: '...',
  limit: 20,     // 检索 20 条
  reranking: {
    enabled: true,
    finalLimit: 5  // 重排序后只返回 Top 5
  }
});

6.2 性能优化

优化 1：使用批量 API

// ❌ 错误做法：逐条上传
for (const doc of documents) {
  await sm.documents.add({ ... });
}
// 100 条文档 = 100 次网络请求

// ✅ 正确做法：批量上传
await sm.documents.batchAdd({
  containerTag: 'user_123',
  documents: documents.map(doc => ({
    content: doc.content,
    metadata: doc.metadata
  }))
});
// 100 条文档 = 1 次网络请求

优化 2：启用压缩

// 对于大文本，启用压缩（节省 60-95% Token）
await sm.documents.add({
  containerTag: 'user_123',
  content: largeText,
  compression: 'headroom',  // 使用 Headroom 算法压缩
  // 可选：'gzip' / 'zstd'
});

优化 3：缓存常见查询

const queryCache = new LRUCache<string, any>({ max: 100 });

async function cachedSearch(query: string) {
  if (queryCache.has(query)) {
    return queryCache.get(query);
  }

  const result = await sm.search.query({ /* ... */ });
  queryCache.set(query, result);
  return result;
}

6.3 高可用部署

方案 1：多区域部署（Enterprise 版）

// 配置多个 Region 作为备份
const sm = new Supermemory({
  apiKey: process.env.SUPERMEMORY_API_KEY!,
  regions: ['us-east-1', 'eu-west-1', 'ap-east-1'],
  failover: true  // 自动故障转移
});

方案 2：本地缓存层

// 在本地 Redis 中缓存热点数据
import Redis from 'ioredis';

const redis = new Redis();

async function getMemoryWithCache(containerTag: string, query: string) {
  const cacheKey = `sm:${containerTag}:${query}`;
  const cached = await redis.get(cacheKey);
  
  if (cached) {
    return JSON.parse(cached);
  }

  const result = await sm.search.query({ containerTag, query });
  await redis.set(cacheKey, JSON.stringify(result), 'EX', 3600);  // 缓存 1 小时
  return result;
}

基准测试：LongMemEval 85.2% 的秘密

7.1 什么是 LongMemEval？

LongMemEval 是评估 AI Agent 长期记忆能力的基准测试，包含：

• 500 轮对话
• 跨会话记忆（相隔数天甚至数周）
• 时序推理（"我之前说的 X，现在改成了 Y"）

测试维度：

1. 单轮事实回忆（Single-hop Fact Retrieval）
2. 多跳推理（Multi-hop Reasoning）
3. 时序理解（Temporal Understanding）
4. 知识更新（Knowledge Update）

7.2 Supermemory 的技术优势

优势 1：Memory Graph 的多跳推理

测试样例：

Turn 10:  用户说 "我叫张三"
Turn 50:  用户说 "我喜欢用 Go 语言"
Turn 100: 用户说 "我在公司负责微服务架构"
Turn 400: 问 "张三需要学什么框架？"

传统 RAG：检索到 "张三喜欢 Go" → 无法推荐具体框架
Supermemory：
  1. (张三) --[likes]--> (Go)
  2. (Go) --[common_frameworks]--> (Gin, gRPC)
  3. 返回："推荐 Gin（HTTP）和 gRPC（RPC）"

优势 2：时序感知

测试样例：

Turn 20: 用户说 "我用 Python"
Turn 200: 用户说 "我改学 Go 了"
Turn 500: 问 "张三用什么语言？"

传统 RAG：可能返回 "Python"（因为向量相似度高）
Supermemory：
  1. 识别到矛盾信息
  2. 检查时序：(Python) [Turn 20] vs (Go) [Turn 200]
  3. 返回："Go"（更晚的信息置信度更高）

优势 3：自动遗忘

测试样例：

Turn 10: 用户说 "我正在学 React"
Turn 100: 用户说 "我已经精通 React 了"
Turn 200: 用户说 "我现在在学 Vue"
Turn 500: 问 "张三的技能有哪些？"

Supermemory：
  1. (张三) --[learning]--> (React) [Turn 10, status: outdated]
  2. (张三) --[skilled_at]--> (React) [Turn 100]
  3. (张三) --[learning]--> (Vue) [Turn 200]
  4. 返回："React（精通）、Vue（学习中）"

7.3 与其他方案对比

与其他方案对比：为何选择 Supermemory？

8.1 Supermemory vs LangChain Memory

选择建议：

• 如果你已经在用 LangChain，可以用 SupermemoryChatMessageHistory 替代原生的 Memory
• 如果是新项目，直接用 Supermemory SDK

8.2 Supermemory vs Mem0

选择建议：

• 如果需要完整的数据管道（Notion/Gmail/S3 同步），选 Supermemory
• 如果需要自托管，选 Mem0

8.3 Supermemory vs 传统向量数据库（Pinecone/Weaviate）

选择建议：

• 如果是 AI Agent / 对话系统，选 Supermemory
• 如果是推荐系统 / 图片检索，选 Pinecone

总结与展望

9.1 核心要点回顾

1. Supermemory 不是向量数据库，而是完整的上下文工程平台

   • 五层抽象：Connectors → Extractors → Memory Graph → User Profiles → Retrieval
   • 开箱即用的多模态处理和数据源同步

2. Memory Graph 是核心竞争力

   • 支持多跳推理、时序感知、自动遗忘
   • LongMemEval 基准测试 85.2% SOTA

3. 成本优化关键：去重 + 压缩

   • 相同内容只计费一次（SM Token 去重）
   • 配合 Headroom 压缩可节省 60-95% Token

4. 易于集成

   • REST API / TypeScript SDK / Python SDK / MCP Server
   • 兼容 OpenAI / Anthropic / LangChain / Vercel AI SDK

9.2 实战建议

适合使用 Supermemory 的场景：

• ✅ 个人 AI 助手（记忆用户偏好和对话历史）
• ✅ 企业知识库（自动同步 Notion/Google Drive）
• ✅ 客服机器人（记住客户的历史问题）
• ✅ 代码助手（索引 GitHub 项目和文档）

不适合的场景：

• ❌ 纯图片/视频检索（用专门的向量数据库）
• ❌ 对成本极度敏感的原型项目（先用开源方案验证）

9.3 未来展望

根据 Supermemory 的 Roadmap 和研究论文，未来可能的发展方向：

1. 更强大的推理能力

   • 从"记忆"到"思考"：自动从记忆中总结规律
   • 示例：从用户的编程偏好中推断最适合他的代码风格

2. 多 Agent 协作

   • 多个 AI Agent 共享同一个记忆池
   • 示例：代码助手 Agent 和 DevOps Agent 共享项目上下文

3. 边缘部署

   • 在本地设备（手机/笔记本）上运行轻量级 Memory Engine
   • 保护隐私，零延迟

参考资源

• 官方文档：https://docs.supermemory.ai
• GitHub：https://github.com/supermemoryai/supermemory
• API 参考：https://docs.supermemory.ai/api-reference
• 研究论文：https://supermemory.ai/research
• 基准测试：https://git.new/membench
• 定价：https://supermemory.ai/pricing

作者简介：程序员茄子，全栈工程师，关注 AI Agent 和开发者工具。博客：程序员茄子

文章标签：AI Agent | Supermemory | 记忆引擎 | RAG | 知识图谱 | TypeScript | 生产实战

发布时间：2026-06-03
字数：约 18,500 字

免责声明：本文基于公开文档和基准测试数据撰写，部分实现细节为根据架构设计反向推导，具体实现以官方代码为准。Supermemory 是闭源商业产品，本文仅做技术分享，不构成商业推荐。