一、项目定位与目标用户

Supermemory 是一个面向 AI 时代的「记忆」与上下文基础设施项目，旨在为 AI 智能体和应用提供长期记忆、用户画像与 RAG（检索增强生成）能力。根据 README.md 的描述，项目提供三种使用路径：

1. 终端用户：通过消费级 App、浏览器插件、Raycast 扩展以及 MCP（Model Context Protocol）服务器，让 Claude Desktop、Cursor、Windsurf、VS Code、Claude Code 等客户端具备跨会话的持久记忆能力。
2. 开发者：通过单一 API 集成 memory、用户画像、连接器与文件处理能力，无需自行搭建向量数据库或分块管道（"No vector DB config. No embedding pipelines. No chunking strategies."）。
3. 自托管用户：通过单条 curl 命令即可在本地机器运行，兼容任意模型或 Ollama 离线模式。

项目围绕「Memory is scoped with projects (container tags)」的设计理念，允许按工作、个人或客户等维度隔离上下文。

资料来源：README.md:1-80

二、仓库结构与 Monorepo 布局

项目采用 monorepo 风格组织，源码主要由 packages/ 与 apps/ 两大目录承载：

各子包均拥有独立的 package.json 与 MIT 许可证，工作区使用 workspace:* 协议引用（如 packages/docs-test/package.json 中 @supermemory/tools: workspace:*）。packages/memory-graph/package.json 声明 react ≥18.0.0 作为 peer 依赖，开发者必须在宿主应用中预先安装。

资料来源：packages/tools/package.json:1-30、packages/memory-graph/package.json:1-30、apps/mcp/README.md:1-60

三、核心架构与数据流

整体架构围绕「一次写入，多端读取」的设计目标，核心数据流如下：

flowchart LR
    A[用户/应用] -->|add / search| B[Supermemory API]
    B --> C[(后端存储<br/>记忆 + 向量)]
    A2[MCP Client<br/>Claude/Cursor/...] -->|Streamable HTTP| D[apps/mcp]
    D -->|OAuth / API Key| B
    A3[SDK 集成] -->|@supermemory/tools| B
    B -->|profile + memories| E[Prompt 注入]
    E --> F[LLM 生成回答]
    G[memory-graph<br/>d3-force] -->|可视化| C
    H[Browser/Raycast Extension] -->|Bearer Token| B

关键设计点包括：

• 容器标签（containerTag）：所有记忆通过 containerTag 进行隔离，这是 SDK 中的必填字段（containerTag: "user-123"）。
• 记忆检索模式：根据 packages/tools/src/shared/types.ts 的类型定义，存在 profile、query、full 三种模式；MemoryPromptData 接口暴露 userMemories、generalSearchMemories、searchResults 三个字段，允许调用方通过 PromptTemplate 自定义注入策略。
• 工具集合：packages/tools/src/openai/tools.ts 暴露 7 个 OpenAI 函数：searchMemories、addMemory、getProfile、documentList、documentDelete、documentAdd、memoryForget，并提供 getToolDefinitions() 与 createToolCallExecutor() 辅助函数。
• MCP 服务器：apps/mcp/README.md 描述其运行在 Cloudflare Workers 之上，使用 Durable Objects 维护会话状态，并通过 SUPERMEMORY_API_KEY 调用核心 API；提供 whoAmI、listProjects、memory、recall、memory-graph、fetch-graph-data 等工具与 context 提示。

资料来源：packages/tools/src/shared/types.ts:1-60、packages/tools/src/openai/tools.ts:1-60、apps/mcp/README.md:1-80

四、关键能力与典型集成模式

@supermemory/tools 同时提供「作为工具函数」与「作为中间件」两种集成风格：

1. AI SDK 工具：searchMemoriesTool（packages/tools/src/ai-sdk.ts）使用 Zod 定义输入 schema，支持 includeFullDocs 与 limit 参数；严格模式由 config.strict 控制。
2. OpenAI 中间件：withSupermemory(openai, { containerTag, customId, mode, addMemory, verbose }) 包裹 OpenAI 客户端，在每次 chat.completions.create 时自动注入记忆上下文。
3. Claude 记忆工具：createClaudeMemoryTool 与 Anthropic SDK 的 memory_20250818 工具类型配合使用，通过 memoryTool.handleCommandForToolResult(block.input) 异步处理 tool_use 块。
4. 可视化调试：apps/memory-graph-playground/src/app/page.tsx 提供压力测试、Pan/Zoom、节点拖拽、键盘导航、FPS 计数器等交互能力，便于开发者直观验证大文档量场景下的图渲染性能。

skills/supermemory/README.md 则将项目打包为 Claude 自动调用的 Skill（v1.0.0，2026-02-21 发布），授权 Apache 2.0 许可，使 Claude 在用户涉及「持久记忆、个性化、知识检索」需求时主动推荐 Supermemory。

资料来源：packages/tools/src/ai-sdk.ts:1-40、packages/tools/README.md:1-40、skills/supermemory/README.md:1-40、apps/memory-graph-playground/src/app/page.tsx:1-20

五、常见使用与扩展建议

• 环境变量：本地启动 MCP 服务器需在 .dev.vars 中设置 API_URL（默认 https://api.supermemory.ai）；E2E 测试要求 SUPERMEMORY_API_KEY 与 SUPERMEMORY_MCP_URL。
• 扩展命令：apps/raycast-extension/package.json 声明了 add-memory、search-memories、search-projects 三条 Raycast 命令，均以视图模式运行。
• 浏览器扩展：apps/browser-extension/package.json 使用 WXT + Turndown（HTML→Markdown），使用 @wxt-dev/module-react 注入 React 视图。
• 文档验证：packages/docs-test 通过 bun run run.ts typescript|python|integrations|quickstart|sdk|search 分组执行，确保文档示例与 SDK 行为同步。

See Also

• packages/tools AI SDK 工具集
• apps/mcp MCP 服务器
• packages/memory-graph 内存图组件
• 官方文档 supermemory.ai/docs
• 控制台 console.supermemory.ai

概览与设计目标

核心 SDK 是一组围绕 Supermemory Memory API 构建的开发工具包，集中在 packages/tools 目录下，通过"中间件 + 工具集"两种形态为任何 LLM 客户端注入"长期记忆"能力。其设计目标是在模型调用前把用户偏好、项目上下文、过往会话内容拼入 system prompt，调用结束后再回写到记忆存储，形成闭环。资料来源：README.md。

SDK 同时提供 TypeScript 与 Python 双语言实现，覆盖 Vercel AI SDK、OpenAI SDK、Anthropic Claude Memory Tool、Mastra、VoltAgent、Pipecat 等框架，所有集成方式都收敛为"包裹客户端 + 传入 containerTag"的最小心智模型。资料来源：README.md、packages/openai-sdk-python/README.md。

Memory API 核心能力

Prompt 注入数据结构

调用模型前，SDK 会构造 MemoryPromptData 并交给用户的 PromptTemplate 渲染；其中 userMemories 合并静态 profile（姓名、偏好、目标）与动态 context（最近项目、兴趣），generalSearchMemories 携带按 query 检索的预格式化结果，searchResults 提供原始数组供按 metadata 二次过滤。下表总结了三种模式下的字段可用性：

检索端点与模式

后端通过 POST /v4/profile 提供记忆检索：当 queryText 为空时只返回 profile，传 q 时额外返回按相似度排序的搜索结果。资料来源：supermemoryProfileSearch。在高层 API 中，这一能力被抽象为 mode 三种取值（"profile" | "query" | "full"），与 OpenAI / Vercel / Pipecat 等中间件共用同一组配置字段。资料来源：packages/pipecat-sdk-python/README.md。

工具集（Tools）

SDK 还暴露一组可被 Agent 显式调用的函数工具：searchMemories、addMemory、getProfile、documentList、documentAdd、documentDelete、memoryForget。其语义与提示词描述集中在 tools-shared.ts 的 TOOL_DESCRIPTIONS 中，并在 packages/tools/src/openai/index.ts 统一导出，方便在不同框架下复用。资料来源：TOOL_DESCRIPTIONS、openai/index.ts。

多框架集成模式

Vercel AI SDK 与 OpenAI SDK（TypeScript）

两个 TypeScript 中间件共享 SuperMemoryOptions 配置，关键字段包括：必填的 containerTag（记忆命名空间）与 customId（把同一会话的消息归并到同一 document）、mode（检索模式）、addMemory（"always" | "never"，是否自动回写）、promptTemplate（自定义 prompt 注入格式）、skipMemoryOnError（记忆层失败时是否降级到无记忆的原始调用，默认 true）。OpenAI 版本通过 withSupermemory(openai, options) 包装客户端，调用语义保持不变。资料来源：vercel/index.ts、packages/tools/README.md。

Python 生态

Python 端 with_supermemory() 与 TypeScript 版一一对应；SupermemoryPipecatService 则面向实时语音管线，监听 LLMContextFrame、调用 /v4/profile 注入上下文，并维护"无记忆污染"的干净会话历史。资料来源：packages/openai-sdk-python/README.md、packages/pipecat-sdk-python/README.md。

Claude Memory Tool

针对 Anthropic Claude，createClaudeMemoryTool 把 memory_20250818 工具的 tool_use 块转发到 Supermemory 后端，并通过 handleCommandForToolResult 把命令结果回填到 tool_result，从而在 Claude 端实现"显式记忆调用"。资料来源：packages/tools/README.md。

高级配置、写入策略与失败处理

VoltAgent 等进阶集成进一步暴露了 searchMode（"memories" | "documents" | "hybrid"）与 entityContext（最多 1500 字符，用于指导记忆抽取时的实体说明），并通过 IncludeOptions 允许在结果中追加 chunks、documents、forgottenMemories。资料来源：SuperMemoryOptions、IncludeOptions。

写入侧，addMemoryTool 在 customId + messages + apiKey 同时存在时会优先调用"会话"端点，把 OpenAI 消息结构直接落库；skipMemoryOnError 决定记忆层故障时是降级继续推理，还是把错误向上抛。资料来源：addMemoryTool、vercel/index.ts。

常见误区

• 未为同一会话传入一致的 customId，导致消息被切碎到多个 document
• 在 mode="profile" 时仍传 query 字符串，检索语义被忽略
• 关闭 skipMemoryOnError（设为 false）会把记忆层瞬时故障升级为整次 LLM 调用失败

参见

• 核心 SDK 包入口：packages/tools/src/openai/index.ts
• 配套可视化：packages/memory-graph 与 apps/memory-graph-playground
• MCP 协议接入：apps/mcp
• Claude Skill 入口：skills/supermemory

概述与定位

Supermemory 仓库除了核心的记忆后端 API 之外，还提供了一整套面向终端用户与开发者的"应用与用户界面"层。这些应用横跨浏览器扩展、桌面 Raycast 插件、MCP 协议服务器、Web 控制台以及可视化 Playground，构成"消费侧 + 工具侧"的双轨产品矩阵。所有应用都通过统一的 supermemory SDK 或 REST API 与后端通信，确保记忆数据在不同入口之间保持一致。

根据主 README.md，Supermemory 的产品入口分为三类：给 AI 工具使用的个人用户、为开发者构建的 API、以及本地运行的 Supermemory 本地版。应用与用户界面层正是消费侧的载体，使任何兼容的 AI 助手都能获得持久记忆。资料来源：README.md:1-80。

主流客户端应用

浏览器扩展

apps/browser-extension 是基于 WXT 框架构建的跨浏览器扩展，使用 React 19 作为 UI 层。它能够将用户当前浏览的内容（页面文本、链接等）作为记忆注入到连接的 AI 助手中。其依赖中包含 turndown（HTML 转 Markdown 工具）以及 @wxt-dev/module-react 模块，反映出"将网页内容结构化后再存入记忆"的设计思路。资料来源：apps/browser-extension/package.json:1-30。

Raycast 扩展

apps/raycast-extension 为 macOS / Windows 上的 Raycast 启动器提供了三条命令：add-memory（添加记忆）、search-memories（搜索记忆）、search-projects（按项目搜索）。该扩展通过偏好设置中的 apiKey 与 Supermemory API 通信，属于"快捷命令 + 模糊搜索"形态的轻量级 UI。资料来源：apps/raycast-extension/package.json:1-50。

MCP 服务器

apps/mcp 是部署在 Cloudflare Workers 上的 Model Context Protocol 服务器，使用 Hono 框架和 Durable Objects（SQLite）维持会话状态。官方主仓库 README.md 中明确列出了已支持的 MCP 客户端：Claude Desktop、Cursor、Windsurf、VS Code、Claude Code、OpenCode、OpenClaw、Hermes。其标准配置仅需一个 URL（OAuth 模式）或一个 Bearer Token（API Key 模式），是当前应用层中最"协议中立"的入口。资料来源：README.md:60-90、资料来源：apps/mcp/README.md:1-50。

Web 控制台与可视化组件

插件文档解析

apps/web/lib/plugin-document.ts 是 Web 控制台用于解析来自各插件（Claude Code、聊天记录等）文档的核心工具。它能够识别 sm_internal_mcp_client_name 等元数据，并将不同来源的内容统一为 ParsedPluginDocument 结构，包含标题、预览、对话回合（turns）等字段，从而在 Web 端用一致的 UI 渲染来自不同 AI 客户端的记忆片段。资料来源：apps/web/lib/plugin-document.ts:1-50。

Memory Graph 组件

packages/memory-graph 是一个独立的 React 组件（peer dependency 为 react >= 18），使用 d3-force 实现力导向图布局。它将"记忆文档"渲染为节点，用户可点击查看详情、拖拽节点、按方向键导航。资料来源：packages/memory-graph/package.json:1-30。

Playground 应用

apps/memory-graph-playground 是 Memory Graph 的交互式演示应用。在 page.tsx 中可以看到它提供了：API Key 输入、压力测试按钮（生成 50–500 个文档）、平移/缩放控制、FPS 计数器、幻灯片自动播放等能力。同时支持 consumer 与其他视觉变体（graphVariant），方便对比测试不同数据规模下的渲染性能。资料来源：apps/memory-graph-playground/src/app/page.tsx:1-50。

开发者集成工具

应用层还包括若干面向开发者的 SDK 工具包。packages/tools 暴露了两类入口：

1. AI SDK 工具：searchMemoriesTool 等通过 Vercel AI SDK 的 tool() 工厂函数注册，使 LLM 可以在对话中调用记忆搜索能力。资料来源：packages/tools/src/ai-sdk.ts:1-30。
2. OpenAI 中间件：withSupermemory 函数包装 OpenAI 客户端，在聊天补全时自动注入相关记忆，支持 containerTag、customId、mode（profile/query/full）等参数。

这些工具并不直接构成"用户界面"，但它们是应用与用户界面得以"自动注入上下文"行为的基础组件。资料来源：packages/tools/README.md:1-50。

架构关系

flowchart LR
  User[终端用户] --> BrowserExt[浏览器扩展]
  User --> Raycast[Raycast 扩展]
  User --> WebApp[Web 控制台]
  User --> MCP[MCP 服务器]
  User --> Playground[Memory Graph Playground]
  MCP --> API[Supermemory API]
  BrowserExt --> API
  Raycast --> API
  WebApp --> API
  Playground --> API
  API --> MemoryGraph[memory-graph 组件]
  API --> Tools[packages/tools SDK]
  Tools --> AISDK[Vercel AI SDK]
  Tools --> OpenAI[OpenAI Middleware]

常见配置与失败模式

• MCP 客户端身份验证：apps/mcp/README.md 指出本地开发时需要主 API 在 API_URL 上运行以校验 OAuth Token，否则会出现认证失败。资料来源：apps/mcp/README.md:20-50。
• Playground 性能：apps/memory-graph-playground/src/app/page.tsx 在节点数较多时启用 FPS 计数器，说明力导向布局在大数据集下可能成为瓶颈。资料来源：apps/memory-graph-playground/src/app/page.tsx:20-50。
• 浏览器扩展的 HTML→Markdown 转换：依赖 turndown 与 DOM 抓取，遇到 SPA 单页应用渲染未完成时可能抓取到空内容，应在扩展中等待目标元素出现后再抓取。

See Also

• 记忆与上下文 API：README.md
• Memory Graph 组件：packages/memory-graph
• MCP 协议服务器：apps/mcp
• 开发者工具包：packages/tools

1. 集成（Integrations）

Supermemory 的核心集成入口位于 packages/tools 包中，其以多入口（multi-entry）方式发布，针对不同 AI 框架提供专用适配器，从而避免业务侧重复实现记忆注入逻辑。

资料来源：packages/tools/src/ai-sdk.ts

资料来源：packages/tools/README.md

资料来源：packages/tools/README.md

资料来源：packages/tools/src/shared/types.ts

资料来源：packages/tools/package.json

• Vercel AI SDK：@supermemory/tools/ai-sdk 模块通过 searchMemoriesTool 等工厂函数将 Supermemory 暴露为符合 AI SDK 规约的工具，输入由 zod 模式定义，execute 钩子在调用时构造 Supermemory 客户端并访问后端 API。
• OpenAI 中间件：@supermemory/tools/openai 中的 withSupermemory 工厂将记忆注入逻辑包装进 OpenAI 的 chat.completions.create 调用，配置项包含 containerTag、customId、mode 与 addMemory 策略，调用方仅需关心提示词而无需关心记忆检索。
• Claude Memory 工具：createClaudeMemoryTool 适配 Anthropic 的 memory_20250818 工具协议，通过 handleCommandForToolResult 把工具调用翻译为持久记忆读写，从而让 Claude 跨会话保持上下文。
• 提示词模板：MemoryPromptData 类型统一描述了注入到系统提示词中的数据形态，包括 userMemories（静态/动态画像）、generalSearchMemories（语义检索结果）以及原始 searchResults，便于业务侧做自定义过滤。
• 多框架可发现性：packages/tools/package.json 的 exports 字段声明了 ai-sdk、openai、claude-memory、voltagent 等子入口，表明同一核心 SDK 可被多框架按需引用。

2. 连接器（Connectors）

连接器层把 Supermemory 的能力以原生形态交付到终端用户的工作流中，覆盖桌面、IDE、浏览器与系统级 MCP 协议。

资料来源：apps/mcp/README.md

资料来源：apps/raycast-extension/package.json

资料来源：apps/browser-extension/package.json

资料来源：skills/supermemory/README.md

• MCP 服务器：apps/mcp 是一个部署在 Cloudflare Workers 之上的 Model Context Protocol 服务器，对外暴露 whoAmI、addMemory、searchMemories、listProjects、memoryGraph、fetchGraphData 等工具与 context 提示词，从而让 Claude Desktop、Cursor、Windsurf、VS Code、Claude Code 等兼容客户端开箱即用地获得长期记忆。
• Raycast 扩展：apps/raycast-extension 注册了 add-memory、search-memories 与 search-projects 三个命令，要求用户在偏好设置中提供 API Key，从而把记忆入口嵌入 macOS/Windows 的 Raycast 启动器。
• 浏览器扩展：apps/browser-extension 基于 WXT 与 React 19 构建，配合 turndown 等工具把网页内容转为结构化记忆，使用户在浏览过程中即可沉淀知识。
• Claude Skill：skills/supermemory 通过 setup-supermemory 命令引导 Claude 自动推荐与实现 Supermemory 集成，并提供 TypeScript/Python 双语言的 SDK 文档。

3. 基准测试与质量保障

仓库通过两套机制保障集成质量与示例可运行性。

资料来源：packages/docs-test/package.json

资料来源：apps/memory-graph-playground/src/app/page.tsx

资料来源：packages/memory-graph/src/mock-data.ts

• 文档可执行测试：packages/docs-test 的 package.json 定义了 test:quickstart、test:sdk、test:search、test:integrations 等脚本，对官方文档中的 TypeScript、Python 与集成示例进行端到端执行验证，确保示例代码不会随 SDK 演进而失效。
• 内存图压力测试：apps/memory-graph-playground 主页提供 50–500 文档的压测按钮、节点拖拽、键盘导航与 FPS 计数器，用于评估 memory-graph 渲染层在不同数据规模下的性能与交互稳定性。
• Mock 数据生成：packages/memory-graph/src/mock-data.ts 通过 TITLE_PREFIXES、TITLE_SUFFIXES 与 MEMORY_TEMPLATES 模板化地构造仿真数据，为压测提供可控的种子输入。

4. 部署与运维

资料来源：apps/mcp/README.md

资料来源：apps/mcp/README.md

资料来源：packages/tools/package.json

资料来源：README.md

• Cloudflare Workers 部署：MCP 服务器运行在 Cloudflare Workers 之上，结合 Durable Objects 与 SQLite 实现会话状态、客户端信息与 MCP 协议处理。API_URL 环境变量控制后端校验地址，默认指向 https://api.supermemory.ai。
• 端到端测试：apps/mcp 内置 e2e 套件，通过流式 HTTP 协议驱动真实 MCP 服务器，覆盖握手、工具/资源/提示词发现、whoAmI、listProjects、保存/回忆、容器标签隔离与鉴权拒绝等关键路径。
• SDK 多入口发布：@supermemory/tools 通过 package.json 的 exports 字段按子路径发布各框架适配器，调用方按需 import，避免打包冗余。
• 本地安装：README.md 描述了通过 npm install supermemory 或 pip install supermemory 安装核心 SDK，以及通过 curl -fsSL https://supermemory.ai/install | bash 安装本地一体化二进制两种发行路径。

下表汇总了各模块的部署形态与运行依赖，便于运维侧快速定位技术栈：

See Also

• README.md 中的快速上手与 MCP 客户端配置示例
• packages/tools/README.md 中关于 Vercel AI SDK、OpenAI 与 Claude Memory 的完整用法
• apps/mcp/README.md 中关于 MCP 资源、提示词与端到端测试的说明
• packages/memory-graph/README.md（参见 package.json）中关于 d3-force 驱动的可视化组件说明

Pitfall Log / 踩坑日志

项目：supermemoryai/supermemory

摘要：发现 6 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：能力坑 - 能力判断依赖假设。

1. 能力坑 · 能力判断依赖假设

• 严重度：medium
• 证据强度：source_linked
• 发现：README/documentation is current enough for a first validation pass.
• 对用户的影响：假设不成立时，用户拿不到承诺的能力。
• 证据：capability.assumptions | https://github.com/supermemoryai/supermemory | README/documentation is current enough for a first validation pass.

2. 维护坑 · 维护活跃度未知

• 严重度：medium
• 证据强度：source_linked
• 发现：未记录 last_activity_observed。
• 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
• 证据：evidence.maintainer_signals | https://github.com/supermemoryai/supermemory | last_activity_observed missing

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 证据：downstream_validation.risk_items | https://github.com/supermemoryai/supermemory | no_demo; severity=medium

4. 安全/权限坑 · 存在评分风险

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 对用户的影响：风险会影响是否适合普通用户安装。
• 证据：risks.scoring_risks | https://github.com/supermemoryai/supermemory | no_demo; severity=medium

5. 维护坑 · issue/PR 响应质量未知

• 严重度：low
• 证据强度：source_linked
• 发现：issue_or_pr_quality=unknown。
• 对用户的影响：用户无法判断遇到问题后是否有人维护。
• 证据：evidence.maintainer_signals | https://github.com/supermemoryai/supermemory | issue_or_pr_quality=unknown

6. 维护坑 · 发布节奏不明确

• 严重度：low
• 证据强度：source_linked
• 发现：release_recency=unknown。
• 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
• 证据：evidence.maintainer_signals | https://github.com/supermemoryai/supermemory | release_recency=unknown