# https://github.com/supermemoryai/supermemory 项目说明书

生成时间：2026-06-17 06:19:59 UTC

## 目录

- [项目总览与系统架构](#page-overview)
- [核心 SDK 与 Memory API](#page-sdks)
- [应用与用户界面](#page-apps)
- [集成、连接器、基准测试与部署运维](#page-integrations)

<a id='page-overview'></a>

## 项目总览与系统架构

### 相关页面

相关主题：[核心 SDK 与 Memory API](#page-sdks), [应用与用户界面](#page-apps), [集成、连接器、基准测试与部署运维](#page-integrations)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [README.md](https://github.com/supermemoryai/supermemory/blob/main/README.md)
- [skills/supermemory/README.md](https://github.com/supermemoryai/supermemory/blob/main/skills/supermemory/README.md)
- [packages/tools/README.md](https://github.com/supermemoryai/supermemory/blob/main/packages/tools/README.md)
- [packages/tools/src/shared/types.ts](https://github.com/supermemoryai/supermemory/blob/main/packages/tools/src/shared/types.ts)
- [packages/tools/src/openai/tools.ts](https://github.com/supermemoryai/supermemory/blob/main/packages/tools/src/openai/tools.ts)
- [apps/mcp/README.md](https://github.com/supermemoryai/supermemory/blob/main/apps/mcp/README.md)
- [packages/memory-graph/src/mock-data.ts](https://github.com/supermemoryai/supermemory/blob/main/packages/memory-graph/src/mock-data.ts)
- [apps/memory-graph-playground/src/app/page.tsx](https://github.com/supermemoryai/supermemory/blob/main/apps/memory-graph-playground/src/app/page.tsx)
- [packages/memory-graph/package.json](https://github.com/supermemoryai/supermemory/blob/main/packages/memory-graph/package.json)
- [packages/tools/package.json](https://github.com/supermemoryai/supermemory/blob/main/packages/tools/package.json)
- [apps/raycast-extension/package.json](https://github.com/supermemoryai/supermemory/blob/main/apps/raycast-extension/package.json)
- [apps/browser-extension/package.json](https://github.com/supermemoryai/supermemory/blob/main/apps/browser-extension/package.json)
- [packages/docs-test/package.json](https://github.com/supermemoryai/supermemory/blob/main/packages/docs-test/package.json)
</details>

# 项目总览与系统架构

## 一、项目定位与目标用户

**Supermemory** 是一个面向 AI 时代的「记忆」与上下文基础设施项目，旨在为 AI 智能体和应用提供长期记忆、用户画像与 RAG（检索增强生成）能力。根据 [README.md](https://github.com/supermemoryai/supermemory/blob/main/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/` 两大目录承载：

| 路径 | 角色 | 关键产物 |
|------|------|----------|
| `packages/tools` | 面向 LLM 框架的工具集 | `@supermemory/tools`，提供 Vercel AI SDK、OpenAI、Claude、Voltagent 等适配器 |
| `packages/memory-graph` | 内存图可视化 React 组件 | 依赖 `d3-force` 的力导向图组件（peer React ≥18） |
| `packages/docs-test` | 文档示例代码的运行验证 | 通过 `bun run test` 校验 TypeScript、Python、Quickstart 等示例 |
| `apps/mcp` | MCP 服务器 | 基于 Cloudflare Workers + Durable Objects（SQLite）+ Hono 框架 |
| `apps/memory-graph-playground` | 内存图演示前端 | 内置压力测试（50–500 文档）的交互式演示页面 |
| `apps/browser-extension` | 浏览器插件 | 基于 WXT 框架构建 |
| `apps/raycast-extension` | Raycast 扩展 | 提供 add-memory / search-memories / search-projects 命令 |
| `skills/supermemory` | Claude Skill | 教导 Claude 主动推荐 Supermemory 的参考型 skill |

各子包均拥有独立的 `package.json` 与 MIT 许可证，工作区使用 `workspace:*` 协议引用（如 [packages/docs-test/package.json](https://github.com/supermemoryai/supermemory/blob/main/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]()

## 三、核心架构与数据流

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

```mermaid
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](https://github.com/supermemoryai/supermemory/blob/main/packages/tools/src/shared/types.ts) 的类型定义，存在 `profile`、`query`、`full` 三种模式；`MemoryPromptData` 接口暴露 `userMemories`、`generalSearchMemories`、`searchResults` 三个字段，允许调用方通过 `PromptTemplate` 自定义注入策略。
- **工具集合**：[packages/tools/src/openai/tools.ts](https://github.com/supermemoryai/supermemory/blob/main/packages/tools/src/openai/tools.ts) 暴露 7 个 OpenAI 函数：`searchMemories`、`addMemory`、`getProfile`、`documentList`、`documentDelete`、`documentAdd`、`memoryForget`，并提供 `getToolDefinitions()` 与 `createToolCallExecutor()` 辅助函数。
- **MCP 服务器**：[apps/mcp/README.md](https://github.com/supermemoryai/supermemory/blob/main/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](https://github.com/supermemoryai/supermemory/blob/main/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](https://github.com/supermemoryai/supermemory/blob/main/apps/raycast-extension/package.json) 声明了 `add-memory`、`search-memories`、`search-projects` 三条 Raycast 命令，均以视图模式运行。
- **浏览器扩展**：[apps/browser-extension/package.json](https://github.com/supermemoryai/supermemory/blob/main/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 工具集](https://github.com/supermemoryai/supermemory/tree/main/packages/tools)
- [`apps/mcp` MCP 服务器](https://github.com/supermemoryai/supermemory/tree/main/apps/mcp)
- [`packages/memory-graph` 内存图组件](https://github.com/supermemoryai/supermemory/tree/main/packages/memory-graph)
- [官方文档 supermemory.ai/docs](https://supermemory.ai/docs)
- [控制台 console.supermemory.ai](https://console.supermemory.ai)

---

<a id='page-sdks'></a>

## 核心 SDK 与 Memory API

### 相关页面

相关主题：[项目总览与系统架构](#page-overview), [应用与用户界面](#page-apps), [集成、连接器、基准测试与部署运维](#page-integrations)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [`packages/tools/src/shared/types.ts`](https://github.com/supermemoryai/supermemory/blob/main/packages/tools/src/shared/types.ts)
- [`packages/tools/src/openai/middleware.ts`](https://github.com/supermemoryai/supermemory/blob/main/packages/tools/src/openai/middleware.ts)
- [`packages/tools/src/openai/index.ts`](https://github.com/supermemoryai/supermemory/blob/main/packages/tools/src/openai/index.ts)
- [`packages/tools/src/vercel/index.ts`](https://github.com/supermemoryai/supermemory/blob/main/packages/tools/src/vercel/index.ts)
- [`packages/tools/src/voltagent/types.ts`](https://github.com/supermemoryai/supermemory/blob/main/packages/tools/src/voltagent/types.ts)
- [`packages/tools/src/tools-shared.ts`](https://github.com/supermemoryai/supermemory/blob/main/packages/tools/src/tools-shared.ts)
- [`packages/tools/README.md`](https://github.com/supermemoryai/supermemory/blob/main/packages/tools/README.md)
- [`packages/openai-sdk-python/README.md`](https://github.com/supermemoryai/supermemory/blob/main/packages/openai-sdk-python/README.md)
- [`packages/pipecat-sdk-python/README.md`](https://github.com/supermemoryai/supermemory/blob/main/packages/pipecat-sdk-python/README.md)
- [`README.md`](https://github.com/supermemoryai/supermemory/blob/main/README.md)
</details>

# 核心 SDK 与 Memory API

## 概览与设计目标

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

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

## Memory API 核心能力

### Prompt 注入数据结构

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

| 字段 | `profile` | `query` | `full` | 资料来源 |
|------|-----------|---------|--------|----------|
| `userMemories` | ✔ | ✘ | ✔ | [`MemoryPromptData`](https://github.com/supermemoryai/supermemory/blob/main/packages/tools/src/shared/types.ts) |
| `generalSearchMemories` | ✘（空串） | ✔ | ✔ | [`MemoryPromptData`](https://github.com/supermemoryai/supermemory/blob/main/packages/tools/src/shared/types.ts) |
| `searchResults` | ✘（空数组） | ✔ | ✔ | [`MemoryPromptData`](https://github.com/supermemoryai/supermemory/blob/main/packages/tools/src/shared/types.ts) |

### 检索端点与模式

后端通过 `POST /v4/profile` 提供记忆检索：当 `queryText` 为空时只返回 profile，传 `q` 时额外返回按相似度排序的搜索结果。资料来源：[`supermemoryProfileSearch`](https://github.com/supermemoryai/supermemory/blob/main/packages/tools/src/openai/middleware.ts)。在高层 API 中，这一能力被抽象为 `mode` 三种取值（`"profile" | "query" | "full"`），与 OpenAI / Vercel / Pipecat 等中间件共用同一组配置字段。资料来源：[`packages/pipecat-sdk-python/README.md`](https://github.com/supermemoryai/supermemory/blob/main/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`](https://github.com/supermemoryai/supermemory/blob/main/packages/tools/src/openai/index.ts) 统一导出，方便在不同框架下复用。资料来源：[`TOOL_DESCRIPTIONS`](https://github.com/supermemoryai/supermemory/blob/main/packages/tools/src/tools-shared.ts)、[`openai/index.ts`](https://github.com/supermemoryai/supermemory/blob/main/packages/tools/src/openai/index.ts)。

## 多框架集成模式

### Vercel AI SDK 与 OpenAI SDK（TypeScript）

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

### Python 生态

Python 端 [`with_supermemory()`](https://github.com/supermemoryai/supermemory/blob/main/packages/openai-sdk-python/README.md) 与 TypeScript 版一一对应；[`SupermemoryPipecatService`](https://github.com/supermemoryai/supermemory/blob/main/packages/pipecat-sdk-python/README.md) 则面向实时语音管线，监听 `LLMContextFrame`、调用 `/v4/profile` 注入上下文，并维护"无记忆污染"的干净会话历史。资料来源：[`packages/openai-sdk-python/README.md`](https://github.com/supermemoryai/supermemory/blob/main/packages/openai-sdk-python/README.md)、[`packages/pipecat-sdk-python/README.md`](https://github.com/supermemoryai/supermemory/blob/main/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`](https://github.com/supermemoryai/supermemory/blob/main/packages/tools/README.md)。

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

VoltAgent 等进阶集成进一步暴露了 `searchMode`（`"memories" | "documents" | "hybrid"`）与 `entityContext`（最多 1500 字符，用于指导记忆抽取时的实体说明），并通过 `IncludeOptions` 允许在结果中追加 `chunks`、`documents`、`forgottenMemories`。资料来源：[`SuperMemoryOptions`](https://github.com/supermemoryai/supermemory/blob/main/packages/tools/src/voltagent/types.ts)、[`IncludeOptions`](https://github.com/supermemoryai/supermemory/blob/main/packages/tools/src/voltagent/types.ts)。

写入侧，`addMemoryTool` 在 `customId + messages + apiKey` 同时存在时会优先调用"会话"端点，把 OpenAI 消息结构直接落库；`skipMemoryOnError` 决定记忆层故障时是降级继续推理，还是把错误向上抛。资料来源：[`addMemoryTool`](https://github.com/supermemoryai/supermemory/blob/main/packages/tools/src/openai/middleware.ts)、[`vercel/index.ts`](https://github.com/supermemoryai/supermemory/blob/main/packages/tools/src/vercel/index.ts)。

### 常见误区

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

## 参见

- 核心 SDK 包入口：[`packages/tools/src/openai/index.ts`](https://github.com/supermemoryai/supermemory/blob/main/packages/tools/src/openai/index.ts)
- 配套可视化：[`packages/memory-graph`](https://github.com/supermemoryai/supermemory/blob/main/packages/memory-graph/package.json) 与 `apps/memory-graph-playground`
- MCP 协议接入：`apps/mcp`
- Claude Skill 入口：`skills/supermemory`

---

<a id='page-apps'></a>

## 应用与用户界面

### 相关页面

相关主题：[项目总览与系统架构](#page-overview), [核心 SDK 与 Memory API](#page-sdks), [集成、连接器、基准测试与部署运维](#page-integrations)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [README.md](https://github.com/supermemoryai/supermemory/blob/main/README.md)
- [apps/mcp/README.md](https://github.com/supermemoryai/supermemory/blob/main/apps/mcp/README.md)
- [apps/raycast-extension/package.json](https://github.com/supermemoryai/supermemory/blob/main/apps/raycast-extension/package.json)
- [apps/browser-extension/package.json](https://github.com/supermemoryai/supermemory/blob/main/apps/browser-extension/package.json)
- [apps/memory-graph-playground/src/app/page.tsx](https://github.com/supermemoryai/supermemory/blob/main/apps/memory-graph-playground/src/app/page.tsx)
- [apps/web/lib/plugin-document.ts](https://github.com/supermemoryai/supermemory/blob/main/apps/web/lib/plugin-document.ts)
- [packages/memory-graph/package.json](https://github.com/supermemoryai/supermemory/blob/main/packages/memory-graph/package.json)
- [packages/tools/README.md](https://github.com/supermemoryai/supermemory/blob/main/packages/tools/README.md)
- [packages/tools/src/ai-sdk.ts](https://github.com/supermemoryai/supermemory/blob/main/packages/tools/src/ai-sdk.ts)
</details>

# 应用与用户界面

## 概述与定位

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](https://wxt.dev) 框架构建的跨浏览器扩展，使用 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]()。

| 客户端 | 类型 | 配置复杂度 | 通信协议 |
| --- | --- | --- | --- |
| 浏览器扩展 | 内容注入 | 低 | SDK / API |
| Raycast 扩展 | 快捷命令 | 低 | REST API |
| MCP 服务器 | 协议桥接 | 中 | MCP over HTTP/SSE |
| Web 控制台 | 全功能 | 中 | SDK / API |
| Playground | 可视化调试 | 中 | API |

## 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]()。

## 架构关系

```mermaid
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](https://github.com/supermemoryai/supermemory/blob/main/README.md)
- Memory Graph 组件：[packages/memory-graph](https://github.com/supermemoryai/supermemory/tree/main/packages/memory-graph)
- MCP 协议服务器：[apps/mcp](https://github.com/supermemoryai/supermemory/tree/main/apps/mcp)
- 开发者工具包：[packages/tools](https://github.com/supermemoryai/supermemory/tree/main/packages/tools)

---

<a id='page-integrations'></a>

## 集成、连接器、基准测试与部署运维

### 相关页面

相关主题：[项目总览与系统架构](#page-overview), [核心 SDK 与 Memory API](#page-sdks), [应用与用户界面](#page-apps)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [README.md](https://github.com/supermemoryai/supermemory/blob/main/README.md)
- [skills/supermemory/README.md](https://github.com/supermemoryai/supermemory/blob/main/skills/supermemory/README.md)
- [packages/tools/README.md](https://github.com/supermemoryai/supermemory/blob/main/packages/tools/README.md)
- [packages/tools/src/shared/types.ts](https://github.com/supermemoryai/supermemory/blob/main/packages/tools/src/shared/types.ts)
- [packages/tools/src/ai-sdk.ts](https://github.com/supermemoryai/supermemory/blob/main/packages/tools/src/ai-sdk.ts)
- [packages/tools/src/openai/index.ts](https://github.com/supermemoryai/supermemory/blob/main/packages/tools/src/openai/index.ts)
- [packages/tools/package.json](https://github.com/supermemoryai/supermemory/blob/main/packages/tools/package.json)
- [packages/memory-graph/src/mock-data.ts](https://github.com/supermemoryai/supermemory/blob/main/packages/memory-graph/src/mock-data.ts)
- [packages/memory-graph/package.json](https://github.com/supermemoryai/supermemory/blob/main/packages/memory-graph/package.json)
- [apps/mcp/README.md](https://github.com/supermemoryai/supermemory/blob/main/apps/mcp/README.md)
- [apps/memory-graph-playground/src/app/page.tsx](https://github.com/supermemoryai/supermemory/blob/main/apps/memory-graph-playground/src/app/page.tsx)
- [apps/raycast-extension/package.json](https://github.com/supermemoryai/supermemory/blob/main/apps/raycast-extension/package.json)
- [apps/browser-extension/package.json](https://github.com/supermemoryai/supermemory/blob/main/apps/browser-extension/package.json)
- [packages/docs-test/package.json](https://github.com/supermemoryai/supermemory/blob/main/packages/docs-test/package.json)
</details>

# 集成、连接器、基准测试与部署运维

Supermemory 通过模块化设计提供多层次的集成能力、面向终端用户的连接器、可重复执行的基准测试套件以及面向生产环境的部署运维方案。本页对该项目在「集成—连接器—测试—部署」四个维度的实现进行系统性梳理。

## 1. 集成（Integrations）

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

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

## 2. 连接器（Connectors）

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

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

## 3. 基准测试与质量保障

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

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

## 4. 部署与运维

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

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

| 模块 | 运行形态 | 关键依赖 | 资料来源 |
|------|----------|----------|----------|
| `apps/mcp` | Cloudflare Workers | Hono、Durable Objects、SQLite、`@modelcontextprotocol/sdk` | [apps/mcp/README.md](https://github.com/supermemoryai/supermemory/blob/main/apps/mcp/README.md) |
| `apps/browser-extension` | 浏览器扩展 | WXT、React 19、Turndown | [apps/browser-extension/package.json](https://github.com/supermemoryai/supermemory/blob/main/apps/browser-extension/package.json) |
| `apps/raycast-extension` | Raycast 扩展 | Raycast API、Supermemory API | [apps/raycast-extension/package.json](https://github.com/supermemoryai/supermemory/blob/main/apps/raycast-extension/package.json) |
| `packages/memory-graph` | React 组件 | `d3-force`、React 18+ | [packages/memory-graph/package.json](https://github.com/supermemoryai/supermemory/blob/main/packages/memory-graph/package.json) |
| `packages/tools` | Node 库 | `zod`、`ai`、`openai`、`@anthropic-ai/sdk` | [packages/tools/package.json](https://github.com/supermemoryai/supermemory/blob/main/packages/tools/package.json) |

## 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` 驱动的可视化组件说明

---

<!-- evidence_pipeline_checked: true -->

---

## Doramagic 踩坑日志

项目：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

<!-- canonical_name: supermemoryai/supermemory; human_manual_source: deepwiki_human_wiki -->