@mastra/mcp-docs-server 1.0.0-beta.11 → 1.0.0-beta.14

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (345) hide show
  1. package/.docs/organized/changelogs/%40mastra%2Fagent-builder.md +29 -29
  2. package/.docs/organized/changelogs/%40mastra%2Fai-sdk.md +51 -51
  3. package/.docs/organized/changelogs/%40mastra%2Fclickhouse.md +45 -45
  4. package/.docs/organized/changelogs/%40mastra%2Fclient-js.md +180 -180
  5. package/.docs/organized/changelogs/%40mastra%2Fcloudflare-d1.md +39 -39
  6. package/.docs/organized/changelogs/%40mastra%2Fcloudflare.md +39 -39
  7. package/.docs/organized/changelogs/%40mastra%2Fconvex.md +68 -0
  8. package/.docs/organized/changelogs/%40mastra%2Fcore.md +331 -331
  9. package/.docs/organized/changelogs/%40mastra%2Fdeployer-cloud.md +31 -31
  10. package/.docs/organized/changelogs/%40mastra%2Fdeployer-cloudflare.md +16 -16
  11. package/.docs/organized/changelogs/%40mastra%2Fdeployer.md +41 -41
  12. package/.docs/organized/changelogs/%40mastra%2Fdynamodb.md +39 -39
  13. package/.docs/organized/changelogs/%40mastra%2Ffastembed.md +6 -0
  14. package/.docs/organized/changelogs/%40mastra%2Flance.md +39 -39
  15. package/.docs/organized/changelogs/%40mastra%2Flibsql.md +45 -45
  16. package/.docs/organized/changelogs/%40mastra%2Fmcp-docs-server.md +24 -24
  17. package/.docs/organized/changelogs/%40mastra%2Fmemory.md +24 -24
  18. package/.docs/organized/changelogs/%40mastra%2Fmongodb.md +39 -39
  19. package/.docs/organized/changelogs/%40mastra%2Fmssql.md +39 -39
  20. package/.docs/organized/changelogs/%40mastra%2Fpg.md +45 -45
  21. package/.docs/organized/changelogs/%40mastra%2Fplayground-ui.md +96 -96
  22. package/.docs/organized/changelogs/%40mastra%2Frag.md +17 -17
  23. package/.docs/organized/changelogs/%40mastra%2Freact.md +49 -2
  24. package/.docs/organized/changelogs/%40mastra%2Fschema-compat.md +6 -0
  25. package/.docs/organized/changelogs/%40mastra%2Fserver.md +122 -122
  26. package/.docs/organized/changelogs/%40mastra%2Fupstash.md +39 -39
  27. package/.docs/organized/changelogs/create-mastra.md +31 -31
  28. package/.docs/organized/changelogs/mastra.md +51 -51
  29. package/.docs/organized/code-examples/agent-v6.md +151 -0
  30. package/.docs/organized/code-examples/ai-elements.md +1 -1
  31. package/.docs/organized/code-examples/quick-start.md +0 -4
  32. package/.docs/organized/code-examples/stock-price-tool.md +21 -2
  33. package/.docs/raw/agents/adding-voice.mdx +2 -3
  34. package/.docs/raw/agents/agent-approval.mdx +139 -6
  35. package/.docs/raw/agents/agent-memory.mdx +24 -32
  36. package/.docs/raw/agents/guardrails.mdx +61 -51
  37. package/.docs/raw/agents/networks.mdx +9 -13
  38. package/.docs/raw/agents/overview.mdx +40 -24
  39. package/.docs/raw/agents/processors.mdx +20 -19
  40. package/.docs/raw/agents/structured-output.mdx +11 -7
  41. package/.docs/raw/agents/using-tools.mdx +5 -6
  42. package/.docs/raw/course/01-first-agent/07-creating-your-agent.md +1 -2
  43. package/.docs/raw/course/01-first-agent/12-connecting-tool-to-agent.md +1 -1
  44. package/.docs/raw/course/01-first-agent/16-adding-memory-to-agent.md +1 -2
  45. package/.docs/raw/course/02-agent-tools-mcp/05-updating-your-agent.md +1 -1
  46. package/.docs/raw/course/02-agent-tools-mcp/10-updating-agent-instructions-zapier.md +1 -1
  47. package/.docs/raw/course/02-agent-tools-mcp/16-updating-agent-instructions-github.md +1 -1
  48. package/.docs/raw/course/02-agent-tools-mcp/21-updating-agent-instructions-hackernews.md +1 -1
  49. package/.docs/raw/course/02-agent-tools-mcp/27-updating-agent-instructions-filesystem.md +1 -1
  50. package/.docs/raw/course/02-agent-tools-mcp/31-enhancing-memory-configuration.md +2 -2
  51. package/.docs/raw/course/03-agent-memory/04-creating-basic-memory-agent.md +1 -2
  52. package/.docs/raw/course/03-agent-memory/08-configuring-conversation-history.md +1 -2
  53. package/.docs/raw/course/03-agent-memory/16-configuring-semantic-recall.md +3 -4
  54. package/.docs/raw/course/03-agent-memory/21-configuring-working-memory.md +2 -3
  55. package/.docs/raw/course/03-agent-memory/22-custom-working-memory-templates.md +2 -3
  56. package/.docs/raw/course/03-agent-memory/25-combining-memory-features.md +1 -2
  57. package/.docs/raw/course/03-agent-memory/27-creating-learning-assistant.md +2 -3
  58. package/.docs/raw/course/04-workflows/11-creating-an-ai-agent.md +2 -3
  59. package/.docs/raw/deployment/cloud-providers.mdx +20 -0
  60. package/.docs/raw/deployment/{building-mastra.mdx → mastra-server.mdx} +5 -5
  61. package/.docs/raw/deployment/monorepo.mdx +23 -44
  62. package/.docs/raw/deployment/overview.mdx +32 -50
  63. package/.docs/raw/deployment/web-framework.mdx +15 -19
  64. package/.docs/raw/evals/custom-scorers.mdx +9 -6
  65. package/.docs/raw/evals/overview.mdx +3 -6
  66. package/.docs/raw/evals/running-in-ci.mdx +2 -2
  67. package/.docs/raw/getting-started/manual-install.mdx +20 -20
  68. package/.docs/raw/getting-started/mcp-docs-server.mdx +2 -2
  69. package/.docs/raw/getting-started/start.mdx +10 -1
  70. package/.docs/raw/getting-started/studio.mdx +1 -1
  71. package/.docs/raw/guides/agent-frameworks/ai-sdk.mdx +4 -4
  72. package/.docs/raw/guides/build-your-ui/ai-sdk-ui.mdx +1033 -79
  73. package/.docs/raw/guides/build-your-ui/assistant-ui.mdx +8 -8
  74. package/.docs/raw/guides/build-your-ui/copilotkit.mdx +11 -11
  75. package/.docs/raw/{deployment/cloud-providers → guides/deployment}/amazon-ec2.mdx +9 -9
  76. package/.docs/raw/{deployment/cloud-providers → guides/deployment}/aws-lambda.mdx +13 -16
  77. package/.docs/raw/{deployment/cloud-providers → guides/deployment}/azure-app-services.mdx +5 -7
  78. package/.docs/raw/{deployment/cloud-providers → guides/deployment}/cloudflare-deployer.mdx +8 -5
  79. package/.docs/raw/{deployment/cloud-providers → guides/deployment}/digital-ocean.mdx +12 -15
  80. package/.docs/raw/guides/deployment/index.mdx +32 -0
  81. package/.docs/raw/guides/deployment/inngest.mdx +386 -0
  82. package/.docs/raw/{deployment/cloud-providers → guides/deployment}/netlify-deployer.mdx +7 -3
  83. package/.docs/raw/{deployment/cloud-providers → guides/deployment}/vercel-deployer.mdx +8 -5
  84. package/.docs/raw/guides/getting-started/astro.mdx +292 -451
  85. package/.docs/raw/guides/getting-started/express.mdx +72 -153
  86. package/.docs/raw/guides/getting-started/hono.mdx +227 -0
  87. package/.docs/raw/guides/getting-started/next-js.mdx +170 -61
  88. package/.docs/raw/guides/getting-started/quickstart.mdx +4 -4
  89. package/.docs/raw/guides/getting-started/sveltekit.mdx +238 -409
  90. package/.docs/raw/guides/getting-started/vite-react.mdx +317 -147
  91. package/.docs/raw/guides/guide/ai-recruiter.mdx +10 -10
  92. package/.docs/raw/guides/guide/chef-michel.mdx +9 -11
  93. package/.docs/raw/guides/guide/notes-mcp-server.mdx +15 -15
  94. package/.docs/raw/guides/guide/research-assistant.mdx +17 -17
  95. package/.docs/raw/guides/guide/stock-agent.mdx +5 -5
  96. package/.docs/raw/guides/guide/web-search.mdx +8 -8
  97. package/.docs/raw/guides/guide/whatsapp-chat-bot.mdx +7 -7
  98. package/.docs/raw/guides/migrations/ai-sdk-v4-to-v5.mdx +2 -2
  99. package/.docs/raw/guides/migrations/upgrade-to-v1/agent.mdx +1 -1
  100. package/.docs/raw/guides/migrations/upgrade-to-v1/client.mdx +17 -0
  101. package/.docs/raw/guides/migrations/upgrade-to-v1/overview.mdx +6 -0
  102. package/.docs/raw/guides/migrations/upgrade-to-v1/workflows.mdx +0 -2
  103. package/.docs/raw/guides/migrations/vnext-to-standard-apis.mdx +21 -23
  104. package/.docs/raw/index.mdx +2 -2
  105. package/.docs/raw/{deployment/mastra-cloud → mastra-cloud}/dashboard.mdx +2 -6
  106. package/.docs/raw/{deployment/mastra-cloud → mastra-cloud}/observability.mdx +1 -5
  107. package/.docs/raw/{deployment/mastra-cloud → mastra-cloud}/overview.mdx +2 -6
  108. package/.docs/raw/{deployment/mastra-cloud → mastra-cloud}/setting-up.mdx +8 -7
  109. package/.docs/raw/mcp/overview.mdx +31 -13
  110. package/.docs/raw/mcp/publishing-mcp-server.mdx +2 -2
  111. package/.docs/raw/memory/memory-processors.mdx +9 -9
  112. package/.docs/raw/memory/message-history.mdx +69 -0
  113. package/.docs/raw/memory/overview.mdx +34 -76
  114. package/.docs/raw/memory/semantic-recall.mdx +58 -49
  115. package/.docs/raw/memory/storage.mdx +188 -0
  116. package/.docs/raw/memory/working-memory.mdx +7 -7
  117. package/.docs/raw/observability/logging.mdx +10 -11
  118. package/.docs/raw/observability/overview.mdx +0 -1
  119. package/.docs/raw/observability/tracing/bridges/otel.mdx +2 -2
  120. package/.docs/raw/observability/tracing/exporters/cloud.mdx +1 -1
  121. package/.docs/raw/observability/tracing/exporters/default.mdx +3 -3
  122. package/.docs/raw/observability/tracing/exporters/langfuse.mdx +1 -2
  123. package/.docs/raw/observability/tracing/overview.mdx +23 -25
  124. package/.docs/raw/observability/tracing/processors/sensitive-data-filter.mdx +3 -3
  125. package/.docs/raw/rag/chunking-and-embedding.mdx +18 -31
  126. package/.docs/raw/rag/graph-rag.mdx +220 -0
  127. package/.docs/raw/rag/overview.mdx +2 -3
  128. package/.docs/raw/rag/retrieval.mdx +34 -51
  129. package/.docs/raw/rag/vector-databases.mdx +29 -25
  130. package/.docs/raw/reference/agents/agent.mdx +3 -3
  131. package/.docs/raw/reference/agents/generate.mdx +1 -1
  132. package/.docs/raw/reference/agents/generateLegacy.mdx +2 -2
  133. package/.docs/raw/reference/agents/getDefaultGenerateOptions.mdx +3 -3
  134. package/.docs/raw/reference/agents/getDefaultOptions.mdx +3 -3
  135. package/.docs/raw/reference/agents/getDefaultStreamOptions.mdx +3 -3
  136. package/.docs/raw/reference/agents/getDescription.mdx +1 -1
  137. package/.docs/raw/reference/agents/getInstructions.mdx +3 -3
  138. package/.docs/raw/reference/agents/getLLM.mdx +3 -3
  139. package/.docs/raw/reference/agents/getMemory.mdx +3 -3
  140. package/.docs/raw/reference/agents/getModel.mdx +3 -3
  141. package/.docs/raw/reference/agents/getTools.mdx +2 -2
  142. package/.docs/raw/reference/agents/getVoice.mdx +2 -2
  143. package/.docs/raw/reference/agents/listAgents.mdx +2 -2
  144. package/.docs/raw/reference/agents/listScorers.mdx +3 -3
  145. package/.docs/raw/reference/agents/listTools.mdx +2 -2
  146. package/.docs/raw/reference/agents/listWorkflows.mdx +2 -2
  147. package/.docs/raw/reference/agents/network.mdx +1 -1
  148. package/.docs/raw/reference/ai-sdk/chat-route.mdx +3 -3
  149. package/.docs/raw/reference/ai-sdk/handle-chat-stream.mdx +2 -2
  150. package/.docs/raw/reference/ai-sdk/handle-network-stream.mdx +2 -2
  151. package/.docs/raw/reference/ai-sdk/handle-workflow-stream.mdx +2 -2
  152. package/.docs/raw/reference/ai-sdk/network-route.mdx +3 -3
  153. package/.docs/raw/reference/ai-sdk/to-ai-sdk-stream.mdx +6 -6
  154. package/.docs/raw/reference/ai-sdk/to-ai-sdk-v4-messages.mdx +127 -0
  155. package/.docs/raw/reference/ai-sdk/to-ai-sdk-v5-messages.mdx +107 -0
  156. package/.docs/raw/reference/ai-sdk/with-mastra.mdx +1 -1
  157. package/.docs/raw/reference/ai-sdk/workflow-route.mdx +3 -3
  158. package/.docs/raw/reference/auth/auth0.mdx +2 -3
  159. package/.docs/raw/reference/auth/clerk.mdx +2 -3
  160. package/.docs/raw/reference/auth/firebase.mdx +3 -5
  161. package/.docs/raw/reference/auth/jwt.mdx +2 -3
  162. package/.docs/raw/reference/auth/supabase.mdx +2 -3
  163. package/.docs/raw/reference/auth/workos.mdx +2 -3
  164. package/.docs/raw/reference/cli/create-mastra.mdx +10 -10
  165. package/.docs/raw/reference/cli/mastra.mdx +10 -10
  166. package/.docs/raw/reference/client-js/agents.mdx +1 -2
  167. package/.docs/raw/reference/client-js/mastra-client.mdx +2 -2
  168. package/.docs/raw/reference/client-js/workflows.mdx +20 -0
  169. package/.docs/raw/reference/core/getAgent.mdx +1 -1
  170. package/.docs/raw/reference/core/getAgentById.mdx +1 -1
  171. package/.docs/raw/reference/core/getDeployer.mdx +1 -1
  172. package/.docs/raw/reference/core/getLogger.mdx +1 -1
  173. package/.docs/raw/reference/core/getMCPServer.mdx +1 -1
  174. package/.docs/raw/reference/core/getMCPServerById.mdx +1 -1
  175. package/.docs/raw/reference/core/getMemory.mdx +2 -2
  176. package/.docs/raw/reference/core/getServer.mdx +3 -3
  177. package/.docs/raw/reference/core/getStorage.mdx +2 -2
  178. package/.docs/raw/reference/core/getStoredAgentById.mdx +3 -3
  179. package/.docs/raw/reference/core/getTelemetry.mdx +1 -1
  180. package/.docs/raw/reference/core/getVector.mdx +1 -1
  181. package/.docs/raw/reference/core/getWorkflow.mdx +1 -1
  182. package/.docs/raw/reference/core/listAgents.mdx +1 -1
  183. package/.docs/raw/reference/core/listLogs.mdx +1 -1
  184. package/.docs/raw/reference/core/listLogsByRunId.mdx +1 -1
  185. package/.docs/raw/reference/core/listMCPServers.mdx +1 -1
  186. package/.docs/raw/reference/core/listMemory.mdx +2 -2
  187. package/.docs/raw/reference/core/listStoredAgents.mdx +4 -4
  188. package/.docs/raw/reference/core/listVectors.mdx +1 -1
  189. package/.docs/raw/reference/core/listWorkflows.mdx +1 -1
  190. package/.docs/raw/reference/core/setLogger.mdx +1 -1
  191. package/.docs/raw/reference/core/setStorage.mdx +2 -2
  192. package/.docs/raw/reference/core/setTelemetry.mdx +1 -1
  193. package/.docs/raw/reference/deployer/cloudflare.mdx +1 -2
  194. package/.docs/raw/reference/deployer/deployer.mdx +0 -1
  195. package/.docs/raw/reference/deployer/netlify.mdx +1 -1
  196. package/.docs/raw/reference/deployer/vercel.mdx +2 -4
  197. package/.docs/raw/reference/evals/answer-relevancy.mdx +1 -1
  198. package/.docs/raw/reference/evals/answer-similarity.mdx +1 -1
  199. package/.docs/raw/reference/evals/bias.mdx +1 -1
  200. package/.docs/raw/reference/evals/completeness.mdx +1 -1
  201. package/.docs/raw/reference/evals/content-similarity.mdx +1 -1
  202. package/.docs/raw/reference/evals/context-precision.mdx +1 -1
  203. package/.docs/raw/reference/evals/faithfulness.mdx +1 -1
  204. package/.docs/raw/reference/evals/hallucination.mdx +1 -1
  205. package/.docs/raw/reference/evals/keyword-coverage.mdx +1 -1
  206. package/.docs/raw/reference/evals/prompt-alignment.mdx +7 -7
  207. package/.docs/raw/reference/evals/textual-difference.mdx +1 -1
  208. package/.docs/raw/reference/evals/tone-consistency.mdx +1 -1
  209. package/.docs/raw/reference/evals/tool-call-accuracy.mdx +10 -10
  210. package/.docs/raw/reference/evals/toxicity.mdx +1 -1
  211. package/.docs/raw/reference/logging/pino-logger.mdx +7 -8
  212. package/.docs/raw/reference/memory/createThread.mdx +2 -2
  213. package/.docs/raw/reference/memory/deleteMessages.mdx +2 -2
  214. package/.docs/raw/reference/memory/listThreadsByResourceId.mdx +2 -2
  215. package/.docs/raw/reference/memory/memory-class.mdx +3 -3
  216. package/.docs/raw/reference/memory/query.mdx +2 -2
  217. package/.docs/raw/reference/memory/recall.mdx +2 -2
  218. package/.docs/raw/reference/observability/tracing/exporters/langfuse.mdx +1 -1
  219. package/.docs/raw/reference/processors/batch-parts-processor.mdx +2 -2
  220. package/.docs/raw/reference/processors/language-detector.mdx +2 -2
  221. package/.docs/raw/reference/processors/message-history-processor.mdx +2 -2
  222. package/.docs/raw/reference/processors/moderation-processor.mdx +3 -3
  223. package/.docs/raw/reference/processors/pii-detector.mdx +3 -3
  224. package/.docs/raw/reference/processors/processor-interface.mdx +13 -13
  225. package/.docs/raw/reference/processors/prompt-injection-detector.mdx +2 -2
  226. package/.docs/raw/reference/processors/semantic-recall-processor.mdx +2 -2
  227. package/.docs/raw/reference/processors/system-prompt-scrubber.mdx +2 -2
  228. package/.docs/raw/reference/processors/token-limiter-processor.mdx +2 -2
  229. package/.docs/raw/reference/processors/tool-call-filter.mdx +3 -3
  230. package/.docs/raw/reference/processors/unicode-normalizer.mdx +2 -2
  231. package/.docs/raw/reference/processors/working-memory-processor.mdx +3 -3
  232. package/.docs/raw/reference/rag/chunk.mdx +1 -1
  233. package/.docs/raw/reference/rag/database-config.mdx +1 -1
  234. package/.docs/raw/reference/rag/extract-params.mdx +2 -2
  235. package/.docs/raw/reference/rag/metadata-filters.mdx +7 -7
  236. package/.docs/raw/reference/server/create-route.mdx +14 -14
  237. package/.docs/raw/reference/server/express-adapter.mdx +10 -11
  238. package/.docs/raw/reference/server/hono-adapter.mdx +10 -11
  239. package/.docs/raw/reference/server/mastra-server.mdx +22 -22
  240. package/.docs/raw/reference/server/routes.mdx +28 -1
  241. package/.docs/raw/reference/storage/cloudflare-d1.mdx +3 -3
  242. package/.docs/raw/reference/storage/cloudflare.mdx +2 -2
  243. package/.docs/raw/reference/storage/convex.mdx +6 -6
  244. package/.docs/raw/reference/storage/dynamodb.mdx +4 -4
  245. package/.docs/raw/reference/storage/lance.mdx +3 -3
  246. package/.docs/raw/reference/storage/libsql.mdx +69 -54
  247. package/.docs/raw/reference/storage/mongodb.mdx +80 -7
  248. package/.docs/raw/reference/storage/mssql.mdx +4 -4
  249. package/.docs/raw/{server-db/storage.mdx → reference/storage/overview.mdx} +13 -111
  250. package/.docs/raw/reference/storage/postgresql.mdx +78 -7
  251. package/.docs/raw/reference/storage/upstash.mdx +74 -2
  252. package/.docs/raw/reference/streaming/agents/stream.mdx +27 -5
  253. package/.docs/raw/reference/streaming/agents/streamLegacy.mdx +2 -2
  254. package/.docs/raw/reference/streaming/workflows/observeStream.mdx +1 -1
  255. package/.docs/raw/reference/streaming/workflows/resumeStream.mdx +1 -1
  256. package/.docs/raw/reference/streaming/workflows/stream.mdx +35 -22
  257. package/.docs/raw/reference/streaming/workflows/timeTravelStream.mdx +4 -4
  258. package/.docs/raw/reference/templates/overview.mdx +1 -2
  259. package/.docs/raw/reference/tools/create-tool.mdx +24 -5
  260. package/.docs/raw/reference/tools/graph-rag-tool.mdx +3 -3
  261. package/.docs/raw/reference/tools/vector-query-tool.mdx +4 -4
  262. package/.docs/raw/reference/vectors/astra.mdx +3 -3
  263. package/.docs/raw/reference/vectors/chroma.mdx +3 -3
  264. package/.docs/raw/reference/vectors/convex.mdx +12 -12
  265. package/.docs/raw/reference/vectors/couchbase.mdx +5 -5
  266. package/.docs/raw/reference/vectors/duckdb.mdx +10 -10
  267. package/.docs/raw/reference/vectors/elasticsearch.mdx +4 -4
  268. package/.docs/raw/reference/vectors/lance.mdx +4 -4
  269. package/.docs/raw/reference/vectors/libsql.mdx +61 -11
  270. package/.docs/raw/reference/vectors/mongodb.mdx +58 -5
  271. package/.docs/raw/reference/vectors/pg.mdx +53 -6
  272. package/.docs/raw/reference/vectors/pinecone.mdx +3 -3
  273. package/.docs/raw/reference/vectors/qdrant.mdx +3 -3
  274. package/.docs/raw/reference/vectors/s3vectors.mdx +6 -6
  275. package/.docs/raw/reference/vectors/turbopuffer.mdx +4 -4
  276. package/.docs/raw/reference/vectors/upstash.mdx +55 -6
  277. package/.docs/raw/reference/vectors/vectorize.mdx +3 -3
  278. package/.docs/raw/reference/workflows/run-methods/cancel.mdx +2 -2
  279. package/.docs/raw/reference/workflows/run-methods/restart.mdx +1 -3
  280. package/.docs/raw/reference/workflows/run-methods/resume.mdx +2 -2
  281. package/.docs/raw/reference/workflows/run-methods/start.mdx +2 -2
  282. package/.docs/raw/reference/workflows/run-methods/startAsync.mdx +143 -0
  283. package/.docs/raw/reference/workflows/run-methods/timeTravel.mdx +5 -5
  284. package/.docs/raw/reference/workflows/run.mdx +1 -1
  285. package/.docs/raw/reference/workflows/step.mdx +3 -3
  286. package/.docs/raw/reference/workflows/workflow-methods/branch.mdx +1 -1
  287. package/.docs/raw/reference/workflows/workflow-methods/commit.mdx +1 -1
  288. package/.docs/raw/reference/workflows/workflow-methods/create-run.mdx +37 -2
  289. package/.docs/raw/reference/workflows/workflow-methods/dountil.mdx +1 -1
  290. package/.docs/raw/reference/workflows/workflow-methods/dowhile.mdx +1 -1
  291. package/.docs/raw/reference/workflows/workflow-methods/foreach.mdx +6 -6
  292. package/.docs/raw/reference/workflows/workflow-methods/map.mdx +7 -7
  293. package/.docs/raw/reference/workflows/workflow-methods/parallel.mdx +1 -1
  294. package/.docs/raw/reference/workflows/workflow-methods/sendEvent.mdx +2 -2
  295. package/.docs/raw/reference/workflows/workflow-methods/sleep.mdx +2 -2
  296. package/.docs/raw/reference/workflows/workflow-methods/sleepUntil.mdx +2 -2
  297. package/.docs/raw/reference/workflows/workflow-methods/then.mdx +1 -1
  298. package/.docs/raw/reference/workflows/workflow-methods/waitForEvent.mdx +2 -2
  299. package/.docs/raw/reference/workflows/workflow.mdx +17 -3
  300. package/.docs/raw/{auth → server/auth}/auth0.mdx +20 -14
  301. package/.docs/raw/{auth → server/auth}/clerk.mdx +16 -9
  302. package/.docs/raw/{auth → server/auth}/firebase.mdx +21 -15
  303. package/.docs/raw/{auth → server/auth}/index.mdx +6 -6
  304. package/.docs/raw/{auth → server/auth}/jwt.mdx +14 -7
  305. package/.docs/raw/{auth → server/auth}/supabase.mdx +16 -9
  306. package/.docs/raw/{auth → server/auth}/workos.mdx +19 -13
  307. package/.docs/raw/{server-db → server}/custom-adapters.mdx +13 -13
  308. package/.docs/raw/{server-db → server}/custom-api-routes.mdx +3 -5
  309. package/.docs/raw/{server-db → server}/mastra-client.mdx +26 -15
  310. package/.docs/raw/{server-db → server}/mastra-server.mdx +8 -8
  311. package/.docs/raw/{server-db → server}/middleware.mdx +9 -9
  312. package/.docs/raw/{server-db → server}/request-context.mdx +33 -32
  313. package/.docs/raw/{server-db → server}/server-adapters.mdx +12 -12
  314. package/.docs/raw/streaming/events.mdx +14 -7
  315. package/.docs/raw/streaming/overview.mdx +21 -10
  316. package/.docs/raw/streaming/tool-streaming.mdx +6 -6
  317. package/.docs/raw/streaming/workflow-streaming.mdx +6 -8
  318. package/.docs/raw/tools-mcp/advanced-usage.mdx +2 -2
  319. package/.docs/raw/tools-mcp/mcp-overview.mdx +31 -12
  320. package/.docs/raw/tools-mcp/overview.mdx +10 -11
  321. package/.docs/raw/voice/overview.mdx +1 -1
  322. package/.docs/raw/workflows/agents-and-tools.mdx +28 -19
  323. package/.docs/raw/workflows/control-flow.mdx +27 -40
  324. package/.docs/raw/workflows/error-handling.mdx +172 -18
  325. package/.docs/raw/workflows/human-in-the-loop.mdx +6 -7
  326. package/.docs/raw/workflows/inngest-workflow.mdx +8 -9
  327. package/.docs/raw/workflows/input-data-mapping.mdx +7 -7
  328. package/.docs/raw/workflows/overview.mdx +34 -23
  329. package/.docs/raw/workflows/snapshots.mdx +14 -44
  330. package/.docs/raw/workflows/suspend-and-resume.mdx +7 -7
  331. package/.docs/raw/workflows/time-travel.mdx +16 -16
  332. package/.docs/raw/workflows/workflow-state.mdx +5 -8
  333. package/CHANGELOG.md +23 -0
  334. package/dist/logger.d.ts +3 -0
  335. package/dist/logger.d.ts.map +1 -1
  336. package/dist/stdio.js +53 -0
  337. package/package.json +4 -4
  338. package/.docs/organized/changelogs/%40internal%2Fai-sdk-v4.md +0 -1
  339. package/.docs/raw/deployment/cloud-providers/index.mdx +0 -55
  340. package/.docs/raw/memory/conversation-history.mdx +0 -24
  341. package/.docs/raw/memory/storage/memory-with-libsql.mdx +0 -140
  342. package/.docs/raw/memory/storage/memory-with-mongodb.mdx +0 -150
  343. package/.docs/raw/memory/storage/memory-with-pg.mdx +0 -138
  344. package/.docs/raw/memory/storage/memory-with-upstash.mdx +0 -146
  345. package/.docs/raw/memory/threads-and-resources.mdx +0 -95
@@ -1,32 +1,35 @@
1
1
  ---
2
2
  title: "Memory overview | Memory"
3
- description: "Learn how Mastra's memory system works with working memory, conversation history, and semantic recall."
3
+ description: "Learn how Mastra's memory system works with working memory, message history, and semantic recall."
4
4
  ---
5
5
 
6
- # Memory overview
6
+ # Memory
7
7
 
8
- Memory in Mastra helps agents manage context across conversations by condensing relevant information into the language model's context window.
8
+ Memory gives your agent coherence across interactions and allows it to improve over time by retaining relevant information from past conversations.
9
9
 
10
- Mastra supports three types of memory: working memory, conversation history, and semantic recall. It uses a two-tier scoping system where memory can be isolated per conversation thread (thread-scoped) or shared across all conversations for the same user (resource-scoped).
10
+ Mastra requires a [storage provider](./storage) to persist memory and supports three types:
11
11
 
12
- Mastra's memory system uses [storage providers](#memory-storage-adapters) to persist conversation threads, messages, and working memory across application restarts.
12
+ - [**Message history**](/docs/v1/memory/message-history) captures recent messages from the current conversation, providing short-term continuity and maintaining dialogue flow.
13
+ - [**Working memory**](/docs/v1/memory/working-memory) stores persistent user-specific details such as names, preferences, goals, and other structured data.
14
+ - [**Semantic recall**](/docs/v1/memory/semantic-recall) retrieves older messages from past conversations based on semantic relevance. Matches are retrieved using vector search and can include surrounding context for better comprehension.
15
+
16
+ You can enable any combination of these memory types. Mastra assembles the relevant memories into the model’s context window. If the total exceeds the model's token limit, use [memory processors](/docs/v1/memory/memory-processors) to trim or filter messages before sending them to the model.
13
17
 
14
18
  ## Getting started
15
19
 
16
- First install the required dependencies:
20
+ Install Mastra's memory module and the storage adapter for your preferred database (see the storage section below):
17
21
 
18
- ```bash copy
19
- npm install @mastra/core@beta @mastra/memory@beta @mastra/libsql@beta
22
+ ```bash
23
+ npm install @mastra/memory@beta @mastra/libsql@beta
20
24
  ```
21
25
 
22
- Then add a storage adapter to the main Mastra instance. Any agent with memory enabled will use this shared storage to store and recall interactions.
26
+ Add the storage adapter to the main Mastra instance:
23
27
 
24
- ```typescript {6-8} title="src/mastra/index.ts" showLineNumbers copy
28
+ ```typescript title="src/mastra/index.ts"
25
29
  import { Mastra } from "@mastra/core";
26
30
  import { LibSQLStore } from "@mastra/libsql";
27
31
 
28
32
  export const mastra = new Mastra({
29
- // ...
30
33
  storage: new LibSQLStore({
31
34
  id: 'mastra-storage',
32
35
  url: ":memory:",
@@ -34,88 +37,43 @@ export const mastra = new Mastra({
34
37
  });
35
38
  ```
36
39
 
37
- Now, enable memory by passing a `Memory` instance to the agent's `memory` parameter:
38
-
39
- ```typescript {3-5} title="src/mastra/agents/test-agent.ts" showLineNumbers copy
40
- import { Memory } from "@mastra/memory";
41
- import { Agent } from "@mastra/core/agent";
42
-
43
- export const testAgent = new Agent({
44
- id: "test-agent",
45
- // ...
46
- memory: new Memory(),
47
- });
48
- ```
49
-
50
- That memory instance has options you can configure for working memory, conversation history, and semantic recall.
51
-
52
- ## Different types of memory
53
-
54
- Mastra supports three types of memory: working memory, conversation history, and semantic recall.
55
-
56
- [**Working memory**](./working-memory) stores persistent user-specific details such as names, preferences, goals, and other structured data. (Compare this to ChatGPT where you can ask it to tell you about yourself). This is implemented as a block of Markdown text that the agent is able to update over time (or alternately, as a Zod schema)
57
-
58
- [**Conversation history**](./conversation-history) captures recent messages from the current conversation, providing short-term continuity and maintaining dialogue flow.
59
-
60
- [**Semantic recall**](./semantic-recall) retrieves older messages from past conversations based on semantic relevance. Matches are retrieved using vector search and can include surrounding context for better comprehension.
40
+ Enable memory by passing a `Memory` instance to your agent:
61
41
 
62
- Mastra combines all memory types into a single context window. If the total exceeds the model’s token limit, use [memory processors](./memory-processors) to trim or filter messages before sending them to the model.
63
-
64
- ## Scoping memory with threads and resources
65
-
66
- All memory types are [resource-scoped](./working-memory#resource-scoped-memory-default) by default, meaning they persist across all conversations for the same user or entity. [Thread-scoped](./working-memory#thread-scoped-memory) configuration isolates memory to a single conversation thread.
67
-
68
- ## Memory Storage Adapters
69
-
70
- To persist and recall information between conversations, memory requires a storage adapter.
71
-
72
- Supported options include [LibSQL](/docs/v1/memory/storage/memory-with-libsql), [MongoDB](/docs/v1/memory/storage/memory-with-mongodb), [Postgres](/docs/v1/memory/storage/memory-with-pg), and [Upstash](/docs/v1/memory/storage/memory-with-upstash)
73
-
74
- We use LibSQL out of the box because it is file-based or in-memory, so it is easy to install and works well with Studio.
75
-
76
- ## Dedicated storage
77
-
78
- Agents can be configured with their own dedicated storage, keeping tasks, conversations, and recalled information separate across agents.
79
-
80
- ### Adding storage to agents
81
-
82
- To assign dedicated storage to an agent, install and import the required dependency and pass a `storage` instance to the `Memory` constructor:
83
-
84
- ```typescript {3, 9-11} title="src/mastra/agents/test-agent.ts" showLineNumbers copy
42
+ ```typescript title="src/mastra/agents/test-agent.ts"
85
43
  import { Memory } from "@mastra/memory";
86
44
  import { Agent } from "@mastra/core/agent";
87
- import { LibSQLStore } from "@mastra/libsql";
88
45
 
89
46
  export const testAgent = new Agent({
90
47
  id: "test-agent",
91
- // ...
92
48
  memory: new Memory({
93
- // ...
94
- storage: new LibSQLStore({
95
- id: 'test-agent-storage',
96
- url: "file:agent-memory.db",
97
- }),
98
- // ...
49
+ options: {
50
+ lastMessages: 20,
51
+ },
99
52
  }),
100
53
  });
101
54
  ```
55
+ When you send a new message, the model can now "see" the previous 20 messages, which gives it better context for the conversation and leads to more coherent, accurate replies.
102
56
 
103
- ## Viewing retrieved messages
57
+ This example configures basic [message history](/docs/v1/memory/message-history). You can also enable [working memory](/docs/v1/memory/working-memory) and [semantic recall](/docs/v1/memory/semantic-recall) by passing additional options to `Memory`.
104
58
 
105
- If tracing is enabled in your Mastra deployment and memory is configured either with `lastMessages` and/or `semanticRecall`, the agent’s trace output will show all messages retrieved for context—including both recent conversation history and messages recalled via semantic recall.
59
+ ## Storage
106
60
 
107
- This is helpful for debugging, understanding agent decisions, and verifying that the agent is retrieving the right information for each request.
61
+ Before enabling memory, you must first configure a storage adapter. Mastra supports multiple database providers including PostgreSQL, MongoDB, libSQL, and more.
108
62
 
109
- For more details on enabling and configuring tracing, see [Tracing](../observability/tracing/overview).
63
+ Storage can be configured at the instance level (shared across all agents) or at the agent level (dedicated per agent). You can also use different databases for storage and vector operations.
110
64
 
111
- ## Local development with LibSQL
65
+ See the [Storage](/docs/v1/memory/storage) documentation for configuration options, supported providers, and examples.
112
66
 
113
- For local development with `LibSQLStore`, you can inspect stored memory using the [SQLite Viewer](https://marketplace.visualstudio.com/items?itemName=qwtel.sqlite-viewer) extension in VS Code.
67
+ ## Debugging memory
114
68
 
115
- ![SQLite Viewer](/img/memory/memory-sqlite-viewer.jpg)
69
+ When tracing is enabled, you can inspect exactly which messages the agent uses for context in each request. The trace output shows all memory included in the agent's context window - both recent message history and messages recalled via semantic recall.
116
70
 
117
- ## Next Steps
71
+ This visibility helps you understand why an agent made specific decisions and verify that memory retrieval is working as expected.
72
+
73
+ For more details on enabling and configuring tracing, see [Tracing](/docs/v1/observability/tracing/overview).
118
74
 
119
- Now that you understand the core concepts, continue to [semantic recall](./semantic-recall) to learn how to add RAG memory to your Mastra agents.
75
+ ## Next Steps
120
76
 
121
- Alternatively you can visit the [configuration reference](/reference/v1/memory/memory-class) for available options.
77
+ - Learn more about [Storage](/docs/v1/memory/storage) providers and configuration options
78
+ - Add [Message History](/docs/v1/memory/message-history), [Working Memory](/docs/v1/memory/working-memory), or [Semantic Recall](/docs/v1/memory/semantic-recall)
79
+ - Visit [Memory configuration reference](/reference/v1/memory/memory-class) for all available options
@@ -7,20 +7,19 @@ description: "Learn how to use semantic recall in Mastra to retrieve relevant me
7
7
 
8
8
  If you ask your friend what they did last weekend, they will search in their memory for events associated with "last weekend" and then tell you what they did. That's sort of like how semantic recall works in Mastra.
9
9
 
10
- > **📹 Watch**: What semantic recall is, how it works, and how to configure it in Mastra → [YouTube (5 minutes)](https://youtu.be/UVZtK8cK8xQ)
10
+ :::tip[Watch 📹]
11
+
12
+ What semantic recall is, how it works, and how to configure it in Mastra → [YouTube (5 minutes)](https://youtu.be/UVZtK8cK8xQ)
13
+
14
+ :::
11
15
 
12
16
  ## How Semantic Recall Works
13
17
 
14
- Semantic recall is RAG-based search that helps agents maintain context across longer interactions when messages are no longer within [recent conversation history](./conversation-history).
18
+ Semantic recall is RAG-based search that helps agents maintain context across longer interactions when messages are no longer within [recent message history](./message-history).
15
19
 
16
20
  It uses vector embeddings of messages for similarity search, integrates with various vector stores, and has configurable context windows around retrieved messages.
17
21
 
18
- <br />
19
- <img
20
- src="/img/semantic-recall.png"
21
- alt="Diagram showing Mastra Memory semantic recall"
22
- width={800}
23
- />
22
+ ![Diagram showing Mastra Memory semantic recall](/img/semantic-recall.png)
24
23
 
25
24
  When it's enabled, new messages are used to query a vector DB for semantically similar messages.
26
25
 
@@ -30,7 +29,7 @@ After getting a response from the LLM, all new messages (user, assistant, and to
30
29
 
31
30
  Semantic recall is enabled by default, so if you give your agent memory it will be included:
32
31
 
33
- ```typescript {8}
32
+ ```typescript {9}
34
33
  import { Agent } from "@mastra/core/agent";
35
34
  import { Memory } from "@mastra/memory";
36
35
 
@@ -43,33 +42,11 @@ const agent = new Agent({
43
42
  });
44
43
  ```
45
44
 
46
- ## Recall configuration
47
-
48
- The three main parameters that control semantic recall behavior are:
49
-
50
- 1. **topK**: How many semantically similar messages to retrieve
51
- 2. **messageRange**: How much surrounding context to include with each match
52
- 3. **scope**: Whether to search within the current thread or across all threads owned by a resource (the default is resource scope).
53
-
54
- ```typescript {5-7}
55
- const agent = new Agent({
56
- memory: new Memory({
57
- options: {
58
- semanticRecall: {
59
- topK: 3, // Retrieve 3 most similar messages
60
- messageRange: 2, // Include 2 messages before and after each match
61
- scope: "resource", // Search across all threads for this user (default setting if omitted)
62
- },
63
- },
64
- }),
65
- });
66
- ```
67
-
68
- ### Storage configuration
45
+ ## Storage configuration
69
46
 
70
47
  Semantic recall relies on a [storage and vector db](/reference/v1/memory/memory-class) to store messages and their embeddings.
71
48
 
72
- ```ts {8-17}
49
+ ```ts {8-16}
73
50
  import { Memory } from "@mastra/memory";
74
51
  import { Agent } from "@mastra/core/agent";
75
52
  import { LibSQLStore, LibSQLVector } from "@mastra/libsql";
@@ -90,14 +67,49 @@ const agent = new Agent({
90
67
  });
91
68
  ```
92
69
 
93
- **Storage/vector code Examples**:
70
+ Each vector store page below includes installation instructions, configuration parameters, and usage examples:
71
+
72
+ - [Astra](/reference/v1/vectors/astra)
73
+ - [Chroma](/reference/v1/vectors/chroma)
74
+ - [Cloudflare Vectorize](/reference/v1/vectors/vectorize)
75
+ - [Convex](/reference/v1/vectors/convex)
76
+ - [Couchbase](/reference/v1/vectors/couchbase)
77
+ - [DuckDB](/reference/v1/vectors/duckdb)
78
+ - [Elasticsearch](/reference/v1/vectors/elasticsearch)
79
+ - [LanceDB](/reference/v1/vectors/lance)
80
+ - [libSQL](/reference/v1/vectors/libsql)
81
+ - [MongoDB](/reference/v1/vectors/mongodb)
82
+ - [OpenSearch](/reference/v1/vectors/opensearch)
83
+ - [Pinecone](/reference/v1/vectors/pinecone)
84
+ - [PostgreSQL](/reference/v1/vectors/pg)
85
+ - [Qdrant](/reference/v1/vectors/qdrant)
86
+ - [S3 Vectors](/reference/v1/vectors/s3vectors)
87
+ - [Turbopuffer](/reference/v1/vectors/turbopuffer)
88
+ - [Upstash](/reference/v1/vectors/upstash)
89
+
90
+ ## Recall configuration
91
+
92
+ The three main parameters that control semantic recall behavior are:
94
93
 
95
- - [LibSQL](/docs/v1/memory/storage/memory-with-libsql)
96
- - [MongoDB](/docs/v1/memory/storage/memory-with-mongodb)
97
- - [Postgres](/docs/v1/memory/storage/memory-with-pg)
98
- - [Upstash](/docs/v1/memory/storage/memory-with-upstash)
94
+ 1. **topK**: How many semantically similar messages to retrieve
95
+ 2. **messageRange**: How much surrounding context to include with each match
96
+ 3. **scope**: Whether to search within the current thread or across all threads owned by a resource (the default is resource scope).
97
+
98
+ ```typescript {5-7}
99
+ const agent = new Agent({
100
+ memory: new Memory({
101
+ options: {
102
+ semanticRecall: {
103
+ topK: 3, // Retrieve 3 most similar messages
104
+ messageRange: 2, // Include 2 messages before and after each match
105
+ scope: "resource", // Search across all threads for this user (default setting if omitted)
106
+ },
107
+ },
108
+ }),
109
+ });
110
+ ```
99
111
 
100
- ### Embedder configuration
112
+ ## Embedder configuration
101
113
 
102
114
  Semantic recall relies on an [embedding model](/reference/v1/memory/memory-class) to convert messages into embeddings. Mastra supports embedding models through the model router using `provider/model` strings, or you can use any [embedding model](https://sdk.vercel.ai/docs/ai-sdk-core/embeddings) compatible with the AI SDK.
103
115
 
@@ -112,7 +124,6 @@ import { ModelRouterEmbeddingModel } from "@mastra/core/llm";
112
124
 
113
125
  const agent = new Agent({
114
126
  memory: new Memory({
115
- // ... other memory options
116
127
  embedder: new ModelRouterEmbeddingModel("openai/text-embedding-3-small"),
117
128
  }),
118
129
  });
@@ -136,7 +147,6 @@ import { ModelRouterEmbeddingModel } from "@mastra/core/llm";
136
147
 
137
148
  const agent = new Agent({
138
149
  memory: new Memory({
139
- // ... other memory options
140
150
  embedder: new ModelRouterEmbeddingModel("openai/text-embedding-3-small"),
141
151
  }),
142
152
  });
@@ -146,32 +156,31 @@ const agent = new Agent({
146
156
 
147
157
  To use FastEmbed (a local embedding model), install `@mastra/fastembed`:
148
158
 
149
- ```bash npm2yarn copy
159
+ ```bash npm2yarn
150
160
  npm install @mastra/fastembed@beta
151
161
  ```
152
162
 
153
163
  Then configure it in your memory:
154
164
 
155
- ```ts {3,8}
165
+ ```ts {3,7}
156
166
  import { Memory } from "@mastra/memory";
157
167
  import { Agent } from "@mastra/core/agent";
158
168
  import { fastembed } from "@mastra/fastembed";
159
169
 
160
170
  const agent = new Agent({
161
171
  memory: new Memory({
162
- // ... other memory options
163
172
  embedder: fastembed,
164
173
  }),
165
174
  });
166
175
  ```
167
176
 
168
- ### PostgreSQL Index Optimization
177
+ ## PostgreSQL Index Optimization
169
178
 
170
179
  When using PostgreSQL as your vector store, you can optimize semantic recall performance by configuring the vector index. This is particularly important for large-scale deployments with thousands of messages.
171
180
 
172
181
  PostgreSQL supports both IVFFlat and HNSW indexes. By default, Mastra creates an IVFFlat index, but HNSW indexes typically provide better performance, especially with OpenAI embeddings which use inner product distance.
173
182
 
174
- ```typescript {9-18}
183
+ ```typescript {18-23}
175
184
  import { Memory } from "@mastra/memory";
176
185
  import { PgStore, PgVector } from "@mastra/pg";
177
186
 
@@ -203,7 +212,7 @@ const agent = new Agent({
203
212
 
204
213
  For detailed information about index configuration options and performance tuning, see the [PgVector configuration guide](/reference/v1/vectors/pg#index-configuration-guide).
205
214
 
206
- ### Disabling
215
+ ## Disabling
207
216
 
208
217
  There is a performance impact to using semantic recall. New messages are converted into embeddings and used to query a vector database before new messages are sent to the LLM.
209
218
 
@@ -221,11 +230,11 @@ const agent = new Agent({
221
230
 
222
231
  You might want to disable semantic recall in scenarios like:
223
232
 
224
- - When conversation history provide sufficient context for the current conversation.
233
+ - When message history provides sufficient context for the current conversation.
225
234
  - In performance-sensitive applications, like realtime two-way audio, where the added latency of creating embeddings and running vector queries is noticeable.
226
235
 
227
236
  ## Viewing Recalled Messages
228
237
 
229
- When tracing is enabled, any messages retrieved via semantic recall will appear in the agents trace output, alongside recent conversation history (if configured).
238
+ When tracing is enabled, any messages retrieved via semantic recall will appear in the agent's trace output, alongside recent message history (if configured).
230
239
 
231
240
  For more info on viewing message traces, see [Viewing Retrieved Messages](./overview#viewing-retrieved-messages).
@@ -0,0 +1,188 @@
1
+ ---
2
+ title: "Storage | Memory"
3
+ description: Configure storage for Mastra's memory system to persist conversations, workflows, and traces.
4
+ ---
5
+
6
+ # Storage
7
+
8
+ For Mastra to remember previous interactions, you must configure a storage adapter. Mastra is designed to work with your preferred database provider - choose from the [supported providers](#supported-providers) and pass it to your Mastra instance.
9
+
10
+
11
+ ```typescript
12
+ import { Mastra } from "@mastra/core";
13
+ import { LibSQLStore } from "@mastra/libsql";
14
+
15
+ const mastra = new Mastra({
16
+ storage: new LibSQLStore({
17
+ id: 'mastra-storage',
18
+ url: "file:./mastra.db",
19
+ }),
20
+ });
21
+ ```
22
+ On first interaction, Mastra automatically creates the necessary tables following the [core schema](/reference/v1/storage/overview#core-schema). This includes tables for messages, threads, resources, workflows, traces, and evaluation datasets.
23
+
24
+ ## Supported Providers
25
+
26
+ Each provider page includes installation instructions, configuration parameters, and usage examples:
27
+
28
+ - [libSQL Storage](/reference/v1/storage/libsql)
29
+ - [PostgreSQL Storage](/reference/v1/storage/postgresql)
30
+ - [MongoDB Storage](/reference/v1/storage/mongodb)
31
+ - [Upstash Storage](/reference/v1/storage/upstash)
32
+ - [Cloudflare D1](/reference/v1/storage/cloudflare-d1)
33
+ - [Cloudflare Durable Objects](/reference/v1/storage/cloudflare)
34
+ - [Convex](/reference/v1/storage/convex)
35
+ - [DynamoDB](/reference/v1/storage/dynamodb)
36
+ - [LanceDB](/reference/v1/storage/lance)
37
+ - [Microsoft SQL Server](/reference/v1/storage/mssql)
38
+
39
+ :::tip
40
+ libSQL is the easiest way to get started because it doesn’t require running a separate database server
41
+ :::
42
+
43
+ ## Configuration Scope
44
+
45
+ You can configure storage at two different scopes:
46
+
47
+ ### Instance-level storage
48
+
49
+ Add storage to your Mastra instance so all agents share the same memory provider:
50
+
51
+ ```typescript
52
+ import { Mastra } from "@mastra/core";
53
+ import { PostgresStore } from "@mastra/pg";
54
+
55
+ const mastra = new Mastra({
56
+ storage: new PostgresStore({
57
+ id: 'mastra-storage',
58
+ connectionString: process.env.DATABASE_URL,
59
+ }),
60
+ });
61
+
62
+ // All agents automatically use this storage
63
+ const agent1 = new Agent({ memory: new Memory() });
64
+ const agent2 = new Agent({ memory: new Memory() });
65
+ ```
66
+
67
+ ### Agent-level storage
68
+
69
+ Add storage to a specific agent when you need data boundaries or compliance requirements:
70
+
71
+ ```typescript
72
+ import { Agent } from "@mastra/core/agent";
73
+ import { Memory } from "@mastra/memory";
74
+ import { PostgresStore } from "@mastra/pg";
75
+
76
+ const agent = new Agent({
77
+ memory: new Memory({
78
+ storage: new PostgresStore({
79
+ id: 'agent-storage',
80
+ connectionString: process.env.AGENT_DATABASE_URL,
81
+ }),
82
+ }),
83
+ });
84
+ ```
85
+
86
+ This is useful when different agents need to store data in separate databases for security, compliance, or organizational reasons.
87
+
88
+ ## Threads and Resources
89
+
90
+ Mastra organizes memory into threads using two identifiers:
91
+
92
+ - **Thread**: A conversation session containing a sequence of messages (e.g., `convo_123`)
93
+ - **Resource**: An identifier for the entity the thread belongs to, typically a user (e.g., `user_123`)
94
+
95
+ Both identifiers are required for agents to store and recall information:
96
+
97
+ ```typescript
98
+ const stream = await agent.stream("message for agent", {
99
+ memory: {
100
+ thread: "convo_123",
101
+ resource: "user_123",
102
+ },
103
+ });
104
+ ```
105
+
106
+ :::note
107
+ [Studio](/docs/v1/getting-started/studio) automatically generates a thread and resource ID for you. Remember to to pass these explicitly when calling `stream` or `generate` yourself.
108
+ :::
109
+
110
+ ### Thread title generation
111
+
112
+ Mastra can automatically generate descriptive thread titles based on the user's first message.
113
+
114
+ Use this option when implementing a ChatGPT-style chat interface to render a title alongside each thread in the conversation list (for example, in a sidebar) derived from the thread’s initial user message.
115
+
116
+ ```typescript
117
+ export const testAgent = new Agent({
118
+ memory: new Memory({
119
+ options: {
120
+ generateTitle: true,
121
+ },
122
+ }),
123
+ });
124
+ ```
125
+
126
+ Title generation runs asynchronously after the agent responds and does not affect response time.
127
+
128
+ To optimize cost or behavior, provide a smaller `model` and custom `instructions`:
129
+
130
+ ```typescript
131
+ export const testAgent = new Agent({
132
+ memory: new Memory({
133
+ options: {
134
+ threads: {
135
+ generateTitle: {
136
+ model: "openai/gpt-4o-mini",
137
+ instructions: "Generate a concise title based on the user's first message",
138
+ },
139
+ },
140
+ },
141
+ }),
142
+ });
143
+ ```
144
+
145
+ ## Semantic recall
146
+
147
+ Semantic recall uses vector embeddings to retrieve relevant past messages based on meaning rather than recency. This requires a vector database instance, which can be configured at the instance or agent level.
148
+
149
+ The vector database doesn't have to be the same as your storage provider. For example, you might use PostgreSQL for storage and Pinecone for vectors:
150
+
151
+ ```typescript
152
+ import { Mastra } from "@mastra/core";
153
+ import { Agent } from "@mastra/core/agent";
154
+ import { Memory } from "@mastra/memory";
155
+ import { PostgresStore } from "@mastra/pg";
156
+ import { PineconeVector } from "@mastra/pinecone";
157
+
158
+ // Instance-level vector configuration
159
+ const mastra = new Mastra({
160
+ storage: new PostgresStore({
161
+ id: 'mastra-storage',
162
+ connectionString: process.env.DATABASE_URL,
163
+ }),
164
+ });
165
+
166
+ // Agent-level vector configuration
167
+ const agent = new Agent({
168
+ memory: new Memory({
169
+ vector: new PineconeVector({
170
+ id: 'agent-vector',
171
+ apiKey: process.env.PINECONE_API_KEY,
172
+ environment: process.env.PINECONE_ENVIRONMENT,
173
+ indexName: 'agent-embeddings',
174
+ }),
175
+ options: {
176
+ semanticRecall: {
177
+ topK: 5,
178
+ messageRange: 2,
179
+ },
180
+ },
181
+ }),
182
+ });
183
+ ```
184
+
185
+ We support all popular vector providers including [Pinecone](/reference/v1/vectors/pinecone), [Chroma](/reference/v1/vectors/chroma), [Qdrant](/reference/v1/vectors/qdrant), and many more.
186
+
187
+ For more information on configuring semantic recall, see the [Semantic Recall](./semantic-recall) documentation.
188
+
@@ -7,7 +7,7 @@ import YouTube from "@site/src/components/YouTube-player";
7
7
 
8
8
  # Working Memory
9
9
 
10
- While [conversation history](/docs/v1/memory/conversation-history) and [semantic recall](./semantic-recall) help agents remember conversations, working memory allows them to maintain persistent information about users across interactions.
10
+ While [message history](/docs/v1/memory/message-history) and [semantic recall](./semantic-recall) help agents remember conversations, working memory allows them to maintain persistent information about users across interactions.
11
11
 
12
12
  Think of it as the agent's active thoughts or scratchpad – the key information they keep available about the user or task. It's similar to how a person would naturally remember someone's name, preferences, or important details during a conversation.
13
13
 
@@ -24,7 +24,7 @@ Working memory can persist at two different scopes:
24
24
 
25
25
  Here's a minimal example of setting up an agent with working memory:
26
26
 
27
- ```typescript {11-14}
27
+ ```typescript {11-15}
28
28
  import { Agent } from "@mastra/core/agent";
29
29
  import { Memory } from "@mastra/memory";
30
30
 
@@ -126,9 +126,9 @@ const memory = new Memory({
126
126
 
127
127
  Resource-scoped working memory requires specific storage adapters that support the `mastra_resources` table:
128
128
 
129
- ### Supported Storage Adapters
129
+ ### Supported Storage Adapters
130
130
 
131
- - **LibSQL** (`@mastra/libsql`)
131
+ - **libSQL** (`@mastra/libsql`)
132
132
  - **PostgreSQL** (`@mastra/pg`)
133
133
  - **Upstash** (`@mastra/upstash`)
134
134
  - **MongoDB** (`@mastra/mongodb`)
@@ -325,7 +325,7 @@ While agents typically update working memory through the `updateWorkingMemory` t
325
325
 
326
326
  When creating a thread, you can provide initial working memory through the metadata's `workingMemory` key:
327
327
 
328
- ```typescript title="src/app/medical-consultation.ts" showLineNumbers copy
328
+ ```typescript title="src/app/medical-consultation.ts"
329
329
  // Create a thread with initial working memory
330
330
  const thread = await memory.createThread({
331
331
  threadId: "thread-123",
@@ -354,7 +354,7 @@ await agent.generate("What's my blood type?", {
354
354
 
355
355
  You can also update an existing thread's working memory:
356
356
 
357
- ```typescript title="src/app/medical-consultation.ts" showLineNumbers copy
357
+ ```typescript title="src/app/medical-consultation.ts"
358
358
  // Update thread metadata to add/modify working memory
359
359
  await memory.updateThread({
360
360
  id: "thread-123",
@@ -376,7 +376,7 @@ await memory.updateThread({
376
376
 
377
377
  Alternatively, use the `updateWorkingMemory` method directly:
378
378
 
379
- ```typescript title="src/app/medical-consultation.ts" showLineNumbers copy
379
+ ```typescript title="src/app/medical-consultation.ts"
380
380
  await memory.updateWorkingMemory({
381
381
  threadId: "thread-123",
382
382
  resourceId: "user-456", // Required for resource-scoped memory