Voltagent 内存存储指南：InMemoryStorageAdapter 的默认机制、配置与适用边界

人工智能AI AgentAgent 框架后端多智能体RAG工具调用Agent 记忆【免费下载链接】voltagentAI Agent Engineering Platform built on an Open Source TypeScript AI Agent Framework项目地址https://gitcode.com/gh_mirrors/vo/voltagent点击查看免费下载本文基于 Voltagent 官方文档《In-Memory Storage》展开系统讲解InMemoryStorageAdapter的默认行为、显式配置方式、会话存储与工作记忆Working Memory的底层实现并结合仓库源码剖析其数据结构与查询逻辑。读完本文你将掌握如何在开发测试、无状态部署和快速原型场景中正确使用内存存储以及何时应当切换到 LibSQL、PostgreSQL 等持久化适配器。什么是 In-Memory StorageInMemoryStorageAdapter是 Voltagent 提供的最简存储实现将对话历史保存在应用进程内存中。它不依赖任何数据库或外部基础设施写入即生效、读取无延迟但应用重启后所有数据都会丢失。在 packages/core/src/memory/adapters/storage/in-memory.ts 中该适配器被明确定位为 Simple implementation for testing and development面向测试与开发的简单实现其内部通过若干 JavaScript 原生数据结构完成存储Recordstring, Recordstring, StoredUIMessage[]以userId → conversationId → 消息数组的嵌套结构保存全部消息Mapstring, Conversation会话元数据Mapstring, UserInfo用户级数据含用户级工作记忆Mapstring, WorkflowStateEntry与按 workflow 建立的索引工作流状态Mapstring, Mapstring, ConversationStepRecord[]会话步骤记录。从源码结构看这套存储五脏俱全覆盖了StorageAdapter接口定义于 packages/core/src/memory/types.ts要求的消息、会话、工作记忆、工作流状态四大类操作因此它不仅是教学玩具更是可完整驱动 Agent 对话闭环的轻量实现。默认行为不配置 memory 也不等于无记忆Voltagent 的 Agent 在未提供memory选项时默认使用内存存储这是官方明确的行为约定import { Agent } from voltagent/core; // Uses InMemoryStorageAdapter automatically const agent new Agent({ name: Assistant, instructions: Help users with questions., model: openai/gpt-4o-mini, });注意一个容易被忽略的细节省略memory并不会禁用记忆功能。想要一个真正无状态的 Agent必须显式传入memory: false。这一默认行为在 packages/core/src/memory/manager/memory-manager.ts 的构造逻辑中得到了印证当memory参数为false时对话记忆被显式关闭为undefined时则自动new Memory({ storage: new InMemoryStorageAdapter() })。也就是说什么都没写 与 明确关掉记忆 在 Voltagent 中是两种完全不同的状态前者默认走内存存储。显式配置精确控制存储实例当你需要显式声明内存存储、或将来要无缝替换为其他适配器时可以手动构造Memoryimport { Agent, Memory, InMemoryStorageAdapter } from voltagent/core; const memory new Memory({ storage: new InMemoryStorageAdapter(), }); const agent new Agent({ name: Assistant, model: openai/gpt-4o-mini, memory, });这种存储适配器 Memory 管理器的分层设计使切换存储后端只需替换storage一项即可——例如将new InMemoryStorageAdapter()换成 LibSQL 或 PostgreSQL 适配器其余调用代码完全不变。核心特性会话存储按 userId 与 conversationId 组织内存存储的消息按userId与conversationId双重维度组织其addMessage实现见 in-memory.ts会按需惰性创建userId与conversationId两级容器并在写入时补充createdAt、userId、conversationId元数据若消息id已存在则执行原地更新而非追加避免重复写入。getMessages则支持丰富的过滤能力in-memory.tsroles按消息角色user / assistant 等过滤before/after按createdAt时间窗口过滤limit取最近 N 条从尾部切片默认按创建时间升序排列保证对话流的自然顺序。此外接口还要求实现deleteMessages按消息 ID 批量删除、clearMessages按会话或用户整体清空、createConversation/updateConversation/deleteConversation、queryConversations/countConversations支持userId、resourceId过滤、按created_at/updated_at/title排序及分页等完整会话管理能力。关于消息裁剪内存存储不会自动修剪消息——所有消息都会原样保留在内存中直到进程退出或被显式清除。这意味着长对话会持续累积需要自行评估内存占用。工作记忆Working Memory内存存储同时支持会话级conversation与用户级user两种作用域的工作记忆const memory new Memory({ storage: new InMemoryStorageAdapter(), workingMemory: { enabled: true, scope: conversation, // or user }, });从源码实现看会话级工作记忆被保存在Conversation.metadata.workingMemory字段中in-memory.ts用户级工作记忆则保存在独立的UserInfo.metadata.workingMemory中setWorkingMemory在用户不存在时会自动创建用户记录。关于工作记忆的完整配置细节可参考 Working Memory 指南。语义搜索开发阶段配合 InMemoryVectorAdapter开发阶段如需为对话内容做向量检索可将InMemoryStorageAdapter与InMemoryVectorAdapter组合使用import { Memory, InMemoryVectorAdapter, InMemoryStorageAdapter } from voltagent/core; const memory new Memory({ storage: new InMemoryStorageAdapter(), embedding: openai/text-embedding-3-small, vector: new InMemoryVectorAdapter(), });InMemoryVectorAdapter的实现位于 packages/core/src/memory/adapters/vector/in-memory.ts其注释明确标注适用于开发、测试与小型数据集少于 1 万向量。该适配器的关键行为包括维度校验首个向量写入后锁定维度后续写入或查询若维度不一致将抛出Vector dimension mismatch错误余弦相似度检索search支持limit默认 10、threshold默认 0与filter按 metadata 精确匹配过滤内部将相似度归一化为 0–1 的score并同步输出distance 1 - similarity返回防御性拷贝store、get均复制向量数组与 metadata防止外部修改污染存储统计能力getStats()返回向量数量、维度以及估算内存占用按count × dimensions × 4字节粗略计算。与存储数据一样向量数据在重启后同样全部丢失。需要持久化向量时应改用LibSQLVectorAdapter参见 LibSQL / SQLite 指南语义检索的完整工作方式可参考 Semantic Search 文档。典型使用场景开发与测试免数据库验证 Agent 逻辑单元测试与本地调试时内存存储让你无需搭建任何数据库即可验证 Agent 逻辑import { Agent, Memory, InMemoryStorageAdapter } from voltagent/core; const testAgent new Agent({ name: Test Assistant, model: openai/gpt-4o-mini, memory: new Memory({ storage: new InMemoryStorageAdapter(), }), }); // Test conversations without persistence await testAgent.generateText(Test message, { memory: { userId: test-user, conversationId: test-conversation, }, });Voltagent 官方测试也验证了该适配器的行为完整性在 packages/core/src/memory/adapters/storage/in-memory.spec.ts 中覆盖了会话创建重复 ID 抛ConversationAlreadyExistsError、自动填充createdAt/updatedAt、深拷贝防外部篡改、会话查询与更新不存在时抛ConversationNotFoundError、消息增删改查、工作记忆读写等大量用例可作为你编写自己应用测试时的行为参考。无状态部署Serverless 与临时容器在函数即用即焚的 Serverless 场景或短生命周期的临时容器中持久化往往不是必需项默认的内存存储恰好省去了外部依赖// Cloud function handler export async function handler(event) { const agent new Agent({ name: Serverless Assistant, model: openai/gpt-4o-mini, // Default in-memory storage }); return await agent.generateText(event.message, { memory: { userId: event.userId, conversationId: event.sessionId, }, }); }需要提醒的是此类部署中每次函数冷启动都是全新记忆跨调用上下文需依赖外部会话管理如数据库、Redis 或托管记忆服务内存存储只承担单次调用内的记忆职责。演示与示例零基础设施依赖的原型快速原型、Demo、课程示例等场景下内存存储可以让你在 30 秒内跑通一个带记忆的 Agent无需配置任何连接字符串。官方大量示例如 examples 目录下的各类with-*示例正是依赖这一默认行为降低了上手门槛。局限性为什么它不适合生产内存存储的边界非常清晰官方文档明确列出了三点限制无持久化进程重启后所有会话、消息、工作记忆与向量数据全部丢失内存占用消息量大时直接消耗应用内存且无自动裁剪机制不面向生产生产环境应使用持久化适配器。结合源码还可补充两点判断其一该适配器内部所有操作均为同步内存读写无事务与并发控制多实例部署时数据无法共享其二向量适配器也以内存 Map 保存全部向量超过万级向量后检索性能与内存开销会快速劣化。因此内存存储的正确定位是开发期的速度工具而非生产期的存储方案。何时切换持久化适配器当应用需要跨进程、跨重启保留记忆时Voltagent 提供了多条迁移路径且 API 完全一致——只需替换Memory的storage必要时连同vector即可Managed Memory零配置的生产级托管记忆服务开箱即用LibSQL / SQLite自托管 SQLite 或边缘部署方案PostgreSQL自托管 Postgres 适配器适合已有数据库体系Supabase基于 Supabase 平台的托管集成。迁移时建议遵循先在开发环境用内存存储跑通逻辑再替换持久化适配器的节奏借助统一的StorageAdapter接口实现最小改动切换。小结InMemoryStorageAdapter是 Voltagent 记忆体系中零成本起步的基石它默认被启用、支持完整的会话/工作记忆/向量语义为开发测试与无状态场景提供了敏捷的存储环境。其底层以userId → conversationId双层结构组织消息通过StorageAdapter接口types.ts与其他持久化适配器保持完全一致的使用方式。理解它的默认行为与边界你就能在正确的场景选择正确的存储避免把开发期的便利误用到生产环境。赞分享人工智能AI AgentAgent 框架后端多智能体RAG工具调用Agent 记忆【免费下载链接】voltagentAI Agent Engineering Platform built on an Open Source TypeScript AI Agent Framework项目地址https://gitcode.com/gh_mirrors/vo/voltagent点击查看免费下载相关推荐Apache SkyWalking 后端存储配置指南使用 H2 内存数据库作为默认存储Apache SkyWalking 后端存储配置指南使用 H2 内存数据库作为默认存储 导读 Apache SkyWalking 的 OAPObservab可观测性后端微服务云原生深入解读 voltagent/voltagent-memoryVoltAgent 托管内存适配器的架构、配置与演进深入解读 voltagent/voltagent memoryVoltAgent 托管内存适配器的架构、配置与演进 导读 voltagent/voltag人工智能AI AgentAgent 框架后端多智能体RAG工具调用Agent 记忆Agent 工作流AI 评测MCP 服务MCP Clients语音Kubernetes 命名空间默认内存请求与限制配置指南Kubernetes 命名空间默认内存请求与限制配置指南 概述 在 Kubernetes 集群中合理配置内存请求Memory Requests和限制Me文档教程云原生上一篇网盘直链下载助手告别限速解锁八大网盘高速下载的完整指南下一篇网盘直链下载助手告别限速解锁九大网盘高速下载的终极解决方案创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考