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 个问题它们直接决定后续每一步的配置方式你在构建什么个人聊天助手 / 团队知识库 / 客服机器人 / 文档问答 / 其他——不同场景对应不同的记忆写入与检索节奏。你希望如何集成可选路径包括 Vercel AI SDKsupermemory/tools、OpenAI 插件、官方 SDKnpm 包supermemory或 pip 包supermemory、以及直接调用 HTTP API。数据模型是怎样的只有个人用户 → 使用containerTag: userId只有组织 → 使用containerTag: orgId组织成员共享记忆两者都有 → 需要额外设计组合策略见第 3 节。是否需要用户画像User Profiles用户画像是系统自动维护的关于用户的事实集合喜欢什么、正在做什么、偏好如何官方推荐启用通过client.profile()获取上下文。如何检索上下文方案 A单次调用同时包含搜索profile({ containerTag, q: userMessage })方案 B分开调用profile()取事实search()取记忆。这 5 个问题的答案分别对应本指南第 26 节的安装、全局设置、数据模型、集成代码与检索配置。2. 安装依赖与获取 API Key官方推荐的最小安装命令如下# 在 https://console.supermemory.ai 获取 API Key npm install supermemory # TypeScript / JavaScript SDKPython 请用: pip install supermemory # 使用 Vercel AI SDK 集成时额外安装: npm install supermemory/tools # 配置环境变量 export SUPERMEMORY_API_KEYsm_...几点值得说明两个官方 SDK 为 npm 包supermemoryTypeScript与 PyPI 包supermemoryPython分别对应 SDK 文档 中的快速开始示例。supermemory/tools是面向 AI 框架的工具包其 package.json 显示它同时为 AI SDK、OpenAI、Mastra、VoltAgent 提供记忆工具并内置了对aiVercel 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-ONLYcontainerTag: userId仅组织ORG-ONLYcontainerTag: 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 的处理也支持更灵活的配置getContainerTagstools-shared.ts规定projectId与containerTags二者只能传其一projectId会被自动转换为sm_project_${projectId}前缀格式若两者都不传则回退到默认值sm_project_default。5. 集成代码四种方式任选5.1 方式一Vercel AI SDK推荐用于 Agent 流官方提供两种用法均在supermemory/tools/ai-sdk子路径导出选项 1Agent 工具工具调用模式适合 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被限制在 150 之间超出范围会被clampSearchLimit拉回默认 10搜索阈值默认0.6。选项 2Profile 中间件自动上下文注入模式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 promptwithSupermemory的实现vercel/index.ts是一个包装 Language Model 的 Proxy可配置项比文档示例更丰富完整参数如下参数默认值说明containerTag必填记忆检索的作用域用户 ID / 项目 IDcustomId必填用于把多轮消息归并到同一份对话文档的自定义 IDmodeprofile记忆检索模式profile只取画像不带查询过滤、query按用户消息语义相似度检索、full两者结合addMemoryalways是否在回复后自动保存对话记忆always/neverapiKey环境变量显式传入 API KeybaseUrlhttps://api.supermemory.ai自定义 API 地址自托管时使用includeToolCallsfalse是否把工具调用与结果一并写入记忆默认关闭避免大而低信号的 payload 污染知识抽取promptTemplate默认模板自定义记忆注入 system prompt 的格式skipMemoryOnErrortrue记忆检索失败时true降级为不带记忆直接调用模型false则向上抛错fail closed底层行为middleware.ts 与 memory-prompt.ts每次用户新回合先调用POST /v4/profile拉取staticdynamic画像预 LLM 阶段默认有 5 秒检索时间预算并把结果注入 system prompt注入采用纯函数方式不会修改原始参数若已存在 system prompt 则替换其中的记忆上下文否则新建一条 system prompt记忆按回合缓存memoryCachekey 由 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_taguser_id, quser_message # 选方案 A 时传入方案 B 时省略 ) context f Static: {chr(10).join(profile_data.profile.static)} Dynamic: {chr(10).join(profile_data.profile.dynamic)} # 存储对话 client.add(contentfuser: {user_message}\nassistant: {response}, container_taguser_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: memorieshybrid是官方默认推荐它把从对话/文档中提炼出的高层记忆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 条核心要点本文结合源码补充印证如下先配置 settings 与 filterPrompt第 3 节再谈集成。用户画像 自动维护的用户事实分为profile.static静态与profile.dynamic动态。profile({ containerTag, q })一次调用同时返回画像 搜索结果减少一次往返。搜索模式二选一hybrid推荐记忆 文档分块或memories仅记忆。文件抽取完全自动无需额外配置只需等待异步处理完成。每次交互后都要保存对话memories.add或中间件的addMemory: always记忆系统才有足够素材持续积累。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.mdxcontainerTag 与多租户隔离模型container-tags.mdx、multi-tenancy.mdx自托管部署后如何替换 API 地址SDK 传baseURL/base_urlself-hosting/overview.mdxsupermemory/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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考