Hindsight × Vercel AI SDK为 AI Agent 接入长期记忆的五个即用型工具【免费下载链接】hindsightHindsight: Agent Memory That Learns项目地址: https://gitcode.com/GitHub_Trending/hindsight2/hindsightHindsight 的vectorize-io/hindsight-ai-sdk包为 Vercel AI SDK 提供了一组开箱即用的记忆工具让基于generateText、streamText、ToolLoopAgent构建的 AI Agent 具备记住、召回、反思长期记忆的能力。本篇指南以 Hindsight 官方 AI SDK 集成文档为核心结合仓库内 TypeScript 源码与测试用例完整讲解安装配置、五种记忆工具的用法与全部构造参数帮助你快速为多用户应用落地持久化记忆能力。安装在项目目录下执行npm install vectorize-io/hindsight-ai-sdk vectorize-io/hindsight-client ai根据仓库中的 package.json 声明当前集成包版本 0.5.1的运行时约束如下peerDependencies要求ai为^6.0.0zod为^3.0.0 || ^4.0.0zod 由 AI SDK 的 tool 定义使用安装ai时通常会自动带上如需显式声明可一并安装engines.node 22请确保运行环境满足该 Node 版本要求包以 ESM 形式发布type: module导出dist/index.js与dist/index.d.ts。快速开始创建记忆工具vectorize-io/hindsight-ai-sdk的核心导出是createHindsightTools。用法是先创建 Hindsight 客户端再传入bankId生成工具集。import { HindsightClient } from vectorize-io/hindsight-client; import { createHindsightTools } from vectorize-io/hindsight-ai-sdk; const client new HindsightClient({ baseUrl: http://localhost:8888 }); const tools createHindsightTools({ client, bankId: user-123, });关键概念说明bankId标识记忆存储空间即这个会话属于谁。对于 C 端应用通常直接使用用户 ID不同bankId之间的记忆互相隔离。bankId在创建时被固定从源码看createHindsightTools将bankId闭包进每个工具的execute内五个工具的输入 schemaZod中都不包含bankId字段因此 Agent 无法自行切换记忆空间——这正是安全边界的来源见 tools/index.ts。baseUrl指向 Hindsight API 服务地址示例中的http://localhost:8888为本地服务地址实际部署时请替换为你的 Hindsight 实例地址本地嵌入模式默认监听 8000 端口具体以运行环境为准。多用户应用提示bankId是创建时刻的闭包变量因此在多租户场景下应在请求处理器内部创建tools让每次请求都捕获正确的bankId。下文Next.js Route Handler一节给出了标准做法。使用方式四种主流接入场景工具创建后即可像普通 AI SDK 工具一样使用与任何模型 Provider 兼容。以下示例均可直接复制运行。1. 与generateText搭配一次性生成import { generateText } from ai; import { openai } from ai-sdk/openai; const { text } await generateText({ model: openai(gpt-4o), tools, maxSteps: 5, system: You are a helpful assistant with long-term memory., prompt: Remember that I prefer dark mode and large fonts., });maxSteps: 5允许模型在单次调用中多轮调用工具——Agent 先通过retain记住用户偏好再继续回答。2. 与streamText搭配流式输出import { streamText } from ai; const result streamText({ model: openai(gpt-4o), tools, maxSteps: 5, system: You are a helpful assistant with long-term memory., prompt: What are my display preferences?, }); for await (const chunk of result.textStream) { process.stdout.write(chunk); }当用户在新会话中询问我的显示偏好是什么时Agent 会先调用recall检索记忆再把结果组织进回答中流式输出。3. 与ToolLoopAgent搭配显式循环 Agentimport { generateText, ToolLoopAgent, stepCountIs } from ai; import { openai } from ai-sdk/openai; import { HindsightClient } from vectorize-io/hindsight-client; import { createHindsightTools } from vectorize-io/hindsight-ai-sdk; const client new HindsightClient({ baseUrl: process.env.HINDSIGHT_API_URL! }); const agent new ToolLoopAgent({ model: openai(gpt-4o), tools: createHindsightTools({ client, bankId: user-123 }), stopWhen: stepCountIs(10), system: You are a helpful assistant with long-term memory., }); const result await agent.generate({ prompt: Remember that my favorite editor is Neovim, });ToolLoopAgent会持续循环调用工具直至满足stopWhen条件适合需要记忆 → 推理 → 再记忆多轮交互的复杂任务。4. 在 Next.js Route Handler 中多用户标准做法// app/api/chat/route.ts import { streamText } from ai; import { openai } from ai-sdk/openai; import { HindsightClient } from vectorize-io/hindsight-client; import { createHindsightTools } from vectorize-io/hindsight-ai-sdk; const hindsightClient new HindsightClient({ baseUrl: process.env.HINDSIGHT_API_URL!, }); export async function POST(req: Request) { const { messages, userId } await req.json(); // Tools are created per-request, closing over the current users bankId const tools createHindsightTools({ client: hindsightClient, bankId: userId, }); return streamText({ model: openai(gpt-4o), tools, maxSteps: 5, system: You are a helpful assistant with long-term memory., messages, }).toDataStreamResponse(); }注意Hindsight 客户端可以在模块顶层创建并复用但createHindsightTools必须放在请求处理器内部——这样每个请求都能用请求体中的userId作为bankId实现用户级记忆隔离。五个记忆工具参考createHindsightTools一共注册五个工具职责覆盖记住 → 召回 → 反思 → 取回结构化产物的完整记忆生命周期工具Agent 提供的输入构造函数控制的选项retaincontent、documentId、timestamp、contextasync、tags、metadatarecallquery、queryTimestampbudget、types、maxTokens、includeEntities、includeChunksreflectquery、contextbudgetgetMentalModelmentalModelId—getDocumentdocumentId—为什么这样拆分这是该集成最重要的设计原则语义输入交给 Agent记住什么内容、搜索什么信息属于模型的自主决策因此暴露为工具参数Zod schema 中仅有这些字段见 tools/index.ts基础设施决策交给应用成本预算budget、打标策略tags、异步模式async、元数据metadata属于工程控制项由开发者在构造createHindsightTools时统一固化防止 Agent 随意放大成本。对应源码中五个工具的 Zod 输入定义retaincontent必填、documentId/timestamp/context可选recallquery必填、queryTimestamp可选ISO 格式用于从某个时间点检索reflectquery必填、context可选getMentalModelmentalModelId必填getDocumentdocumentId必填。构造函数选项详解createHindsightTools除client与bankId外的所有选项均可选每个工具的选项按工具名分组传入const tools createHindsightTools({ client, bankId: userId, retain: { async: true, // fire-and-forget (default: false) tags: [env:prod, app:support], // always attached to every retained memory metadata: { version: 2.0 }, // always attached to every retained memory }, recall: { budget: high, // processing depth: low | mid | high (default: mid) types: [experience, world], // restrict to these fact types (default: all) maxTokens: 2048, // cap token budget (default: API default) includeEntities: true, // include entity observations (default: false) includeChunks: true, // include raw source chunks (default: false) }, reflect: { budget: mid, // processing depth (default: mid) }, });retain选项选项类型默认值说明asyncbooleanfalse即发即忘——不等待记忆摄取完成就返回适合对延迟敏感的高频写入tagsstring[]—附加到每条被记忆内容上的标签metadataRecordstring, string—附加到每条被记忆内容上的元数据descriptionstring内置覆盖展示给模型的工具描述从源码看retain的execute会把 Agent 提供的documentId、timestamp、context与构造层的tags、metadata、async合并后透传给client.retain(bankId, content, options)内置描述为Store information in long-term memory...用于引导模型在用户表达偏好、事实、经历时主动调用见 tools/index.ts。recall选项选项类型默认值说明budgetlow \| mid \| highmid控制检索深度与延迟的权衡types(world \| experience \| observation)[]全部限制只返回这些事实类型maxTokensnumberAPI 默认限制返回结果的总 token 数includeEntitiesbooleanfalse在结果中包含实体观察entity observationsincludeChunksbooleanfalse在结果中包含原始源文档分块raw source chunksdescriptionstring内置覆盖工具描述事实类型world/experience/observation与budget的low/mid/high在源码中分别由FactTypeSchema与BudgetSchema两个 Zod enum 定义见 tools/index.ts。测试用例验证未指定budget时默认透传midtypes与maxTokens未指定时透传undefined由 API 决定默认行为includeEntities、includeChunks默认为false见 tools/index.test.ts。reflect选项选项类型默认值说明budgetlow \| mid \| highmid控制综合推理深度与延迟maxTokensnumberAPI 默认响应的最大 token 数descriptionstring内置覆盖工具描述reflect与recall的区别在于recall是检索——把相关记忆片段找出来reflect是反思——基于记忆做综合推理输出洞察性结论并可通过basedOn返回依据来源记忆、心理模型、指令。源码中对空响应提供了No insights available yet.兜底文案见 tools/index.ts。提示getMentalModel与getDocument也各支持一个description选项用于覆盖工具描述前者用于读取由记忆综合而成的心理模型比检索原始记忆更快更省 token后者用于按 ID 精确取回存储的结构化文档如用户资料、应用状态未命中时返回null。二者除description外无其他构造选项因此原表格中对应的构造函数控制项列为空。源码视角createHindsightTools的实现与验证该集成在仓库中的完整实现位于 hindsight-integrations/ai-sdk/src/tools/index.ts配套测试位于 hindsight-integrations/ai-sdk/src/tools/index.test.ts可以从中确认以下实现事实1. 基于ai包的tool()工厂构建。每个工具通过toolInput, Output({ description, inputSchema, execute })定义inputSchema全部使用 Zod 描述AI SDK 会自动将 schema 转为模型可见的工具参数声明。2. 返回值做了驼峰化包装。例如client.retain返回的items_count在工具输出中被规范为itemsCountreflect的based_on规范为basedOn——这保证了 AI SDK 侧 TypeScript 类型的整洁对应RetainResponse、ReflectResponse等导出类型。3. 默认值集中在构造层。recall/reflect的budget默认midretain的async默认false。测试中专门有一组 budget defaults 用例逐一验证了这些默认透传行为见 tools/index.test.ts。4. 错误按需向上传播。测试显示client.retain/recall/reflect/getMentalModel/getDocument抛出的异常会原样传播给 AI SDK 运行时见 tools/index.test.ts上层可通过 AI SDK 的错误处理机制统一捕获。5. 记忆隔离由闭包保证。测试专门验证了无论 Agent 传入什么bankId始终取构造时的值见 tools/index.test.ts。此外包主入口 src/index.ts 对外导出了createHindsightTools、BudgetSchema、以及RecallResult、ReflectFact、ReflectResponse、RetainResponse、EntityState、ChunkData等类型方便应用侧编写类型安全的工具调用与结果处理逻辑。工程实践与注意事项按请求创建工具而不是按进程创建。这是多用户应用唯一正确的姿势客户端可复用工具集必须在请求内创建以捕获正确的bankId参考上文 Next.js 示例。高写入量场景开启async: true。同步retain会等待摄取完成阻塞 Agent 的工具调用回合对于偏好、浏览记录等高频、非关键写入异步即发即忘模式能显著降低响应延迟。用budget控制成本与延迟。low适合延迟敏感但结果要求不高的场景high适合需要深度检索/综合推理的场景。默认mid是大多数情况下的稳妥起点。善用tags与types做记忆分层。例如给生产环境的写入统一打上env:prod标签检索时按事实类型过滤可以让召回结果更精准、上下文窗口利用率更高。保持 Agent 与记忆服务同生命周期。在本地开发时可先启动 Hindsight 服务嵌入模式无需额外数据库依赖再将baseUrl/apiUrl指向该服务生产环境建议通过环境变量注入地址避免把地址硬编码进代码。版本与变更记录集成包的版本变更记录见 changelog/integrations/ai-sdk.md0.4.20 版本首次引入 AI SDK 集成并增强工具支持0.5.0 版本改善与 Hindsight Client v0.5.2 的兼容性0.5.1 版本修正了 reflect 工具类型定义与 OpenAPI 规范的匹配。升级集成包时建议同步关注vectorize-io/hindsight-client的版本配套关系。进一步阅读集成包 README 与完整示例hindsight-integrations/ai-sdk/README.md、hindsight-docs/examples/integrations/ai-sdk.ts集成文档站版本hindsight-docs/docs-integrations/ai-sdk.mdx核心实现与测试hindsight-integrations/ai-sdk/src/tools/index.ts、hindsight-integrations/ai-sdk/src/tools/index.test.ts【免费下载链接】hindsightHindsight: Agent Memory That Learns项目地址: https://gitcode.com/GitHub_Trending/hindsight2/hindsight创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考