企业官网建设流程全解析

@supermemory/tools 从 1.4.x 升级到 2.0.0 要改哪些代码

【免费下载链接】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/toolsv2.0.0 是一次破坏性升级（breaking release）：四个集成（Vercel AI SDK、OpenAI、Mastra、VoltAgent）的 API 统一为单一的配置对象签名，并统一了会话分组概念。如果你当前的代码还在用 1.4.x 的写法（位置参数传containerTag、conversationId或threadId分组会话），升级到 2.0.0 后这些调用点都会失效。官方文档明确建议：更新调用并重新测试后再在生产中升级依赖。

破坏性改动一览

升级前需要SUPERMEMORY_API_KEY（或调用时传apiKey），这一点两个版本都要求，不受本次升级影响。

第一步：升级依赖

npm install @supermemory/tools@^2.0.0

第二步：找出所有需要改的调用点

在代码库中搜索以下符号，定位所有受影响的调用点：

• withSupermemory(
• SupermemoryInputProcessor
• SupermemoryOutputProcessor
• createSupermemoryProcessor
• createSupermemoryOutputProcessor

然后把改动按集成类型逐一处理。

Vercel AI SDK：位置参数改为配置对象

v1.4.x 的旧写法：

// v1.4.x import { withSupermemory } from '@supermemory/tools/ai-sdk'; const model = withSupermemory(openai('gpt-4'), 'user-123', { conversationId: 'conv-456', mode: 'full', });

改为 v2.0.0：

// v2.0.0 import { withSupermemory } from '@supermemory/tools/ai-sdk'; const model = withSupermemory(openai('gpt-4'), { containerTag: 'user-123', customId: 'conv-456', mode: 'full', });

注意两点：

• 原来的第二个位置参数'user-123'移入选项对象，字段名变为containerTag；
• conversationId改名为customId，且必填——传空字符串或省略会在构造时直接抛错（customId is required — provide a non-empty string to group messages into a single document）。

OpenAI SDK：同样的签名迁移

// v1.4.x import { withSupermemory } from '@supermemory/tools/openai'; const client = withSupermemory(openai, 'user-123', { conversationId: 'conv-456', });

// v2.0.0 import { withSupermemory } from '@supermemory/tools/openai'; const client = withSupermemory(openai, { containerTag: 'user-123', customId: 'conv-456', });

OpenAI 集成中containerTag和customId都会被校验，缺失时抛出带明确错误信息的异常。

Mastra：构造函数和工厂函数都改为单一选项参数，threadId 消失

v1.4.x：

// v1.4.x import { SupermemoryInputProcessor, createSupermemoryOutputProcessor, } from '@supermemory/tools/mastra'; const input = new SupermemoryInputProcessor('user-123', { mode: 'full', }); const output = createSupermemoryOutputProcessor('user-123', { threadId: 'conv-456', addMemory: 'always', });

v2.0.0：

// v2.0.0 import { SupermemoryInputProcessor, createSupermemoryOutputProcessor, } from '@supermemory/tools/mastra'; const input = new SupermemoryInputProcessor({ containerTag: 'user-123', customId: 'conv-456', mode: 'full', }); const output = createSupermemoryOutputProcessor({ containerTag: 'user-123', customId: 'conv-456', });

threadId已移除，一律用customId替代。有一个服务端场景的行为值得注意：Mastra 的RequestContext中的 thread ID 仍然优先于构造时传入的customId——后者只作为没有 per-request thread ID 时的回退值（源码实现见 getEffectiveCustomId）。

VoltAgent：调用形状不变，但有两处行为变化

VoltAgent 本来就使用配置对象签名，所以调用形状不需要改。v2.0.0 带来两个行为修复：

• verbose: true现在真正生效（v1.4.x 中硬编码为false）。如果你此前隐式依赖verbose: false而传了verbose: true，升级后会出现日志，按需调整。
• 当mode: "profile"下设置了高级搜索参数（threshold、limit、rerank、rewriteQuery、filters、include、searchMode）时，会记录一条运行时警告——这些参数在 profile 模式下会被忽略。

新默认值：addMemory 从 "never" 变为 "always"

四个集成的addMemory默认值都从"never"变成了"always"。如果你的 v1.4.x 代码依赖旧的"never"默认行为（只检索、不写入新记忆），必须显式声明：

const model = withSupermemory(openai('gpt-4'), { containerTag: 'user-123', customId: 'conv-456', addMemory: 'never', // preserve v1.4.x behavior });

会话持久化路径变了

v1.4.x 中 Vercel 中间件在没有传conversationId时会回退到client.add，并使用合成的customId。v2.0.0 中由于customId必填，所有会话持久化统一走/v4/conversations端点（通过addConversation），没有回退路径（实现见 conversations-client.ts）。

验证：跑一遍测试套件

官方迁移清单的最后一项就是运行你的测试套件。原因是 v2.0.0 的校验都发生在构造时——缺失containerTag或customId、customId为空字符串，都会在withSupermemory(...)或 Processor 构造那一刻立即抛错，不需要等实际调用模型才能发现。也就是说，只要代码能构造成功、测试通过，字段层面的迁移就完成了；再配合实际跑一次对话请求确认记忆检索与写入正常，就可以把版本推到生产。

继续深入的参考

• Vercel AI SDK 集成文档
• OpenAI 集成文档
• Mastra 集成文档
• VoltAgent 集成文档
• 升级指南原文：tools-v2-upgrade.mdx

【免费下载链接】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