企业官网建设流程全解析

Supermemory 集成指南：为 AI 应用接入用户记忆、语义搜索与知识抽取的完整实战方案

【免费下载链接】supermemoryMemory and context engine + app that is extremely fast, scalable, and can be run fully locally. The Memory API for the AI era.项目地址: https://gitcode.com/GitHub_Trending/su/supermemory

本篇技术指南基于 Supermemory 官方集成文档（apps/docs/install.md），并辅以仓库源码（packages/tools等）进行深度印证，系统讲解如何把 Supermemory 嵌入你的 AI 应用：从安装依赖、配置全局过滤规则、设计 containerTag 数据模型，到通过 Vercel AI SDK、官方 TypeScript/Python SDK 或直接调用 HTTP API 完成"写入记忆—读取上下文—自动抽取知识"的完整闭环。读完本文，你将掌握一套可直接落地的记忆系统集成范式，并能依据源码理解其底层行为。

1. 集成前的五个关键决策

在写任何代码之前，Supermemory 官方集成文档要求先回答 5 个问题，它们直接决定后续每一步的配置方式：

1. 你在构建什么？个人聊天助手 / 团队知识库 / 客服机器人 / 文档问答 / 其他——不同场景对应不同的记忆写入与检索节奏。
2. 你希望如何集成？可选路径包括 Vercel AI SDK（@supermemory/tools）、OpenAI 插件、官方 SDK（npm 包supermemory或 pip 包supermemory）、以及直接调用 HTTP API。
3. 数据模型是怎样的？只有个人用户 → 使用containerTag: userId；只有组织 → 使用containerTag: orgId（组织成员共享记忆）；两者都有 → 需要额外设计组合策略（见第 3 节）。
4. 是否需要用户画像（User Profiles）？用户画像是系统自动维护的关于用户的事实集合（喜欢什么、正在做什么、偏好如何），官方推荐启用，通过client.profile()获取上下文。
5. 如何检索上下文？方案 A：单次调用同时包含搜索（profile({ containerTag, q: userMessage })）；方案 B：分开调用（profile()取事实，search()取记忆）。

这 5 个问题的答案分别对应本指南第 2～6 节的安装、全局设置、数据模型、集成代码与检索配置。

2. 安装依赖与获取 API Key

官方推荐的最小安装命令如下：

# 在 https://console.supermemory.ai 获取 API Key npm install supermemory # TypeScript / JavaScript SDK；Python 请用: pip install supermemory # 使用 Vercel AI SDK 集成时额外安装: npm install @supermemory/tools # 配置环境变量 export SUPERMEMORY_API_KEY="sm_..."

几点值得说明：

• 两个官方 SDK 为 npm 包supermemory（TypeScript）与 PyPI 包supermemory（Python），分别对应 SDK 文档 中的快速开始示例。
• @supermemory/tools是面向 AI 框架的工具包，其 package.json 显示它同时为 AI SDK、OpenAI、Mastra、VoltAgent 提供记忆工具，并内置了对ai（Vercel AI SDK）、openai、zod的依赖。
• 环境变量SUPERMEMORY_API_KEY会被 SDK 与中间件自动读取；withSupermemory中间件在既未传apiKey也未设置该环境变量时会直接抛出错误（见 vercel/index.ts 中SUPERMEMORY_API_KEY is not set的校验逻辑）。

3. 第一步配置全局设置：filterPrompt 与 LLM 过滤

官方文档强调"DO THIS FIRST"——在集成前先通过PATCH /v3/settings配置全局设置，这一步决定了后续写入的记忆能否被正确提取与过滤：

// PATCH https://api.supermemory.ai/v3/settings fetch('https://api.supermemory.ai/v3/settings', { method: 'PATCH', headers: { 'Authorization': `Bearer ${process.env.SUPERMEMORY_API_KEY}`, 'Content-Type': 'application/json', }, body: JSON.stringify({ shouldLLMFilter: true, filterPrompt: `This is a [your app description]. containerTag is [userId/orgId]. We store [what data].` }) })

参数含义：

• shouldLLMFilter: true：开启 LLM 过滤，让服务端在抽取记忆前用大模型判断内容是否值得记忆、是否符合你的应用语义。
• filterPrompt：一段描述你应用场景的自然语言提示词，模板为This is a [your app description]. containerTag is [userId/orgId]. We store [what data].。它告诉过滤模型"这是什么应用、记忆归属在哪个容器、你会存什么数据"，从而提升知识抽取的精准度。

配套的curl测试命令（官方 TESTING 一节）可用于快速验证配置是否生效：

# 1. 配置 settings curl -X PATCH https://api.supermemory.ai/v3/settings \ -H "Authorization: Bearer $SUPERMEMORY_API_KEY" \ -H "Content-Type: application/json" \ -d '{"shouldLLMFilter": true, "filterPrompt": "..."}'

4. containerTag 数据模型设计

containerTag是 Supermemory 的记忆隔离边界：同一个 tag 下的记忆彼此共享，不同 tag 之间互不可见。官方给出了三种典型模型：

仅用户（USER-ONLY）：

containerTag: userId

仅组织（ORG-ONLY）：

containerTag: orgId // 组织成员共享记忆

用户 + 组织并存（BOTH），三选一：

// 方案 A：每个「用户-组织」组合一个独立 tag（记忆最隔离） containerTag: `${userId}-${orgId}` // 方案 B：组织级 tag + 用户元数据（组织共享，但可通过 metadata 追踪用户） containerTag: orgId, metadata: { userId } // 方案 C：用户级 tag + 组织元数据（用户私享，组织信息存入 metadata） containerTag: userId, metadata: { orgId }

三种方案的取舍：方案 A 隔离最彻底但 tag 数量随组合数增长；方案 B 便于组织内共享但用户间过滤依赖 metadata；方案 C 保护用户隐私但组织维度需要额外聚合。选择后必须保证与第 3 节filterPrompt中填写的 tag 语义一致（官方 KEY POINTS 第 7 条明确要求"containerTag should match what you put in filterPrompt"）。

从源码看，@supermemory/tools对 tag 的处理也支持更灵活的配置：getContainerTags（tools-shared.ts）规定projectId与containerTags二者只能传其一，projectId会被自动转换为sm_project_${projectId}前缀格式；若两者都不传，则回退到默认值sm_project_default。

5. 集成代码：四种方式任选

5.1 方式一：Vercel AI SDK（推荐用于 Agent 流）

官方提供两种用法，均在@supermemory/tools/ai-sdk子路径导出：

选项 1：Agent 工具（工具调用模式，适合 agentic 工作流）

import { streamText } from 'ai' import { anthropic } from '@ai-sdk/anthropic' import { supermemoryTools } from '@supermemory/tools/ai-sdk' const result = await streamText({ model: anthropic('claude-3-5-sonnet-20241022'), prompt: userMessage, tools: supermemoryTools(process.env.SUPERMEMORY_API_KEY, { containerTags: [userId] }) }) // Agent 将自动获得 searchMemories、addMemory、getProfile、 // documentList、documentDelete、documentAdd、memoryForget 等工具

从源码（ai-sdk.ts 的supermemoryTools导出）可见，这 7 个工具内部统一使用client.search({ searchMode: 'hybrid' })、client.add、client.profile、client.documents.*等底层 API，并设置了 30 秒超时与最多 2 次重试（CLIENT_OPTIONS），避免慢 API 拖垮整个 agent 回合；searchMemories的limit被限制在 1～50 之间，超出范围会被clampSearchLimit拉回（默认 10），搜索阈值默认0.6。

选项 2：Profile 中间件（自动上下文注入模式）

import { withSupermemory } from '@supermemory/tools/ai-sdk' const modelWithMemory = withSupermemory(anthropic('claude-3-5-sonnet-20241022'), { containerTag: userId, customId: 'conversation-1', }) const result = await generateText({ model: modelWithMemory, messages: [{ role: 'user', content: userMessage }] }) // 用户画像会被自动注入 system prompt

withSupermemory的实现（vercel/index.ts）是一个包装 Language Model 的 Proxy，可配置项比文档示例更丰富，完整参数如下：

底层行为（middleware.ts 与 memory-prompt.ts）：

• 每次用户新回合先调用POST /v4/profile拉取static+dynamic画像（预 LLM 阶段默认有 5 秒检索时间预算），并把结果注入 system prompt；
• 注入采用纯函数方式，不会修改原始参数；若已存在 system prompt 则替换其中的记忆上下文，否则新建一条 system prompt；
• 记忆按回合缓存（memoryCache，key 由 containerTag、customId、mode、用户消息共同构成），工具调用循环内不重复请求 API；
• 模型回复完成后（含流式场景的flush阶段），通过POST /v4/conversations把整段对话（含图片消息，可选含工具调用）按customId归组保存为一份文档，实现"每轮自动记忆"。

5.2 方式二：直接使用 SDK（启用画像）

import Supermemory from 'supermemory' const client = new Supermemory() // 每次 LLM 调用前： const { profile, searchResults } = await client.profile({ containerTag: userId, q: userMessage // 选方案 A（一次调用）时传入；选方案 B（分开调用）时省略 }) // 组装上下文 const context = ` Static facts: ${profile.static.join('\n')} Recent context: ${profile.dynamic.join('\n')} ${searchResults ? `Memories: ${searchResults.results.map(r => r.content).join('\n')}` : ''} ` // 发送给 LLM const messages = [ { role: 'system', content: `User context:\n${context}` }, { role: 'user', content: userMessage } ] // LLM 回复后写入记忆： await client.memories.add({ content: `user: ${userMessage}\nassistant: ${response}`, containerTag: userId })

这里profile.static（静态事实，如长期偏好、稳定属性）与profile.dynamic（动态上下文，如最近动态、近期交互）正是第 1 节提到的"用户画像"。官方 SDK 文档（supermemory-sdk.mdx）中的快速开始也印证了同样的用法：client.add写入、client.search检索、client.profile读取画像。

5.3 方式三：直接使用 SDK（不启用画像）

import Supermemory from 'supermemory' const client = new Supermemory() // 检索相关记忆 const results = await client.search({ q: userMessage, containerTag: userId, searchMode: 'hybrid', // 同时搜索记忆与文档分块 limit: 5 }) // 组装上下文 const context = results.results.map(r => r.content).join('\n') const messages = [ { role: 'system', content: `Relevant context:\n${context}` }, { role: 'user', content: userMessage } ] // 存储对话 await client.memories.add({ content: `user: ${userMessage}\nassistant: ${response}`, containerTag: userId })

5.4 Python 版本

from supermemory import Supermemory client = Supermemory() # 启用画像时： profile_data = client.profile( container_tag=user_id, q=user_message # 选方案 A 时传入，方案 B 时省略 ) context = f""" Static: {chr(10).join(profile_data.profile.static)} Dynamic: {chr(10).join(profile_data.profile.dynamic)} """ # 存储对话 client.add(content=f"user: {user_message}\nassistant: {response}", container_tag=user_id)

5.5 直接调用 HTTP API（无 SDK 场景）

# 写入记忆 curl -X POST https://api.supermemory.ai/v3/documents \ -H "Authorization: Bearer $SUPERMEMORY_API_KEY" \ -H "Content-Type: application/json" \ -d '{"content": "conversation", "containerTag": "userId"}' # 获取画像 curl -X POST https://api.supermemory.ai/v4/profile \ -H "Authorization: Bearer $SUPERMEMORY_API_KEY" \ -H "Content-Type: application/json" \ -d '{"containerTag": "userId", "q": "search query"}' # 检索 curl -X POST https://api.supermemory.ai/v4/search \ -H "Authorization: Bearer $SUPERMEMORY_API_KEY" \ -H "Content-Type: application/json" \ -d '{"q": "query", "containerTag": "userId", "searchMode": "hybrid"}'

对照 memory-client.ts 的supermemoryProfileSearch实现可以看到，/v4/profile请求体支持可选的q（查询文本）与include: ["static", "dynamic"]（指定返回画像分区），这正是中间件模式一次请求同时拿到画像与搜索结果的底层协议。

6. 文件上传：自动抽取 PDF、图片与视频

如果应用需要用户上传文件，官方提供了异步文件接入方式：

// 文件会被自动抽取（PDF 文本、图片 OCR、视频转写） const formData = new FormData() formData.append('file', fileBlob) formData.append('containerTag', userId) await fetch('https://api.supermemory.ai/v3/documents/file', { method: 'POST', headers: { 'Authorization': `Bearer ${process.env.SUPERMEMORY_API_KEY}`, 'Content-Type': 'application/json', // 注意：此处为 FormData，实际场景中不应手动设置 Content-Type，交由浏览器/运行时自动生成 multipart 边界 }, body: formData }) // 处理是异步的——在确认可检索前先查询状态： // GET /v3/documents/{documentId}

官方明确提示：上传后文件处理是异步的，必须轮询GET /v3/documents/{documentId}确认处理进入终态（源码assertDocumentCanBeDeleted中用到的状态集合为done/failed，见 tools-shared.ts）之后，抽取出的记忆才会进入画像与检索结果。

7. 搜索模式与元数据过滤

7.1 两种搜索模式

// HYBRID（推荐）—— 同时检索抽取出的记忆 + 原始文档分块 searchMode: 'hybrid' // MEMORIES ONLY —— 仅检索已抽取的记忆，不含原文 searchMode: 'memories'

hybrid是官方默认推荐：它把"从对话/文档中提炼出的高层记忆"（memory字段）与"命中的原文分块"（chunk字段）一起返回，兼顾概括性与可溯源性；memories模式则只返回纯记忆。

7.2 元数据过滤（二级过滤）

await client.search({ q: query, containerTag: userId, filters: { AND: [ { key: 'type', value: 'conversation', type: 'string_equal' }, { key: 'timestamp', value: '2024', type: 'string_contains' } ] } })

filters.AND数组内的条件按key（元数据键）、value（匹配值）、type（匹配类型，如string_equal精确相等、string_contains包含匹配）组合成逻辑与关系，适合在 containerTag 之外做更细粒度的二次筛选（如只查某类型、某时间段的数据）。

8. 集成要点速览（KEY POINTS）

官方在文档末尾总结了 7 条核心要点，本文结合源码补充印证如下：

1. 先配置 settings 与 filterPrompt（第 3 节），再谈集成。
2. 用户画像 = 自动维护的用户事实，分为profile.static（静态）与profile.dynamic（动态）。
3. profile({ containerTag, q })一次调用同时返回画像 + 搜索结果，减少一次往返。
4. 搜索模式二选一：hybrid（推荐，记忆 + 文档分块）或memories（仅记忆）。
5. 文件抽取完全自动，无需额外配置，只需等待异步处理完成。
6. 每次交互后都要保存对话（memories.add或中间件的addMemory: 'always'），记忆系统才有足够素材持续积累。
7. containerTag 必须与 filterPrompt 中声明的语义保持一致，否则过滤与检索会错位。

9. 端到端验证脚本

官方 TESTING 一节提供了可直接复制的三段 curl，构成一个最小验证闭环：

# 1. 配置 settings curl -X PATCH https://api.supermemory.ai/v3/settings \ -H "Authorization: Bearer $SUPERMEMORY_API_KEY" \ -H "Content-Type: application/json" \ -d '{"shouldLLMFilter": true, "filterPrompt": "..."}' # 2. 写入测试记忆 curl -X POST https://api.supermemory.ai/v3/documents \ -H "Authorization: Bearer $SUPERMEMORY_API_KEY" \ -H "Content-Type: application/json" \ -d '{"content": "Test", "containerTag": "test_user"}' # 3. 读取画像验证 curl -X POST https://api.supermemory.ai/v4/profile \ -H "Authorization: Bearer $SUPERMEMORY_API_KEY" \ -H "Content-Type: application/json" \ -d '{"containerTag": "test_user"}'

执行顺序即验证顺序：先配好过滤规则 → 写入一条测试内容 → 通过/v4/profile观察画像中是否出现对应的事实。如果第 3 步返回的profile.static/profile.dynamic中能看到由第 2 步内容抽取出的记忆，则整条链路（写入 → 后台抽取 → 画像检索）已打通。

10. 进一步深入

• 完整 SDK 操作清单（写入、元数据、过滤、文档管理、删除）：supermemory-sdk.mdx
• 记忆 / 画像 / 搜索的 API 参考：memories.mdx、search.mdx、profiles.mdx
• containerTag 与多租户隔离模型：container-tags.mdx、multi-tenancy.mdx
• 自托管部署后如何替换 API 地址（SDK 传baseURL/base_url）：self-hosting/overview.mdx
• @supermemory/tools的 AI SDK 工具与中间件实现：ai-sdk.ts、vercel/index.ts

【免费下载链接】supermemoryMemory and context engine + app that is extremely fast, scalable, and can be run fully locally. The Memory API for the AI era.项目地址: https://gitcode.com/GitHub_Trending/su/supermemory