Supermemory - 完整学习教程

**教程级别：** 从零到一
**预计学习时间：** 4-6 小时
**前置知识：** LLM 基础概念、API 集成经验、TypeScript 或 Python 基础

Supermemory - 完整学习教程

教程级别： 从零到一 预计学习时间： 4-6 小时 前置知识： LLM 基础概念、API 集成经验、TypeScript 或 Python 基础

环境搭建指南

系统要求

  • 操作系统：macOS、Linux 或 Windows
  • 运行时/依赖版本：Node.js >= 18 或 Python >= 3.9
  • API Key：Supermemory API Key（从 supermemory.ai 获取）或自托管实例

安装步骤

# 方式一：通过 npm 安装 SDK
npm install supermemory

# 方式二：通过 pip 安装 Python SDK
pip install supermemory

# 方式三：自托管（Docker）
git clone https://github.com/supermemoryai/supermemory.git
cd supermemory
docker compose up -d

验证安装

# 设置 API Key
export SUPERMEMORY_API_KEY=your-api-key

# 运行基本测试
# TypeScript
npx ts-node -e "
import { Supermemory } from 'supermemory';
const sm = new Supermemory();
console.log('Supermemory initialized:', sm !== null);
"

第一部分：入门篇

1.1 理解 AI 记忆的基本概念

概念讲解：

LLM 是无状态的——每次新对话都是全新的。Supermemory 通过三个核心能力解决这个问题：

  1. 记忆提取（Extract）：从对话中自动识别值得记住的信息
  2. 记忆存储（Store）：将信息向量化并持久化存储
  3. 记忆检索（Recall）：在后续对话中智能检索相关记忆
对话 1: "我喜欢 TypeScript，在 A 公司工作"
    → 提取: [偏好: TypeScript] [事实: 在 A 公司工作]
    → 存储: 向量化嵌入 + 元数据

对话 2: "推荐一个适合我的编程项目"
    → 检索: [用户喜欢 TypeScript]
    → 上下文注入: "用户偏好 TypeScript..."
    → LLM 回答: "考虑到你喜欢 TypeScript..."

练习题： 1. 列举 3 个你希望 AI 记住但当前 LLM 无法记住的信息类型。 2. 思考"记忆矛盾"的场景：如果用户先说"我在 A 公司"，后说"我跳槽到 B 公司"，系统应该如何处理？

1.2 基本记忆存储与检索

概念讲解：

在 1.1 中我们理解了 AI 记忆的概念。现在学习如何使用 Supermemory API 存储和检索记忆。

代码示例：

// TypeScript 基本使用示例
import { Supermemory } from 'supermemory';

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

// 存储记忆
await sm.memories.create({
  content: "用户喜欢 TypeScript，在 A 公司担任前端工程师",
  metadata: {
    userId: "user-123",
    source: "chat",
    timestamp: new Date().toISOString()
  }
});

// 检索相关记忆
const results = await sm.memories.search({
  query: "这个用户喜欢什么编程语言？",
  userId: "user-123",
  limit: 5
});

console.log("相关记忆:", results);

# Python 基本使用示例
from supermemory import Supermemory

sm = Supermemory(api_key="your-api-key")

# 存储记忆
sm.memories.create(
    content="用户喜欢 TypeScript，在 A 公司担任前端工程师",
    metadata={
        "userId": "user-123",
        "source": "chat",
    }
)

# 检索相关记忆
results = sm.memories.search(
    query="这个用户喜欢什么编程语言？",
    userId="user-123",
    limit=5
)

print("相关记忆:", results)

执行结果：

相关记忆: [
  {
    content: "用户喜欢 TypeScript，在 A 公司担任前端工程师",
    score: 0.95,
    metadata: { userId: "user-123", source: "chat" }
  }
]

练习题： 1. 存储 5 条不同的用户信息（偏好、事实、指令），然后通过不同查询检索。 2. 测试模糊查询：存储"我喜欢猫"，查询"宠物推荐"，观察检索效果。

1.3 自动记忆提取

概念讲解：

在 1.2 中我们手动存储记忆。Supermemory 的核心优势是自动从对话中提取记忆，无需手动操作。

代码示例：

// 自动从对话中提取记忆
const conversation = [
  { role: "user", content: "我最近在用 React 开发一个电商网站" },
  { role: "assistant", content: "好的，React 是一个很好的选择..." },
  { role: "user", content: "对了，我叫张三，在淘宝工作" },
  { role: "assistant", content: "你好张三..." }
];

// Supermemory 自动提取记忆
await sm.extract({
  messages: conversation,
  userId: "user-123"
});
// 自动提取: [使用 React] [电商网站项目] [名字: 张三] [工作: 淘宝]

// 后续对话中自动检索相关记忆
const context = await sm.memories.search({
  query: "帮我选择一个状态管理方案",
  userId: "user-123"
});
// 自动返回: [用户使用 React 开发电商网站]

练习题： 1. 创建一段包含 3 个可提取事实的对话，验证自动提取效果。 2. 测试矛盾处理：先说"我在 A 公司"，后说"我跳槽到 B 公司"，检查记忆更新。

第二部分：进阶篇

2.1 混合搜索（RAG + Memory）

概念讲解：

在 1.3 中我们实现了基本的记忆提取。Supermemory 的混合搜索允许同时检索外部知识库（RAG）和个人记忆（Memory），在单个查询中获取两方面的信息。

代码示例：

// 添加外部知识到 RAG 知识库
await sm.documents.create({
  content: "React 18 引入了 Concurrent Features，包括 useTransition 和 useDeferredValue...",
  metadata: { source: "react-docs", type: "documentation" }
});

// 混合搜索：同时检索知识库和用户记忆
const results = await sm.search({
  query: "帮我优化 React 电商网站的性能",
  userId: "user-123",
  hybrid: true  // 同时搜索 RAG + Memory
});

// 结果包含：
// 1. RAG: React 18 并发特性文档
// 2. Memory: 用户在开发电商网站，使用 React

注意事项： - 混合搜索会增加响应时间和成本（需要两次检索 + 合并排序）。 - 对于只需要文档检索的场景，使用纯 RAG 搜索即可。

练习题： 1. 添加 3 篇技术文档到 RAG 知识库，测试混合搜索效果。 2. 对比纯 RAG 搜索和混合搜索的结果差异。

2.2 连接器集成

概念讲解：

Supermemory 支持从多种外部数据源自动同步知识，包括 Google Drive、Gmail、Notion、GitHub 等。

代码示例：

// 配置 Notion 连接器
await sm.connectors.create({
  type: "notion",
  config: {
    apiKey: process.env.NOTION_API_KEY,
    databases: ["工作笔记", "项目文档"]
  },
  userId: "user-123"
});

// 配置 GitHub 连接器（同步代码仓库）
await sm.connectors.create({
  type: "github",
  config: {
    token: process.env.GITHUB_TOKEN,
    repositories: ["my-org/my-project"]
  },
  userId: "user-123"
});

// 连接器会自动定期同步内容到 Supermemory
// 后续查询会自动包含连接器同步的知识

练习题： 1. 配置一个连接器（如 GitHub），验证知识同步效果。 2. 测试从连接器同步的内容是否能被正确检索。

第三部分：高级篇

3.1 自定义记忆处理

// 自定义记忆提取规则
await sm.memories.create({
  content: "用户的代码审查偏好：使用函数式编程风格，避免 class 组件",
  metadata: {
    userId: "user-123",
    type: "instruction",
    priority: "high",
    expiresAt: null  // 永不过期
  }
});

// 设置记忆过期时间（临时偏好）
await sm.memories.create({
  content: "用户暂时使用 Python 进行数据分析项目",
  metadata: {
    userId: "user-123",
    type: "temporary_preference",
    expiresAt: "2026-07-01T00:00:00Z"  // 3 个月后过期
  }
});

3.2 最佳实践

  1. 合理分类记忆类型：区分事实（长期）、偏好（中期）、指令（短期），设置不同的过期策略。
  2. 定期清理过时记忆：利用知识更新机制自动遗忘过时信息。
  3. 注意隐私合规：敏感信息（PII）存储需符合 GDPR 等法规要求。
  4. 控制检索数量：设置合理的 limit 参数，避免注入过多上下文导致 LLM 困惑。
  5. 监控记忆质量：定期审查自动提取的记忆准确性。

第四部分：实战项目

项目需求

构建一个个性化编程助手，能够： - 记住用户的编程偏好和技术栈 - 从用户 GitHub 仓库学习代码风格 - 提供个性化的代码建议

本项目综合运用：记忆存储（1.2）、自动提取（1.3）、混合搜索（2.1）、连接器（2.2）共 4 个知识点。

完整实现代码

import { Supermemory } from 'supermemory';

const sm = new Supermemory({ apiKey: process.env.SUPERMEMORY_API_KEY });
const USER_ID = "developer-123";

// Step 1: 存储初始用户画像（知识点 1: 记忆存储）
await sm.memories.create({
  content: "资深前端工程师，精通 TypeScript/React/Next.js，偏好函数式编程",
  metadata: { userId: USER_ID, type: "profile" }
});

// Step 2: 配置 GitHub 连接器（知识点 4: 连接器）
await sm.connectors.create({
  type: "github",
  config: { token: process.env.GITHUB_TOKEN, repositories: ["my-org/frontend"] },
  userId: USER_ID
});

// Step 3: 模拟对话（知识点 2: 自动提取）
const chat = [
  { role: "user", content: "我最近在用 Tailwind CSS，觉得很好用" },
  { role: "assistant", content: "Tailwind CSS 确实很灵活..." },
  { role: "user", content: "我不喜欢用 CSS-in-JS，太复杂了" },
];
await sm.extract({ messages: chat, userId: USER_ID });

// Step 4: 个性化查询（知识点 3: 混合搜索）
const results = await sm.search({
  query: "帮我设计一个按钮组件",
  userId: USER_ID,
  hybrid: true
});
// 自动结合: React + TypeScript + Tailwind CSS 偏好 + GitHub 代码风格

扩展挑战

  1. 添加 Slack 连接器，从工作聊天中提取项目上下文。
  2. 实现记忆质量评分，自动标记低置信度的记忆供人工审核。

第五部分：常见问题与排查指南

常见错误及解决方案

错误信息 原因 解决方案
API key invalid API Key 未设置或无效 检查 SUPERMEMORY_API_KEY 环境变量
Memory not found 检索的记忆不存在 检查 userId 是否一致，先存储再检索
Rate limit exceeded API 调用频率过高 降低调用频率，使用批量接口
Connector sync failed 连接器认证失败 检查连接器的 API Token 是否有效
Search timeout 查询过于复杂 简化查询，减少 limit 值

调试技巧

  1. 使用日志模式：启用调试日志查看记忆提取和检索的详细过程。
  2. 检查存储内容：定期列出用户的所有记忆，确认自动提取的准确性。
  3. 对比有无记忆的回答：同一个问题，对比有/无 Supermemory 上下文时 LLM 的回答差异。

第六部分：学习路线推荐

官方文档推荐阅读顺序

  1. GitHub README — 快速入门和 API 概览
  2. API 文档 — 完整的 API 参考（supermemory.ai）
  3. 连接器文档 — 外部数据源集成
  4. Skills 仓库 — 高级功能扩展
  5. OpenCode 插件 — IDE 集成

推荐进阶资源