Mastra 记忆存储配置完全指南LibSQL、PostgreSQL 与 Upstash 存储适配器实战【免费下载链接】mastraMastra is the modern TypeScript framework for AI-powered applications and agents.项目地址: https://gitcode.com/GitHub_Trending/ma/mastra对话历史能否跨应用重启而留存完全取决于你为Memory实例配置的存储适配器。本文围绕 Mastra 的存储配置主题系统讲解默认 LibSQL本地 SQLite存储的完整参数、对话历史条数控制以及面向生产环境的 PostgreSQL 与 UpstashRedis替换方案并结合仓库源码packages/memory/src/index.ts、stores/libsql/src/storage/index.ts、stores/pg/src/storage/index.ts、stores/upstash/src/storage/index.ts逐项解读底层实现。读完本文你将能够为记忆 Agent 选择并正确配置存储适配器、按需调整对话历史条数、理解本地库的 PRAGMA 调优原理并把开发环境平滑迁移到生产级存储。存储适配器在 Mastra 记忆体系中的角色Mastra 的记忆能力由mastra/memory包提供它通过存储适配器storage adapter来持久化记忆数据。所谓记忆数据包括两类核心内容对话历史conversation historyAgent 与用户之间逐条往来的消息记录工作记忆working memoryAgent 跨会话维护的结构化用户信息、偏好与任务状态。存储适配器的核心价值在于把这两类数据写入持久化介质使 Agent 在应用进程重启后依然能回忆起之前的对话。在 Memory 类的源码文档注释 中可以看到Memory的定位是为 Mastra Agent 提供对话历史以及可选的工作记忆、语义召回和观察记忆并明确要求在使用前为该实例或其 Mastra 实例配置存储。从源码结构看Memory继承自MastraMemory定义于mastra/core/memory而各类存储实现如LibSQLStore、PostgresStore、UpstashStore均继承自MastraCompositeStore并通过getStore(memory)暴露记忆域memory domain的读写能力。也就是说存储适配器是一组可插拔的持久化后端Memory只面向统一的存储接口编程具体落在哪个数据库由配置决定。默认存储LibSQL本地 SQLiteMastra 开箱即用的默认存储是LibSQL——一个快速、开源的 SQLite 分支由 Turso 主导开发。LibSQL 以单文件本地数据库的形式运行无需独立部署数据库服务非常适合开发与测试阶段。安装记忆与存储包记忆能力与存储适配器是独立于核心包发布的只有需要时才引入以保持依赖精简。安装命令如下来自本课程安装章节npm install mastra/memorylatest mastra/libsqllatestmastra/memory提供对话历史、语义召回、工作记忆等全部记忆能力mastra/libsql众多存储适配器之一为 LibSQL/SQLite 提供持久化实现。最小可用配置以下代码创建了一个使用本地 LibSQL 存储的Memory实例对应课程文档的存储配置章节import { Memory } from mastra/memory import { LibSQLStore } from mastra/libsql const memory new Memory({ // Configure storage storage: new LibSQLStore({ id: learning-memory-storage, url: file:../../memory.db, // Local database. Relative to the output folder }), options: { lastMessages: 20, }, })其中storage注入存储适配器实例此处为LibSQLStoreid存储实例的唯一标识用于在 Mastra 中区分多个存储。在 LibSQLStore 构造函数 中id为空字符串或非字符串会被直接拒绝并抛出错误url数据库连接地址。file:../../memory.db表示本地文件数据库路径相对于构建/输出目录而非源码目录这是初学者最容易踩坑的点——请务必确认相对路径指向你实际运行程序时的当前工作目录options.lastMessages每次请求注入 Agent 上下文窗口的最近消息条数覆盖默认值 10。LibSQLStore 完整配置参数结合 LibSQL 存储适配器的类型定义LibSQLStore支持以下配置项可按需组合配置项类型默认值说明idstring必填存储实例唯一标识不能为空urlstring—连接地址file:本地文件、:memory:内存库、libsql:///https://远程库authTokenstring无远程 LibSQL/Turso 数据库的认证令牌syncUrlstring无远程主库 URL设置后启用嵌入式副本embedded replica要求url为本地file:地址syncIntervalnumber无与远程主库自动同步的间隔秒仅在设置syncUrl时生效clientClient无直接传入已配置好的libsql/client实例与url二选一maxRetriesnumber5写入遇到SQLITE_BUSY时的最大重试次数initialBackoffMsnumber100重试的初始退避毫秒数每次重试指数翻倍connectionTimeoutMsnumber5000本地库busy_timeout毫秒写锁冲突时等待锁释放而非立即失败仅对本地库生效要求libsql/client≥ 0.17.4localPragmas.cacheSizenumber-16000SQLitecache_size负值按 KiB 解释localPragmas.mmapSizenumber134217728SQLitemmap_size字节提升读取性能disableInitbooleanfalse关闭运行时自动建表/迁移适合 CI/CD 中显式执行迁移retentionRetentionConfig无按表粒度的基于时间的保留策略如{ memory: { messages: { maxAge: 30d } } }需自行把storage.prune()接入定时任务本地数据库的 PRAGMA 调优原理LibSQLStore对本地file:/:memory:数据库会自动执行一组 SQLite PRAGMA 优化见 applyLocalPragmas 实现PRAGMA journal_modeWAL; -- 启用 WAL 日志模式读写并发更友好 PRAGMA busy_timeout连接超时毫秒; -- 写锁等待时长 PRAGMA synchronousNORMAL; -- 降低同步频率换取写入性能 PRAGMA temp_storeMEMORY; -- 临时表/排序放内存 PRAGMA cache_sizecacheSize; -- 页缓存大小 PRAGMA mmap_sizemmapSize; -- 内存映射大小这些 PRAGMA 仅在isLocalDburl以file:开头或包含:memory:且未设置syncUrl时应用远程库与嵌入式副本由服务端/同步引擎处理。另外LibSQLStore也继承了MastraCompositeStore的init()与close()init()负责建表与迁移本地库按域串行执行 DDL 以避免重复建表close()释放底层 libsql 客户端句柄。控制对话历史lastMessages 选项存储决定了消息放哪而lastMessages决定每次请求取多少。这是两个相互配合的配置默认值lastMessages默认取最近10条消息见 packages/core/src/memory/memory.ts 与类型定义 packages/core/src/memory/types.ts设为数字如lastMessages: 20将最近 20 条消息注入上下文设为false彻底禁用对话历史——此时recall()不再返回历史消息仅当启用语义召回时返回相关片段见 recall 实现 中historyDisabledByConfig的处理逻辑。课程对话历史配置章节给出了完整示例把lastMessages与其他配置一并传入Memory构造器import { Agent } from mastra/core/agent import { Memory } from mastra/memory import { LibSQLStore } from mastra/libsql const memory new Memory({ storage: new LibSQLStore({ url: file:../../memory.db, }), options: { lastMessages: 20, // Include the last 20 messages instead of the default 10 }, }) export const memoryAgent new Agent({ name: MemoryAgent, instructions: You are a helpful assistant with memory capabilities. You can remember previous conversations and user preferences. , model: openai/gpt-5.4, memory: memory, })需要注意lastMessages与上下文窗口的平衡语言模型的上下文窗口有限历史消息过多会挤占其他重要信息如指令、工具结果、检索片段过少则 Agent 无法理解对话脉络。从 recall 实现 还可以看到一个细节当设置了lastMessages且未显式指定排序时底层会按createdAt倒序查询最新的 N 条再反转回时间正序交给模型确保取到的是最后 N 条而非最早 N 条。生产级替换方案一PostgreSQLPostgreSQL 是文档推荐的生产环境首选之一。它支持连接池、读写分离、自定义 schema适合多实例部署与大规模数据量场景。存储实现为PostgresStore位于 stores/pg/src/storage/index.ts。连接字符串方式import { PostgresStore } from mastra/pg const storage new PostgresStore({ id: my-pg-store, connectionString: postgresql://user:passwordlocalhost:5432/mastra, })主机参数方式const storage new PostgresStore({ id: my-pg-store, host: localhost, port: 5432, database: mastra, user: postgres, password: secret, ssl: { rejectUnauthorized: false }, })连接池与高级选项从源码看PostgresStore的核心配置包括默认值见 stores/pg/src/storage/index.ts配置项默认值说明max连接池上限20池中最大并发连接数idleTimeoutMillis30000空闲连接回收超时毫秒schemaNamepublic使用的 PostgreSQL schema会经过标识符解析校验防注入readPool/writePool共用同一池读写分离可分别提供读池与写池未提供readPool时读写共用写池pool—直接传入自建的pg.Pool实例disableInit/retentionfalse/ 无与 LibSQL 同义的初始化控制与保留策略skipDefaultIndexes/indexes—跳过默认索引 / 自定义索引源码层面有两个值得关注的工程细节其一PostgresStore在自身创建连接池时会为池注册error监听器避免空闲连接掉线后端重启、网络分区、云代理回收空闲 socket时触发 Node 的uncaughtException导致进程崩溃若传入用户自建池则保留用户自己的监听器。其二init()期间会把 DDL 流量临时固定pin到单一连接上保证建表/迁移的串行一致性。此外stores/pg/src/storage/index.ts 导出了exportSchemas(schemaName?)函数可以在不连接数据库的情况下导出完整的建表 DDL含表、约束、索引、触发器配合disableInit: true可在 CI/CD 部署阶段显式执行迁移运行时应用则不再自动改表。生产级替换方案二UpstashRedisUpstash 提供 Serverless Redis 服务按请求计费、零运维适合无状态函数与边缘部署场景。存储实现为UpstashStore位于 stores/upstash/src/storage/index.ts。URL Token 方式import { UpstashStore } from mastra/upstash const storage new UpstashStore({ id: my-upstash-store, url: https://your-db.upstash.io, token: your-token, })预配置 Redis 客户端方式当需要自定义重试策略或拦截器时可先构造upstash/redis的Redis客户端再传入import { Redis } from upstash/redis import { UpstashStore } from mastra/upstash const client new Redis({ url: https://your-db.upstash.io, token: your-token, retry: { retries: 5, backoff: retryCount Math.exp(retryCount) * 50 }, }) const storage new UpstashStore({ id: my-upstash-store, client })从源码看UpstashStore在传入url/token时会先做非空校验为空直接抛错并支持disableInit配置。与 LibSQL/Postgres 不同Upstash 的存储域目前只覆盖scores、workflows、memory、backgroundTasks四类见 stores/upstash/src/storage/index.ts且close()为空实现无本地连接需要清理。如何选择存储方案课程文档给出的选择建议可以归纳为以下决策路径开发与测试阶段默认的 LibSQL 本地存储通常已经足够——零部署成本、单文件便于清空重置、PRAGMA 自动优化保证基础读写性能生产环境单体/多实例服务优先考虑 PostgreSQL。它提供成熟的事务、连接池、读写分离与 schema 管理能够支撑多个应用实例并发读写同一份记忆数据生产环境Serverless / 边缘 / 追求零运维考虑 Upstash 这类云端方案无需自行托管数据库适合按需弹性的无服务器架构。替换时只需更换storage注入的适配器实例Memory的其余配置lastMessages、工作记忆、语义召回等保持不动存储接口对上层完全透明。也可以从 mastra/libsql 与 mastra/pg 的源码看到两者都实现了统一的内存域getStore(memory)读写接口这也是一键换存储能够成立的根本原因。小结存储配置是 Mastra 记忆功能从能跑走向可靠的关键一环开发期用默认 LibSQL 快速验证生产期按架构选 PostgreSQL 或 Upstash。本课程后续的测试对话历史、向量存储配置与语义召回配置章节将进一步围绕存储之上的召回与检索能力展开届时你会发现清晰理解存储适配器的职责边界是正确组合这些高级记忆特性的前提。【免费下载链接】mastraMastra is the modern TypeScript framework for AI-powered applications and agents.项目地址: https://gitcode.com/GitHub_Trending/ma/mastra创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Mastra 记忆存储配置完全指南：LibSQL、PostgreSQL 与 Upstash 存储适配器实战
Mastra 记忆存储配置完全指南LibSQL、PostgreSQL 与 Upstash 存储适配器实战【免费下载链接】mastraMastra is the modern TypeScript framework for AI-powered applications and agents.项目地址: https://gitcode.com/GitHub_Trending/ma/mastra对话历史能否跨应用重启而留存完全取决于你为Memory实例配置的存储适配器。本文围绕 Mastra 的存储配置主题系统讲解默认 LibSQL本地 SQLite存储的完整参数、对话历史条数控制以及面向生产环境的 PostgreSQL 与 UpstashRedis替换方案并结合仓库源码packages/memory/src/index.ts、stores/libsql/src/storage/index.ts、stores/pg/src/storage/index.ts、stores/upstash/src/storage/index.ts逐项解读底层实现。读完本文你将能够为记忆 Agent 选择并正确配置存储适配器、按需调整对话历史条数、理解本地库的 PRAGMA 调优原理并把开发环境平滑迁移到生产级存储。存储适配器在 Mastra 记忆体系中的角色Mastra 的记忆能力由mastra/memory包提供它通过存储适配器storage adapter来持久化记忆数据。所谓记忆数据包括两类核心内容对话历史conversation historyAgent 与用户之间逐条往来的消息记录工作记忆working memoryAgent 跨会话维护的结构化用户信息、偏好与任务状态。存储适配器的核心价值在于把这两类数据写入持久化介质使 Agent 在应用进程重启后依然能回忆起之前的对话。在 Memory 类的源码文档注释 中可以看到Memory的定位是为 Mastra Agent 提供对话历史以及可选的工作记忆、语义召回和观察记忆并明确要求在使用前为该实例或其 Mastra 实例配置存储。从源码结构看Memory继承自MastraMemory定义于mastra/core/memory而各类存储实现如LibSQLStore、PostgresStore、UpstashStore均继承自MastraCompositeStore并通过getStore(memory)暴露记忆域memory domain的读写能力。也就是说存储适配器是一组可插拔的持久化后端Memory只面向统一的存储接口编程具体落在哪个数据库由配置决定。默认存储LibSQL本地 SQLiteMastra 开箱即用的默认存储是LibSQL——一个快速、开源的 SQLite 分支由 Turso 主导开发。LibSQL 以单文件本地数据库的形式运行无需独立部署数据库服务非常适合开发与测试阶段。安装记忆与存储包记忆能力与存储适配器是独立于核心包发布的只有需要时才引入以保持依赖精简。安装命令如下来自本课程安装章节npm install mastra/memorylatest mastra/libsqllatestmastra/memory提供对话历史、语义召回、工作记忆等全部记忆能力mastra/libsql众多存储适配器之一为 LibSQL/SQLite 提供持久化实现。最小可用配置以下代码创建了一个使用本地 LibSQL 存储的Memory实例对应课程文档的存储配置章节import { Memory } from mastra/memory import { LibSQLStore } from mastra/libsql const memory new Memory({ // Configure storage storage: new LibSQLStore({ id: learning-memory-storage, url: file:../../memory.db, // Local database. Relative to the output folder }), options: { lastMessages: 20, }, })其中storage注入存储适配器实例此处为LibSQLStoreid存储实例的唯一标识用于在 Mastra 中区分多个存储。在 LibSQLStore 构造函数 中id为空字符串或非字符串会被直接拒绝并抛出错误url数据库连接地址。file:../../memory.db表示本地文件数据库路径相对于构建/输出目录而非源码目录这是初学者最容易踩坑的点——请务必确认相对路径指向你实际运行程序时的当前工作目录options.lastMessages每次请求注入 Agent 上下文窗口的最近消息条数覆盖默认值 10。LibSQLStore 完整配置参数结合 LibSQL 存储适配器的类型定义LibSQLStore支持以下配置项可按需组合配置项类型默认值说明idstring必填存储实例唯一标识不能为空urlstring—连接地址file:本地文件、:memory:内存库、libsql:///https://远程库authTokenstring无远程 LibSQL/Turso 数据库的认证令牌syncUrlstring无远程主库 URL设置后启用嵌入式副本embedded replica要求url为本地file:地址syncIntervalnumber无与远程主库自动同步的间隔秒仅在设置syncUrl时生效clientClient无直接传入已配置好的libsql/client实例与url二选一maxRetriesnumber5写入遇到SQLITE_BUSY时的最大重试次数initialBackoffMsnumber100重试的初始退避毫秒数每次重试指数翻倍connectionTimeoutMsnumber5000本地库busy_timeout毫秒写锁冲突时等待锁释放而非立即失败仅对本地库生效要求libsql/client≥ 0.17.4localPragmas.cacheSizenumber-16000SQLitecache_size负值按 KiB 解释localPragmas.mmapSizenumber134217728SQLitemmap_size字节提升读取性能disableInitbooleanfalse关闭运行时自动建表/迁移适合 CI/CD 中显式执行迁移retentionRetentionConfig无按表粒度的基于时间的保留策略如{ memory: { messages: { maxAge: 30d } } }需自行把storage.prune()接入定时任务本地数据库的 PRAGMA 调优原理LibSQLStore对本地file:/:memory:数据库会自动执行一组 SQLite PRAGMA 优化见 applyLocalPragmas 实现PRAGMA journal_modeWAL; -- 启用 WAL 日志模式读写并发更友好 PRAGMA busy_timeout连接超时毫秒; -- 写锁等待时长 PRAGMA synchronousNORMAL; -- 降低同步频率换取写入性能 PRAGMA temp_storeMEMORY; -- 临时表/排序放内存 PRAGMA cache_sizecacheSize; -- 页缓存大小 PRAGMA mmap_sizemmapSize; -- 内存映射大小这些 PRAGMA 仅在isLocalDburl以file:开头或包含:memory:且未设置syncUrl时应用远程库与嵌入式副本由服务端/同步引擎处理。另外LibSQLStore也继承了MastraCompositeStore的init()与close()init()负责建表与迁移本地库按域串行执行 DDL 以避免重复建表close()释放底层 libsql 客户端句柄。控制对话历史lastMessages 选项存储决定了消息放哪而lastMessages决定每次请求取多少。这是两个相互配合的配置默认值lastMessages默认取最近10条消息见 packages/core/src/memory/memory.ts 与类型定义 packages/core/src/memory/types.ts设为数字如lastMessages: 20将最近 20 条消息注入上下文设为false彻底禁用对话历史——此时recall()不再返回历史消息仅当启用语义召回时返回相关片段见 recall 实现 中historyDisabledByConfig的处理逻辑。课程对话历史配置章节给出了完整示例把lastMessages与其他配置一并传入Memory构造器import { Agent } from mastra/core/agent import { Memory } from mastra/memory import { LibSQLStore } from mastra/libsql const memory new Memory({ storage: new LibSQLStore({ url: file:../../memory.db, }), options: { lastMessages: 20, // Include the last 20 messages instead of the default 10 }, }) export const memoryAgent new Agent({ name: MemoryAgent, instructions: You are a helpful assistant with memory capabilities. You can remember previous conversations and user preferences. , model: openai/gpt-5.4, memory: memory, })需要注意lastMessages与上下文窗口的平衡语言模型的上下文窗口有限历史消息过多会挤占其他重要信息如指令、工具结果、检索片段过少则 Agent 无法理解对话脉络。从 recall 实现 还可以看到一个细节当设置了lastMessages且未显式指定排序时底层会按createdAt倒序查询最新的 N 条再反转回时间正序交给模型确保取到的是最后 N 条而非最早 N 条。生产级替换方案一PostgreSQLPostgreSQL 是文档推荐的生产环境首选之一。它支持连接池、读写分离、自定义 schema适合多实例部署与大规模数据量场景。存储实现为PostgresStore位于 stores/pg/src/storage/index.ts。连接字符串方式import { PostgresStore } from mastra/pg const storage new PostgresStore({ id: my-pg-store, connectionString: postgresql://user:passwordlocalhost:5432/mastra, })主机参数方式const storage new PostgresStore({ id: my-pg-store, host: localhost, port: 5432, database: mastra, user: postgres, password: secret, ssl: { rejectUnauthorized: false }, })连接池与高级选项从源码看PostgresStore的核心配置包括默认值见 stores/pg/src/storage/index.ts配置项默认值说明max连接池上限20池中最大并发连接数idleTimeoutMillis30000空闲连接回收超时毫秒schemaNamepublic使用的 PostgreSQL schema会经过标识符解析校验防注入readPool/writePool共用同一池读写分离可分别提供读池与写池未提供readPool时读写共用写池pool—直接传入自建的pg.Pool实例disableInit/retentionfalse/ 无与 LibSQL 同义的初始化控制与保留策略skipDefaultIndexes/indexes—跳过默认索引 / 自定义索引源码层面有两个值得关注的工程细节其一PostgresStore在自身创建连接池时会为池注册error监听器避免空闲连接掉线后端重启、网络分区、云代理回收空闲 socket时触发 Node 的uncaughtException导致进程崩溃若传入用户自建池则保留用户自己的监听器。其二init()期间会把 DDL 流量临时固定pin到单一连接上保证建表/迁移的串行一致性。此外stores/pg/src/storage/index.ts 导出了exportSchemas(schemaName?)函数可以在不连接数据库的情况下导出完整的建表 DDL含表、约束、索引、触发器配合disableInit: true可在 CI/CD 部署阶段显式执行迁移运行时应用则不再自动改表。生产级替换方案二UpstashRedisUpstash 提供 Serverless Redis 服务按请求计费、零运维适合无状态函数与边缘部署场景。存储实现为UpstashStore位于 stores/upstash/src/storage/index.ts。URL Token 方式import { UpstashStore } from mastra/upstash const storage new UpstashStore({ id: my-upstash-store, url: https://your-db.upstash.io, token: your-token, })预配置 Redis 客户端方式当需要自定义重试策略或拦截器时可先构造upstash/redis的Redis客户端再传入import { Redis } from upstash/redis import { UpstashStore } from mastra/upstash const client new Redis({ url: https://your-db.upstash.io, token: your-token, retry: { retries: 5, backoff: retryCount Math.exp(retryCount) * 50 }, }) const storage new UpstashStore({ id: my-upstash-store, client })从源码看UpstashStore在传入url/token时会先做非空校验为空直接抛错并支持disableInit配置。与 LibSQL/Postgres 不同Upstash 的存储域目前只覆盖scores、workflows、memory、backgroundTasks四类见 stores/upstash/src/storage/index.ts且close()为空实现无本地连接需要清理。如何选择存储方案课程文档给出的选择建议可以归纳为以下决策路径开发与测试阶段默认的 LibSQL 本地存储通常已经足够——零部署成本、单文件便于清空重置、PRAGMA 自动优化保证基础读写性能生产环境单体/多实例服务优先考虑 PostgreSQL。它提供成熟的事务、连接池、读写分离与 schema 管理能够支撑多个应用实例并发读写同一份记忆数据生产环境Serverless / 边缘 / 追求零运维考虑 Upstash 这类云端方案无需自行托管数据库适合按需弹性的无服务器架构。替换时只需更换storage注入的适配器实例Memory的其余配置lastMessages、工作记忆、语义召回等保持不动存储接口对上层完全透明。也可以从 mastra/libsql 与 mastra/pg 的源码看到两者都实现了统一的内存域getStore(memory)读写接口这也是一键换存储能够成立的根本原因。小结存储配置是 Mastra 记忆功能从能跑走向可靠的关键一环开发期用默认 LibSQL 快速验证生产期按架构选 PostgreSQL 或 Upstash。本课程后续的测试对话历史、向量存储配置与语义召回配置章节将进一步围绕存储之上的召回与检索能力展开届时你会发现清晰理解存储适配器的职责边界是正确组合这些高级记忆特性的前提。【免费下载链接】mastraMastra is the modern TypeScript framework for AI-powered applications and agents.项目地址: https://gitcode.com/GitHub_Trending/ma/mastra创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考