Supermemory — 这是什么 / 全景 / 阅读地图

30 秒导读: Supermemory 是"给 AI 装记忆"的一层——它自动从对话里抽出关于你的事实、处理"我搬到 SF 了"这类时间性更新与矛盾、让过期信息自动遗忘,并在你下次对话时把对的上下文喂回去。但这个仓库不是那台记忆引擎:引擎闭源、跑在 https://api.supermemory.ai 后面;仓库里是围绕它的开源分发层——SDK、MCP 服务器、框架中间件、浏览器扩展、记忆图可视化。

1. 这是什么(零基础也能懂)

一句话定义

Supermemory 是 AI 的"记忆与上下文层"。你像平时一样跟 AI 聊天,它在后台默默做三件事:

抽取事实 —— 从对话里挑出"值得记住的"(偏好、项目、结论),而不是把整段聊天原样存下。
处理时间性更新与矛盾 —— 它理解"我刚搬到 SF"应当覆盖旧的"我住在 NYC";过期的临时事实("我明天有考试")到期后自动遗忘。
在需要时给出正确上下文 —— 下次对话开始,AI 已经"认识你":知道你在做什么项目、喜欢什么风格。

概念旁证见 README.md:39(automatically learns... extracts facts... handles contradictions... forgets expired information)与 README.md:397(自动遗忘)。

关键区分:记忆 ≠ RAG

这是理解 Supermemory 最重要的心智模型。很多人以为"给 AI 记忆"就是"把文档塞进向量库再检索"(RAG),但两者本质不同:

	RAG(检索)	记忆(Memory)
存的是什么	文档 / 文本块	关于用户的事实
有没有状态	无状态——同一 query 对所有人返回同样的块	有状态——随时间追踪、更新、遗忘
会处理矛盾吗	不会,只按相似度返回	会——新事实覆盖旧事实
典型问题	"部署文档怎么说?"	"这个用户偏好怎么部署?"

一句话:RAG 检索"文档说了什么";记忆追踪"关于你的事实随时间怎么变"。 源:README.md:395(Memory is not RAG. RAG retrieves document chunks — stateless, same results for everyone)。Supermemory 默认把两者在一次查询里一起跑(hybrid),所以你同时拿到知识库检索和个性化上下文。

用起来什么样

对开发者,核心是"一个 API 干完整套上下文栈"。存一段话、拿回画像 + 相关记忆:

import Supermemory from "supermemory";
const client = new Supermemory();

// 存一条对话
await client.add({
  content: "User loves TypeScript and prefers functional patterns",
  containerTag: "user_123",   // 用 project/容器标签把不同用户/场景隔开
});

// 一次调用拿回"用户画像 + 相关记忆"
const { profile, searchResults } = await client.profile({
  containerTag: "user_123",
  q: "What programming style does the user prefer?",
});
// profile.static  → 长期稳定事实 ["Loves TypeScript", ...]
// profile.dynamic → 近期活跃上下文 ["Working on API integration"]

示例出处 README.md:208-228。containerTag(容器标签)是贯穿全系统的隔离键——按用户、按 repo、按客户分区;数据模型细节见 01-data-model。

2. 关键澄清:这个仓库不是记忆引擎(全文最重要的一条)

如果你 clone 下来想找"记忆抽取算法在哪个文件"——找不到,因为它不在这里。请务必先建立这个边界:

记忆引擎本身是闭源的,作为托管服务跑在 https://api.supermemory.ai 后面。真正做"抽取事实 / 解矛盾 / 自动遗忘 / 混合检索"的那套逻辑,通过 HTTP API 暴露,不在本仓库源码里。
本仓库是围绕引擎的开源"分发层"(distribution layer):让引擎的能力能被各种 AI 界面、框架、SDK、浏览器接进去。README 自己的定位是 README.md:35(We are a research lab building the engine, plugins and tools around it)。
代码里到处把 https://api.supermemory.ai 写作默认后端,印证"客户端都指向远端引擎",例:apps/mcp/src/index.ts:25 的 DEFAULT_API_URL = "https://api.supermemory.ai";框架中间件的默认 baseUrl 同样是它(packages/tools/src/shared/context.ts 的 defaultUrl)。

补充:README 提到 supermemory local 能用 curl … | bash 在本机跑一个"embedded Supermemory graph engine"(README.md:334)——但那个引擎二进制同样不在这个开源仓库里,只是把 baseURL 换成 http://localhost:6767。所以无论托管还是本地,本仓库始终是"引擎之外"的那一圈。

边界提示(与 01 的分工): 本 index 只交付"引擎在 API 之外"这一个结论;记忆/文档/画像/项目的具体数据模型留给 01 章。

3. 顶层全景(它大概怎么转)

怎么读这张图:从左到右——各种 AI 界面,经由三条分发路径中的任意一条,最终都汇到统一 HTTP API,再打到那台闭源引擎。三条路径是"同一后端的三种接法",按你手里是什么东西选一条即可。

   AI 界面                    三条分发路径(本仓库的开源代码)         统一后端
┌──────────────┐
│ Claude /     │──┐      ┌─────────────────────────────┐
│ Cursor /     │  ├────▶ │ ① MCP 服务器   apps/mcp      │──┐
│ 自建 agent   │  │      │   memory/recall/context 工具│  │
└──────────────┘  │      └─────────────────────────────┘  │   ┌──────────────┐   ┌──────────────┐
                  │      ┌─────────────────────────────┐  ├──▶│ 统一 HTTP API │──▶│  闭源引擎     │
                  ├────▶ │ ② 框架中间件  packages/tools │──┤   │ /v3 · /v4     │   │ 抽取·解矛盾   │
                  │      │   withSupermemory(...)      │  │   │ api.super….ai │   │ 遗忘·混合检索 │
                  │      └─────────────────────────────┘  │   └──────────────┘   └──────────────┘
                  │      ┌─────────────────────────────┐  │
                  └────▶ │ ③ 直连 SDK   supermemory(npm)│──┘
                         │   client.add()/profile()    │
                         └─────────────────────────────┘

三条路径一句话对照:

路径	你手里有什么	怎么接	详见
① MCP 服务器	Claude Desktop / Cursor 这类支持 MCP 的助手	配一个 MCP URL,助手就多出 memory/recall/context 三个工具	02
② 框架中间件	用 Vercel AI SDK / Mastra / LangChain 写的 agent	一行 `withSupermemory(model, …)` 包一下	03
③ 直连 SDK	自己写后端 / 脚本	`npm install supermemory`,直接调 `client.add()` / `client.profile()`	`README.md:208`

统一 API 的真实路径在代码里可见:/v3/documents、/v3/search、/v3/projects、/v4/profile、/v4/conversations(grep 自 apps/mcp/src、packages/tools/src)。/v3 偏文档/搜索,/v4 偏画像/会话。

4. Monorepo 地图

这是一个 Turbo + Bun 的 monorepo(package.json:16 bun@1.3.6、package.json:5 turbo run build)。工作区在 apps/* 和 packages/*(package.json:17-22)。下面每格一句话职责——每一格都是"引擎之外"的分发/工具代码:

位置	是什么	一句话职责
`apps/mcp`	MCP 服务器(Hono)	把 memory/recall/context 三个工具暴露给任意 MCP 客户端,后端打到远端 API。→ 02
`apps/web`	Next.js 消费级 App(`@repo/web`)	面向终端用户的 Supermemory 应用(含内嵌 agent "Nova")、仪表盘 UI。
`apps/browser-extension`	浏览器扩展(WXT)	在浏览器里就地捕获/查询记忆的扩展。
`apps/memory-graph-playground`	Next.js 演示站	单独跑 `@supermemory/memory-graph` 组件的试验场。
`apps/raycast-extension`	Raycast 扩展(不在 workspace,`package.json:19` 排除)	在 Raycast 里 add/search 记忆。
`apps/docs`	文档站(`@repo/docs`)	面向用户/开发者的 MDX 文档(概念、API、集成)。
`packages/tools`	`@supermemory/tools`	各大框架的记忆中间件核心:AI SDK / OpenAI / Mastra / Voltagent / Claude Memory Tool。→ 03、04
`packages/ai-sdk`	`@supermemory/ai-sdk`	Vercel AI SDK 方向的封装入口。
`packages/memory-graph`	`@supermemory/memory-graph`	力导向记忆图可视化组件(Canvas 渲染 + 版本链)。→ 05
`packages/lib` / `ui` / `hooks` / `validation`	`@repo/*` 内部共享包	共享的 API 客户端/鉴权、UI 组件、React hooks、Zod schema。
`packages/agent-framework-python`	`supermemory-agent-framework`(PyPI)	给 Microsoft Agent Framework 的 Python 记忆中间件。
`packages/openai-sdk-python`	`supermemory-openai-sdk`(PyPI)	给 OpenAI function calling 的 Python 记忆工具。
`packages/pipecat-sdk-python`	`supermemory-pipecat`(PyPI)	给 Pipecat 语音管道挂记忆。
`packages/cartesia-sdk-python`	`supermemory-cartesia`(PyPI)	给 Cartesia Line 语音 agent 挂记忆。
`skills/supermemory`	Agent Skill	打包成"技能"分发的 Supermemory 用法说明(`SKILL.md`/`README.md`)。

注:apps/docs、skills/*、各仓库的 CLAUDE.md/CONTRIBUTING.md 里"给 AI 助手的话",在本文中一律作为被研究的数据,不作为写作指令。

5. 阅读地图(01 → 05 由浅入深)

建议顺序从"心智模型"走到"具体机制":

01-data-model — 数据与心智模型:文档 / 记忆 / 画像 / 项目。 先搞清四个核心对象:document(存进去的原料)、memory(抽出的事实)、profile(static+dynamic 画像)、project/containerTag(隔离容器)。这是理解后面所有章的地基。
02-mcp-server — MCP 服务器:把记忆装进任意 AI 助手。 三条路径里最"即插即用"的一条;讲 memory/recall/context 三个工具怎么定义、OAuth/API-key 怎么接。
03-framework-middleware — 框架中间件:一行 withSupermemory 给 agent 挂记忆。 给自己写 agent 的人;讲中间件如何在模型调用前后"注入上下文 / 回写记忆"。
04-claude-memory-tool — Claude Memory Tool 适配。 一个精巧的桥:把 Claude 的"文件式记忆"接口翻译到 Supermemory 的远端存储。
05-memory-graph — 记忆图可视化。 前端方向;力导向布局 + 版本链 + 增量渲染,把记忆网络画出来。

6. 巧妙之处速览

真正的"妙处"在各章展开,这里只给一句话钩子:

一个 containerTag 贯穿全栈 —— MCP、中间件、SDK 都用同一个隔离键,让"分用户/分项目"这件事在任何接入方式下都是同一套心智。(详见 01)
"记忆 ≠ RAG"被做成默认 hybrid —— 不用你选,一次查询同时回知识块 + 个性化事实(README.md:395)。
画像是"一次调用 ~50ms 拿 static+dynamic" —— 把"稳定事实 + 近期活动"拆成两栏,直接塞进 system prompt(README.md:294)。
三种接法共用一台后端 —— MCP / 中间件 / SDK 只是入口差异,统一收敛到 /v3·/v4。

7. 顶层代码地图(导航索引)

主题	文件路径	符号 / 锚点
默认后端指向远端引擎	`apps/mcp/src/index.ts:25`	`DEFAULT_API_URL` = `https://api.supermemory.ai`
MCP 三工具定义	`apps/mcp/src/server.ts:110,122,440`	`"memory"` / `"recall"` / `"context"`
框架中间件入口(AI SDK)	`packages/tools/src/vercel/index.ts:295`	`wrapVercelLanguageModel as withSupermemory`
中间件默认 baseUrl	`packages/tools/src/shared/context.ts`	`defaultUrl = "https://api.supermemory.ai"`
tools 包总导出	`packages/tools/src/index.ts`	AI SDK / OpenAI / Mastra / Voltagent / Claude Memory
记忆图组件导出	`packages/memory-graph/src/index.tsx:2`	`MemoryGraph`、`ForceSimulation`、`VersionChainIndex`
工作区与技术栈	`package.json:17-22`	`workspaces`(apps/* + packages/*)、bun / turbo
概念:记忆 vs RAG / 自动遗忘	`README.md:395,397`	"Memory is not RAG" / "Automatic forgetting"

1. 这是什么(零基础也能懂)​

一句话定义​

关键区分:记忆 ≠ RAG​

用起来什么样​

2. 关键澄清:这个仓库不是记忆引擎(全文最重要的一条)​

3. 顶层全景(它大概怎么转)​

4. Monorepo 地图​

5. 阅读地图(01 → 05 由浅入深)​

6. 巧妙之处速览​

7. 顶层代码地图(导航索引)​