@mastra/memory 0.0.0-knowledge-studio-20261029065150 → 0.0.0-knowledge-alpha-studio-20261030162625

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 (139) hide show
  1. package/dist/_types/@internal_ai-sdk-v4/dist/index.d.ts +51 -12
  2. package/dist/docs/SKILL.md +1 -1
  3. package/dist/docs/assets/SOURCE_MAP.json +202 -3
  4. package/dist/docs/references/docs-agents-human-in-the-loop.md +10 -1
  5. package/dist/docs/references/docs-guides-context-engineering.md +2 -2
  6. package/dist/docs/references/docs-harness-background-tasks.md +89 -1
  7. package/dist/docs/references/docs-harness-goals.md +2 -0
  8. package/dist/docs/references/docs-memory-memory-processors.md +49 -3
  9. package/dist/docs/references/docs-memory-message-history.md +3 -0
  10. package/dist/docs/references/docs-memory-observational-memory.md +37 -1
  11. package/dist/docs/references/docs-memory-overview.md +6 -0
  12. package/dist/docs/references/docs-memory-semantic-recall.md +9 -3
  13. package/dist/docs/references/docs-subagents.md +7 -1
  14. package/dist/docs/references/integrations-databases-aurora-dsql.md +2 -2
  15. package/dist/docs/references/integrations-databases-dynamodb.md +4 -4
  16. package/dist/docs/references/integrations-databases-postgresql.md +35 -4
  17. package/dist/docs/references/reference-memory-cloneThread.md +2 -2
  18. package/dist/docs/references/reference-memory-memory-class.md +87 -8
  19. package/dist/docs/references/reference-memory-observational-memory.md +10 -10
  20. package/dist/docs/references/reference-memory-summarizeConversation.md +1 -1
  21. package/dist/docs/references/reference-memory-summarizeThread.md +1 -1
  22. package/dist/docs/references/reference-vectors-mongodb.md +6 -6
  23. package/dist/docs/references/reference-vectors-pg.md +1 -1
  24. package/dist/docs/references/reference-vectors-upstash.md +8 -4
  25. package/dist/hooks.cjs +1 -2
  26. package/dist/hooks.js +1 -2
  27. package/dist/index.cjs +7 -10
  28. package/dist/index.d.ts +11 -43
  29. package/dist/index.d.ts.map +1 -1
  30. package/dist/index.js +1 -4
  31. package/dist/processors/index.cjs +9 -19
  32. package/dist/processors/index.js +1 -4
  33. package/dist/processors/observational-memory/buffering-coordinator.d.ts +1 -1
  34. package/dist/processors/observational-memory/buffering-coordinator.d.ts.map +1 -1
  35. package/dist/processors/observational-memory/commit-queue.d.ts +5 -1
  36. package/dist/processors/observational-memory/commit-queue.d.ts.map +1 -1
  37. package/dist/processors/observational-memory/constants.d.ts +3 -3
  38. package/dist/processors/observational-memory/constants.d.ts.map +1 -1
  39. package/dist/processors/observational-memory/date-utils.d.ts.map +1 -1
  40. package/dist/processors/observational-memory/error.d.ts +10 -2
  41. package/dist/processors/observational-memory/error.d.ts.map +1 -1
  42. package/dist/processors/observational-memory/extractor.d.ts.map +1 -1
  43. package/dist/processors/observational-memory/hooks.d.ts +1 -1
  44. package/dist/processors/observational-memory/hooks.d.ts.map +1 -1
  45. package/dist/processors/observational-memory/index.d.ts +0 -2
  46. package/dist/processors/observational-memory/index.d.ts.map +1 -1
  47. package/dist/processors/observational-memory/model-by-input-tokens.d.ts.map +1 -1
  48. package/dist/processors/observational-memory/observation-strategies/async-buffer.d.ts +2 -2
  49. package/dist/processors/observational-memory/observation-strategies/async-buffer.d.ts.map +1 -1
  50. package/dist/processors/observational-memory/observation-strategies/base.d.ts.map +1 -1
  51. package/dist/processors/observational-memory/observation-strategies/resource-scoped.d.ts.map +1 -1
  52. package/dist/processors/observational-memory/observation-strategies/sync.d.ts +2 -2
  53. package/dist/processors/observational-memory/observation-strategies/sync.d.ts.map +1 -1
  54. package/dist/processors/observational-memory/observation-turn/step.d.ts.map +1 -1
  55. package/dist/processors/observational-memory/observation-turn/turn.d.ts +2 -6
  56. package/dist/processors/observational-memory/observation-turn/turn.d.ts.map +1 -1
  57. package/dist/processors/observational-memory/observational-memory.d.ts +7 -2
  58. package/dist/processors/observational-memory/observational-memory.d.ts.map +1 -1
  59. package/dist/processors/observational-memory/observer-agent.d.ts.map +1 -1
  60. package/dist/processors/observational-memory/observer-runner.d.ts.map +1 -1
  61. package/dist/processors/observational-memory/processor.d.ts +7 -7
  62. package/dist/processors/observational-memory/processor.d.ts.map +1 -1
  63. package/dist/processors/observational-memory/reflector-runner.d.ts +3 -6
  64. package/dist/processors/observational-memory/reflector-runner.d.ts.map +1 -1
  65. package/dist/processors/observational-memory/retry.d.ts +11 -0
  66. package/dist/processors/observational-memory/retry.d.ts.map +1 -1
  67. package/dist/processors/observational-memory/summarize.d.ts.map +1 -1
  68. package/dist/processors/observational-memory/thresholds.d.ts.map +1 -1
  69. package/dist/processors/observational-memory/token-counter.d.ts.map +1 -1
  70. package/dist/processors/observational-memory/tool-result-helpers.d.ts +6 -0
  71. package/dist/processors/observational-memory/tool-result-helpers.d.ts.map +1 -1
  72. package/dist/processors/observational-memory/types.d.ts +2 -17
  73. package/dist/processors/observational-memory/types.d.ts.map +1 -1
  74. package/dist/processors/observational-memory/wait-with-abort.d.ts +3 -0
  75. package/dist/processors/observational-memory/wait-with-abort.d.ts.map +1 -0
  76. package/dist/processors/observational-memory/working-memory-extractor.d.ts.map +1 -1
  77. package/dist/processors/working-memory-state/processor.d.ts.map +1 -1
  78. package/dist/removed-subconscious.d.ts +33 -0
  79. package/dist/removed-subconscious.d.ts.map +1 -0
  80. package/dist/{src-D93hWhh9.cjs → src-B5HHamRw.cjs} +3314 -2536
  81. package/dist/src-B5HHamRw.cjs.map +1 -0
  82. package/dist/{src-B6iLOSPj.js → src-CoLfois6.js} +2504 -1811
  83. package/dist/src-CoLfois6.js.map +1 -0
  84. package/dist/tools/om-tools.d.ts +1 -1
  85. package/dist/tools/om-tools.d.ts.map +1 -1
  86. package/dist/tools/working-memory.d.ts.map +1 -1
  87. package/package.json +17 -19
  88. package/dist/constants-BMbSss4t.js +0 -222
  89. package/dist/constants-BMbSss4t.js.map +0 -1
  90. package/dist/constants-B_7Hh_kA.cjs +0 -268
  91. package/dist/constants-B_7Hh_kA.cjs.map +0 -1
  92. package/dist/processors/observational-memory/context-overflow.d.ts +0 -2
  93. package/dist/processors/observational-memory/context-overflow.d.ts.map +0 -1
  94. package/dist/processors/observational-memory/subconscious/activity.d.ts +0 -39
  95. package/dist/processors/observational-memory/subconscious/activity.d.ts.map +0 -1
  96. package/dist/processors/observational-memory/subconscious/curate.d.ts +0 -20
  97. package/dist/processors/observational-memory/subconscious/curate.d.ts.map +0 -1
  98. package/dist/processors/observational-memory/subconscious/index.d.ts +0 -41
  99. package/dist/processors/observational-memory/subconscious/index.d.ts.map +0 -1
  100. package/dist/processors/observational-memory/subconscious/knowledge-tools.d.ts +0 -56
  101. package/dist/processors/observational-memory/subconscious/knowledge-tools.d.ts.map +0 -1
  102. package/dist/processors/observational-memory/subconscious/knowledge-write-tools.d.ts +0 -33
  103. package/dist/processors/observational-memory/subconscious/knowledge-write-tools.d.ts.map +0 -1
  104. package/dist/processors/observational-memory/subconscious/model.d.ts +0 -21
  105. package/dist/processors/observational-memory/subconscious/model.d.ts.map +0 -1
  106. package/dist/processors/observational-memory/subconscious/origin.d.ts +0 -4
  107. package/dist/processors/observational-memory/subconscious/origin.d.ts.map +0 -1
  108. package/dist/processors/observational-memory/subconscious/pinned-state-processor.d.ts +0 -49
  109. package/dist/processors/observational-memory/subconscious/pinned-state-processor.d.ts.map +0 -1
  110. package/dist/processors/observational-memory/subconscious/pinned.d.ts +0 -48
  111. package/dist/processors/observational-memory/subconscious/pinned.d.ts.map +0 -1
  112. package/dist/processors/observational-memory/subconscious/remind-agent.d.ts +0 -22
  113. package/dist/processors/observational-memory/subconscious/remind-agent.d.ts.map +0 -1
  114. package/dist/processors/observational-memory/subconscious/remind-continuation.d.ts +0 -21
  115. package/dist/processors/observational-memory/subconscious/remind-continuation.d.ts.map +0 -1
  116. package/dist/processors/observational-memory/subconscious/remind-protocol.d.ts +0 -28
  117. package/dist/processors/observational-memory/subconscious/remind-protocol.d.ts.map +0 -1
  118. package/dist/processors/observational-memory/subconscious/remind-questions.d.ts +0 -27
  119. package/dist/processors/observational-memory/subconscious/remind-questions.d.ts.map +0 -1
  120. package/dist/processors/observational-memory/subconscious/remind.d.ts +0 -7
  121. package/dist/processors/observational-memory/subconscious/remind.d.ts.map +0 -1
  122. package/dist/processors/observational-memory/subconscious/semantic-index.d.ts +0 -35
  123. package/dist/processors/observational-memory/subconscious/semantic-index.d.ts.map +0 -1
  124. package/dist/processors/observational-memory/subconscious/types.d.ts +0 -62
  125. package/dist/processors/observational-memory/subconscious/types.d.ts.map +0 -1
  126. package/dist/rolldown-runtime-C0BPl7ul.cjs +0 -43
  127. package/dist/rolldown-runtime-D7D4PA-g.js +0 -13
  128. package/dist/src-B6iLOSPj.js.map +0 -1
  129. package/dist/src-D93hWhh9.cjs.map +0 -1
  130. package/dist/subconscious-C6KnpTX1.cjs +0 -3154
  131. package/dist/subconscious-C6KnpTX1.cjs.map +0 -1
  132. package/dist/subconscious-DymaJfiT.js +0 -2999
  133. package/dist/subconscious-DymaJfiT.js.map +0 -1
  134. package/dist/tools/knowledge-tools.d.ts +0 -17
  135. package/dist/tools/knowledge-tools.d.ts.map +0 -1
  136. package/dist/working-memory-state-BfJSW2JH.cjs +0 -181
  137. package/dist/working-memory-state-BfJSW2JH.cjs.map +0 -1
  138. package/dist/working-memory-state-CiTsbBgE.js +0 -158
  139. package/dist/working-memory-state-CiTsbBgE.js.map +0 -1
@@ -35,6 +35,36 @@ export declare class AISDKError extends Error {
35
35
  protected static hasMarker(error: unknown, marker: string): boolean;
36
36
  }
37
37
 
38
+ /**
39
+ * AnyValue can be:
40
+ * - a string, number, boolean value
41
+ * - a byte array (Uint8Array)
42
+ * - array of any value
43
+ * - map from string to any value (a plain Object)
44
+ * - null (an empty value)
45
+ *
46
+ * https://opentelemetry.io/docs/specs/otel/common/#anyvalue
47
+ *
48
+ * Notable JavaScript types that are excluded:
49
+ * - `undefined` - Excluding this means the common practice in instrumentations,
50
+ * using `undefined` to mean "no value for this optional attribute", can
51
+ * remain supported.
52
+ * - `BigInt`
53
+ * - TypedArrays other than `Uint8Array`
54
+ * - subclasses of Object, e.g. Date, Error
55
+ *
56
+ * The TypeScript type `unknown` is used for `AnyValue`. This has some
57
+ * implications:
58
+ * - Callers of `@opentelemetry/api` APIs using `AnyValue` can pass in
59
+ * whatever type. This was always the case for (untyped) JavaScript usage.
60
+ * - SDK implementations of `@opentelemetry/api` need to document if/when they
61
+ * support a subset of AnyValue types.
62
+ * - Using `unknown` allows future changes to support more types (e.g. BigInt).
63
+ *
64
+ * @since 1.10.0
65
+ */
66
+ declare type AnyValue = unknown;
67
+
38
68
  export declare class APICallError extends AISDKError {
39
69
  private readonly [symbol$c_2];
40
70
  readonly url: string;
@@ -193,24 +223,20 @@ export declare interface Attachment {
193
223
  }
194
224
 
195
225
  /**
196
- * Attributes is a map from string to attribute values.
197
- *
198
- * Note: only the own enumerable keys are counted as valid attribute keys.
226
+ * Attributes is a mapping from string to attribute values.
227
+ * https://opentelemetry.io/docs/specs/otel/common/#attribute-collections
199
228
  *
200
- * @since 1.3.0
229
+ * @since 1.1.0
201
230
  */
202
231
  declare interface Attributes {
203
- [attributeKey: string]: AttributeValue | undefined;
232
+ [attributeKey: string]: AnyValue;
204
233
  }
205
234
 
206
235
  /**
207
- * Attribute values may be any non-nullish primitive value except an object.
208
- *
209
- * null or undefined attribute values are invalid and will result in undefined behavior.
210
- *
211
- * @since 1.3.0
236
+ * @since 1.1.0
237
+ * @deprecated use AnyValue
212
238
  */
213
- declare type AttributeValue = string | number | boolean | Array<null | undefined | string> | Array<null | undefined | number> | Array<null | undefined | boolean>;
239
+ declare type AttributeValue = AnyValue;
214
240
 
215
241
  declare type CallSettings = {
216
242
  /**
@@ -4281,7 +4307,11 @@ declare interface Link {
4281
4307
  context: SpanContext;
4282
4308
  /** A set of {@link SpanAttributes} on the link. */
4283
4309
  attributes?: SpanAttributes;
4284
- /** Count of attributes of the link that were dropped due to collection limits */
4310
+ /**
4311
+ * Count of attributes of the link that were dropped due to collection limits
4312
+ *
4313
+ * @since 1.4.1
4314
+ */
4285
4315
  droppedAttributesCount?: number;
4286
4316
  }
4287
4317
 
@@ -5193,6 +5223,8 @@ declare interface Span {
5193
5223
  * It is preferred span links be added at span creation.
5194
5224
  *
5195
5225
  * @param link the link to add.
5226
+ *
5227
+ * @since 1.9.0
5196
5228
  */
5197
5229
  addLink(link: Link): this;
5198
5230
  /**
@@ -5202,6 +5234,8 @@ declare interface Span {
5202
5234
  * It is preferred span links be added at span creation.
5203
5235
  *
5204
5236
  * @param links the links to add.
5237
+ *
5238
+ * @since 1.9.0
5205
5239
  */
5206
5240
  addLinks(links: Link[]): this;
5207
5241
  /**
@@ -6995,6 +7029,11 @@ declare interface Tracer {
6995
7029
  * Additionally the new span gets set in context and this context is activated
6996
7030
  * for the duration of the function call.
6997
7031
  *
7032
+ * **Important**: The callback function is responsible for calling `span.end()`
7033
+ * to finish the span. Unlike some other OpenTelemetry implementations, the span
7034
+ * is NOT automatically ended when the callback returns. If `span.end()` is not
7035
+ * called, the span will never be exported and will be silently lost.
7036
+ *
6998
7037
  * @param name The name of the span
6999
7038
  * @param [options] SpanOptions used for span creation
7000
7039
  * @param [context] Context to use to extract parent
@@ -3,7 +3,7 @@ name: mastra-memory
3
3
  description: Documentation for @mastra/memory. Use when working with @mastra/memory APIs, configuration, or implementation.
4
4
  metadata:
5
5
  package: "@mastra/memory"
6
- version: "0.0.0-knowledge-studio-20261029065150"
6
+ version: "0.0.0-knowledge-alpha-studio-20261030162625"
7
7
  ---
8
8
 
9
9
  ## When to use
@@ -1,11 +1,210 @@
1
1
  {
2
- "version": "0.0.0-knowledge-studio-20261029065150",
2
+ "version": "0.0.0-knowledge-alpha-studio-20261030162625",
3
3
  "package": "@mastra/memory",
4
- "exports": {},
4
+ "exports": {
5
+ "d": {
6
+ "types": "dist/processors/index.d.ts",
7
+ "implementation": "dist/src-CoLfois6.js"
8
+ },
9
+ "U": {
10
+ "types": "dist/processors/index.d.ts",
11
+ "implementation": "dist/src-CoLfois6.js"
12
+ },
13
+ "g": {
14
+ "types": "dist/processors/index.d.ts",
15
+ "implementation": "dist/src-CoLfois6.js"
16
+ },
17
+ "W": {
18
+ "types": "dist/processors/index.d.ts",
19
+ "implementation": "dist/src-CoLfois6.js"
20
+ },
21
+ "G": {
22
+ "types": "dist/processors/index.d.ts",
23
+ "implementation": "dist/src-CoLfois6.js"
24
+ },
25
+ "K": {
26
+ "types": "dist/processors/index.d.ts",
27
+ "implementation": "dist/src-CoLfois6.js"
28
+ },
29
+ "q": {
30
+ "types": "dist/processors/index.d.ts",
31
+ "implementation": "dist/src-CoLfois6.js"
32
+ },
33
+ "J": {
34
+ "types": "dist/processors/index.d.ts",
35
+ "implementation": "dist/src-CoLfois6.js"
36
+ },
37
+ "M": {
38
+ "types": "dist/processors/index.d.ts",
39
+ "implementation": "dist/src-CoLfois6.js"
40
+ },
41
+ "u": {
42
+ "types": "dist/processors/index.d.ts",
43
+ "implementation": "dist/src-CoLfois6.js"
44
+ },
45
+ "l": {
46
+ "types": "dist/processors/index.d.ts",
47
+ "implementation": "dist/src-CoLfois6.js"
48
+ },
49
+ "j": {
50
+ "types": "dist/processors/index.d.ts",
51
+ "implementation": "dist/src-CoLfois6.js"
52
+ },
53
+ "D": {
54
+ "types": "dist/processors/index.d.ts",
55
+ "implementation": "dist/src-CoLfois6.js"
56
+ },
57
+ "N": {
58
+ "types": "dist/processors/index.d.ts",
59
+ "implementation": "dist/src-CoLfois6.js"
60
+ },
61
+ "P": {
62
+ "types": "dist/processors/index.d.ts",
63
+ "implementation": "dist/src-CoLfois6.js"
64
+ },
65
+ "_": {
66
+ "types": "dist/processors/index.d.ts",
67
+ "implementation": "dist/src-CoLfois6.js"
68
+ },
69
+ "v": {
70
+ "types": "dist/processors/index.d.ts",
71
+ "implementation": "dist/src-CoLfois6.js"
72
+ },
73
+ "F": {
74
+ "types": "dist/processors/index.d.ts",
75
+ "implementation": "dist/src-CoLfois6.js"
76
+ },
77
+ "I": {
78
+ "types": "dist/processors/index.d.ts",
79
+ "implementation": "dist/src-CoLfois6.js"
80
+ },
81
+ "Y": {
82
+ "types": "dist/processors/index.d.ts",
83
+ "implementation": "dist/src-CoLfois6.js"
84
+ },
85
+ "c": {
86
+ "types": "dist/processors/index.d.ts",
87
+ "implementation": "dist/src-CoLfois6.js"
88
+ },
89
+ "L": {
90
+ "types": "dist/processors/index.d.ts",
91
+ "implementation": "dist/src-CoLfois6.js"
92
+ },
93
+ "B": {
94
+ "types": "dist/processors/index.d.ts",
95
+ "implementation": "dist/src-CoLfois6.js"
96
+ },
97
+ "R": {
98
+ "types": "dist/processors/index.d.ts",
99
+ "implementation": "dist/src-CoLfois6.js"
100
+ },
101
+ "V": {
102
+ "types": "dist/processors/index.d.ts",
103
+ "implementation": "dist/src-CoLfois6.js"
104
+ },
105
+ "y": {
106
+ "types": "dist/processors/index.d.ts",
107
+ "implementation": "dist/src-CoLfois6.js"
108
+ },
109
+ "z": {
110
+ "types": "dist/processors/index.d.ts",
111
+ "implementation": "dist/src-CoLfois6.js"
112
+ },
113
+ "b": {
114
+ "types": "dist/processors/index.d.ts",
115
+ "implementation": "dist/src-CoLfois6.js"
116
+ },
117
+ "x": {
118
+ "types": "dist/processors/index.d.ts",
119
+ "implementation": "dist/src-CoLfois6.js"
120
+ },
121
+ "f": {
122
+ "types": "dist/processors/index.d.ts",
123
+ "implementation": "dist/src-CoLfois6.js"
124
+ },
125
+ "H": {
126
+ "types": "dist/processors/index.d.ts",
127
+ "implementation": "dist/src-CoLfois6.js"
128
+ },
129
+ "S": {
130
+ "types": "dist/processors/index.d.ts",
131
+ "implementation": "dist/src-CoLfois6.js"
132
+ },
133
+ "A": {
134
+ "types": "dist/processors/index.d.ts",
135
+ "implementation": "dist/src-CoLfois6.js"
136
+ },
137
+ "C": {
138
+ "types": "dist/processors/index.d.ts",
139
+ "implementation": "dist/src-CoLfois6.js"
140
+ },
141
+ "w": {
142
+ "types": "dist/index.d.ts",
143
+ "implementation": "dist/src-CoLfois6.js"
144
+ },
145
+ "t": {
146
+ "types": "dist/index.d.ts",
147
+ "implementation": "dist/src-CoLfois6.js"
148
+ },
149
+ "n": {
150
+ "types": "dist/index.d.ts",
151
+ "implementation": "dist/src-CoLfois6.js"
152
+ },
153
+ "k": {
154
+ "types": "dist/index.d.ts",
155
+ "implementation": "dist/src-CoLfois6.js"
156
+ },
157
+ "r": {
158
+ "types": "dist/index.d.ts",
159
+ "implementation": "dist/src-CoLfois6.js"
160
+ },
161
+ "T": {
162
+ "types": "dist/index.d.ts",
163
+ "implementation": "dist/src-CoLfois6.js"
164
+ },
165
+ "E": {
166
+ "types": "dist/index.d.ts",
167
+ "implementation": "dist/src-CoLfois6.js"
168
+ },
169
+ "p": {
170
+ "types": "dist/index.d.ts",
171
+ "implementation": "dist/src-CoLfois6.js"
172
+ },
173
+ "m": {
174
+ "types": "dist/index.d.ts",
175
+ "implementation": "dist/src-CoLfois6.js"
176
+ },
177
+ "i": {
178
+ "types": "dist/index.d.ts",
179
+ "implementation": "dist/src-CoLfois6.js"
180
+ },
181
+ "h": {
182
+ "types": "dist/index.d.ts",
183
+ "implementation": "dist/src-CoLfois6.js"
184
+ },
185
+ "O": {
186
+ "types": "dist/index.d.ts",
187
+ "implementation": "dist/src-CoLfois6.js"
188
+ },
189
+ "a": {
190
+ "types": "dist/index.d.ts",
191
+ "implementation": "dist/src-CoLfois6.js"
192
+ },
193
+ "o": {
194
+ "types": "dist/index.d.ts",
195
+ "implementation": "dist/src-CoLfois6.js"
196
+ },
197
+ "s": {
198
+ "types": "dist/index.d.ts",
199
+ "implementation": "dist/src-CoLfois6.js"
200
+ }
201
+ },
5
202
  "modules": {
6
203
  "processors": {
7
204
  "index": "dist/processors/index.js",
8
- "chunks": []
205
+ "chunks": [
206
+ "src-CoLfois6.js"
207
+ ]
9
208
  }
10
209
  }
11
210
  }
@@ -116,7 +116,7 @@ const stream = await agent.stream('Clean up old records', {
116
116
  })
117
117
  ```
118
118
 
119
- The function can be asynchronous. For decisions that depend on the tool name and arguments, use a [classifier](https://mastra.ai/reference/classifier/classifier) to estimate whether the call needs human review:
119
+ The function can be asynchronous. For decisions that depend on the tool name and arguments, use a [classifier](https://mastra.ai/docs/classifier) to estimate whether the call needs human review:
120
120
 
121
121
  ```typescript
122
122
  import { Classifier } from '@mastra/core/classifier'
@@ -311,6 +311,9 @@ Instead of pausing every tool call at the agent level, you can mark individual t
311
311
  Set `requireApproval: true` on a tool definition. The tool pauses before execution regardless of whether `requireToolApproval` is set on the agent:
312
312
 
313
313
  ```typescript
314
+ import { createTool } from '@mastra/core/tools'
315
+ import { z } from 'zod'
316
+
314
317
  export const testTool = createTool({
315
318
  id: 'test-tool',
316
319
  description: 'Fetches weather for a location',
@@ -359,6 +362,9 @@ const handleApproval = async () => {
359
362
  With this approach, neither the agent nor the tool uses `requireApproval`. Instead, the tool's `execute` function calls `suspend()` to pause at a specific point and return context or confirmation prompts to the user. This is useful when approval depends on runtime conditions rather than being unconditional.
360
363
 
361
364
  ```typescript
365
+ import { createTool } from '@mastra/core/tools'
366
+ import { z } from 'zod'
367
+
362
368
  export const testToolB = createTool({
363
369
  id: 'test-tool-b',
364
370
  description: 'Fetches weather for a location',
@@ -662,6 +668,9 @@ for await (const chunk of stream.fullStream) {
662
668
  Tools can also use [`suspend()`](#approval-using-suspend) to pause execution and return context to the user. This approach works through the supervisor delegation chain the same way `requireApproval` does: the suspension surfaces at the supervisor level:
663
669
 
664
670
  ```typescript
671
+ import { createTool } from '@mastra/core/tools'
672
+ import { z } from 'zod'
673
+
665
674
  const conditionalTool = createTool({
666
675
  id: 'conditional-operation',
667
676
  description: 'Performs an operation that may require confirmation',
@@ -145,8 +145,8 @@ export const workspace = new Workspace({
145
145
  autoIndexPaths: ['**/*.md'],
146
146
  })
147
147
 
148
- // Agents receive tools including read_file, list_files, grep,
149
- // mastra_workspace_search, and mastra_workspace_index.
148
+ // Agents receive tools including mastra_workspace_read_file, mastra_workspace_list_files,
149
+ // mastra_workspace_grep, mastra_workspace_search, and mastra_workspace_index.
150
150
  await workspace.init()
151
151
  ```
152
152
 
@@ -224,6 +224,8 @@ If a subagent isn't listed under the supervisor's `backgroundTasks.tools` but ha
224
224
  The background config used for the inherited dispatch (for example `waitTimeoutMs`) is derived from the subagent's own `backgroundTasks` config.
225
225
 
226
226
  ```typescript
227
+ import { Agent } from '@mastra/core/agent'
228
+
227
229
  const researchAgent = new Agent({
228
230
  id: 'research-agent',
229
231
  description: 'Gathers factual information.',
@@ -290,6 +292,19 @@ await mastra.backgroundTaskManager?.resume(taskId, {
290
292
  })
291
293
  ```
292
294
 
295
+ ### Resume when no slot is free
296
+
297
+ By default, `resume()` throws `Concurrency limit reached` when every concurrency slot is in use. Pass `{ onNoSlot: 'queue' }` to queue the resume instead:
298
+
299
+ ```typescript
300
+ const task = await mastra.backgroundTaskManager?.resume(taskId, resumeData, { onNoSlot: 'queue' })
301
+ // task.status is still 'suspended' until a slot frees up
302
+ ```
303
+
304
+ The task stays `suspended` until a slot frees up, then resumes with the queued `resumeData`. Cancelling the task drops the queued resume.
305
+
306
+ The queue lives in the memory of the process that called `resume()`. If that process exits before the resume runs, the task stays `suspended` and the `resumeData` is lost. To survive restarts, persist the resume data yourself and call `resume()` again.
307
+
293
308
  ### What happens to the agent loop
294
309
 
295
310
  When a task suspends mid-`stream()` with `untilIdle`, the wrapper treats it as terminal for the current iteration and closes. Once the resume payload is available, call `agent.resumeStream(resumeData, { runId, toolCallId, memory, untilIdle: true })` to continue immediately. The resumed background task completes and adds its result to the message list before the agent runs a follow-up turn on the same SSE connection. To drive the resume out of band, call `mastra.backgroundTaskManager.resume(taskId, resumeData)` directly. Its result is still written into the thread for the next user turn.
@@ -308,9 +323,11 @@ Each layer can register terminal-state callbacks. They don't replace one another
308
323
 
309
324
  - Tool-level `background.onComplete` / `onFailed`: scoped to one tool.
310
325
  - Agent-level `backgroundTasks.onTaskComplete` / `onTaskFailed`: scoped to all tasks dispatched by this agent.
311
- - Manager-level `onTaskComplete` / `onTaskFailed`: scoped globally.
326
+ - Manager-level `onTaskComplete` / `onTaskFailed`: scoped globally. These fire for every task, including tasks from [non-agent owners](#non-agent-owners).
312
327
 
313
328
  ```typescript
329
+ import { Mastra } from '@mastra/core'
330
+
314
331
  export const mastra = new Mastra({
315
332
  storage,
316
333
  backgroundTasks: {
@@ -394,6 +411,77 @@ const { tasks, total } = await mastra.backgroundTaskManager?.listTasks({
394
411
 
395
412
  These read from storage rather than the pubsub stream, so they're suitable for paginated lists and detail views.
396
413
 
414
+ ## Non-agent owners
415
+
416
+ Code other than agents can run tasks through the manager. For example, an MCP server can run long tool calls as background tasks. The task's `agentId` is its owner key, and agent streams, `untilIdle`, and the end-of-step wait only see tasks whose `agentId` matches the agent. Use a namespaced owner key such as `mcp-server:<serverId>` so it can't collide with a real agent ID. Mastra doesn't enforce this.
417
+
418
+ Non-agent owners usually register a static executor with `registerStaticExecutor()` so any process can run or recover their tasks. They can also set these optional task fields:
419
+
420
+ - `expiresAt`: When cleanup deletes the task. Once a task completes, fails, is cancelled, or times out, cleanup deletes it after `expiresAt` passes instead of using `completedTtlMs` or `failedTtlMs`. Cleanup only runs when you set the `cleanup` option, and it never deletes a pending, running, or suspended task, so cancel expired work first. It also needs a storage adapter version that supports `expiresAt`. Older adapters keep using the global retention settings.
421
+ - `metadata`: JSON stored with the task. The manager doesn't read it.
422
+
423
+ ```typescript
424
+ mastra.backgroundTaskManager?.registerStaticExecutor('mcp-server:ops:deploy', {
425
+ execute: runDeploy,
426
+ })
427
+
428
+ await mastra.backgroundTaskManager?.enqueue({
429
+ agentId: 'mcp-server:ops',
430
+ toolName: 'mcp-server:ops:deploy',
431
+ toolCallId: taskId,
432
+ runId: taskId,
433
+ args,
434
+ resourceId: principalId,
435
+ expiresAt: new Date(Date.now() + 24 * 60 * 60 * 1000),
436
+ metadata: { ttlMs: 86_400_000 },
437
+ })
438
+ ```
439
+
440
+ Use `perOwnerConcurrency` to give an owner its own concurrency limit instead of `perAgentConcurrency`. Its tasks still count toward `globalConcurrency`:
441
+
442
+ ```typescript
443
+ export const mastra = new Mastra({
444
+ storage,
445
+ backgroundTasks: {
446
+ enabled: true,
447
+ globalConcurrency: 60,
448
+ perOwnerConcurrency: { 'mcp-server:ops': 50 },
449
+ },
450
+ })
451
+ ```
452
+
453
+ Known limitations:
454
+
455
+ - A recovered task runs without the original request. Store anything the executor needs, such as the principal in `resourceId` or other JSON in `metadata`, on the task itself.
456
+ - A `pending` task that isn't pinned holds no lease. On startup, another process can pick it up and dispatch it. If its executor only existed in the original process, the task fails with `No executor registered`. Static executors registered in every process avoid this. Use `pinToWorker` when the original process already started the work.
457
+ - The end-of-step wait in the agent loop only waits for `running` tasks, not `pending` ones. [#28228](https://github.com/mastra-ai/mastra/pull/28228) tracks the fix.
458
+
459
+ ### Pin a task to the current worker
460
+
461
+ Sometimes work for a task is already running in this process before you enqueue it. For example, an MCP server may start a tool call inside the request and hand it to a background task only if it runs long. Pass `pinToWorker: true` with a task context so no other process starts the same work:
462
+
463
+ ```typescript
464
+ await mastra.backgroundTaskManager?.enqueue(
465
+ {
466
+ agentId: 'mcp-server:ops',
467
+ toolName: 'mcp-server:ops:deploy',
468
+ toolCallId: taskId,
469
+ runId: taskId,
470
+ args,
471
+ },
472
+ { executor: { execute: adoptRunningDeploy } },
473
+ { pinToWorker: true },
474
+ )
475
+ ```
476
+
477
+ `pinToWorker` means work for this task is already in flight on this worker. The `pending` task records this worker as its owner and holds an execution lease, which the worker renews while the task waits for a free slot. Other processes don't recover or dispatch the task while the lease is live.
478
+
479
+ If the worker dies or shuts down first, that work is lost. Recovery treats the task as a lost attempt, like a running task whose worker died. If `retryCount` is below `maxRetries`, the task uses a retry and runs on another worker, which needs a static executor for it. Otherwise the task fails with `Worker process terminated before task completed`. A task with `maxRetries: 0` never runs on another worker. Other processes check for lapsed pins at startup and then every `leaseDurationMs`, unless `recoverStaleTasksOnStart` is `false`.
480
+
481
+ A lapsed lease only shows that the worker stopped renewing it, not that the work stopped. A worker whose event loop stalls past the lease can still be running the task when another worker retries it. Make pinned work idempotent, or guard its side effects, if it can be retried.
482
+
483
+ `pinToWorker` throws without a task context. Tasks that aren't pinned, including all agent tasks, hold no lease while `pending`.
484
+
397
485
  ## Related
398
486
 
399
487
  - [`Agent.stream()` reference](https://mastra.ai/reference/streaming/agents/stream)
@@ -87,6 +87,8 @@ Pass `goal.scorer` to replace the pipeline with your own [scorer](https://mastra
87
87
  Configure the default scorer with `judge`, `maxRuns`, and `prompt`:
88
88
 
89
89
  ```typescript
90
+ import { Agent } from '@mastra/core/agent'
91
+
90
92
  const worker = new Agent({
91
93
  id: 'worker',
92
94
  name: 'worker',
@@ -12,13 +12,13 @@ Memory processors are [processors](https://mastra.ai/docs/agents/processors) tha
12
12
 
13
13
  ## Built-in memory processors
14
14
 
15
- Mastra automatically adds these processors when memory is enabled:
15
+ Mastra automatically adds these processors when memory is enabled. `MemoryInputFilter` is added only when a memory store is available and stored history will be loaded:
16
16
 
17
17
  ### `MemoryInputFilter`
18
18
 
19
- Trims client-echoed history before memory loaders run. For an existing thread, it keeps only the current user turn or new tool results. For an empty thread, it keeps the full initial input and removes provider item metadata from assistant parts that could refer to items that don't exist in storage.
19
+ Trims client-echoed history before memory loaders run. For an existing thread, it keeps only the current user turn or new tool results. For an empty thread, it keeps the full initial input and removes provider item metadata from assistant parts that could refer to items that don't exist in storage. When `retainFullInput: true` is set, it skips both the trim and the metadata strip and processes the input exactly as supplied, while stored history still loads.
20
20
 
21
- This processor runs first so `MessageHistory`, `SemanticRecall`, and Observational Memory receive only the new input they need.
21
+ By default, this processor runs first so `MessageHistory`, `SemanticRecall`, and Observational Memory receive only the new input they need.
22
22
 
23
23
  ### `MessageHistory`
24
24
 
@@ -320,6 +320,52 @@ const agent = new Agent({
320
320
 
321
321
  Both scenarios are safe - guardrails prevent inappropriate content from being persisted to memory
322
322
 
323
+ ## Aborted runs and saved messages
324
+
325
+ Cancelling a run and blocking it with a processor `abort()` both stop generation, but they save different things:
326
+
327
+ | What stops the run | Memory processors | What's persisted |
328
+ | ----------------------------- | ----------------- | ------------------------------------------------------------ |
329
+ | `abortSignal` from the caller | Still run | The user message and the assistant text the user already saw |
330
+ | `abort()` inside a processor | Skipped | Nothing; the tripwire blocks the save |
331
+
332
+ A caller cancellation goes through output processors like any other run, so the built-in `MessageHistory` processor saves the thread. The partial answer is stored as an ordinary assistant message with no error part, which means the next turn starts from what the user actually read.
333
+
334
+ ```typescript
335
+ import { Agent } from '@mastra/core/agent'
336
+ import { Memory } from '@mastra/memory'
337
+
338
+ const memory = new Memory({ options: { lastMessages: 20 } })
339
+ const agent = new Agent({
340
+ id: 'writer',
341
+ name: 'writer',
342
+ instructions: 'You write step-by-step migration guides.',
343
+ model: 'openai/gpt-6.1-sol',
344
+ memory,
345
+ })
346
+
347
+ const controller = new AbortController()
348
+ const stream = await agent.stream('Write the migration guide.', {
349
+ memory: { thread: 'thread-1', resource: 'user-1' },
350
+ abortSignal: controller.signal,
351
+ onAbort: ({ steps, text }) => {
352
+ console.log(`Aborted after ${steps.length} steps with ${text?.length ?? 0} characters streamed`)
353
+ },
354
+ })
355
+
356
+ let streamed = ''
357
+ for await (const chunk of stream.fullStream) {
358
+ if (chunk.type !== 'text-delta') continue
359
+ streamed += chunk.payload.text
360
+ if (streamed.length > 200) controller.abort()
361
+ }
362
+
363
+ // The partial answer is already in the thread
364
+ const { messages } = await memory.recall({ threadId: 'thread-1', resourceId: 'user-1' })
365
+ ```
366
+
367
+ `onAbort` receives the steps that completed before the cancellation and the assistant text streamed for the in-flight step. For the abort lifecycle itself, including durable runs aborted by `runId`, see the [`stream()` reference](https://mastra.ai/reference/streaming/agents/stream).
368
+
323
369
  ## Handling large attachments
324
370
 
325
371
  Some storage providers enforce record size limits that base64-encoded file attachments can exceed:
@@ -138,6 +138,9 @@ If you assemble the request input yourself and need it processed exactly as sent
138
138
  Message count is a poor proxy for context size: a tool result can be a few tokens or thousands. Use `messageHistory` to keep recent history within a token budget instead:
139
139
 
140
140
  ```typescript
141
+ import { Agent } from '@mastra/core/agent'
142
+ import { Memory } from '@mastra/memory'
143
+
141
144
  export const agent = new Agent({
142
145
  id: 'test-agent',
143
146
  memory: new Memory({
@@ -10,7 +10,33 @@ Observational Memory (OM) is Mastra's memory system for long-context agentic mem
10
10
 
11
11
  ## Quickstart
12
12
 
13
- Ensure you have `@mastra/memory` installed in your project. Set `observationalMemory: true` in your Memory config to enable Observational Memory.
13
+ Install `@mastra/memory` and a [storage adapter](https://mastra.ai/docs/storage). The examples below use `@mastra/libsql`, which stores data locally in a `memory.db` file.
14
+
15
+ **npm**:
16
+
17
+ ```bash
18
+ npm install @mastra/memory@latest @mastra/libsql@latest
19
+ ```
20
+
21
+ **pnpm**:
22
+
23
+ ```bash
24
+ pnpm add @mastra/memory@latest @mastra/libsql@latest
25
+ ```
26
+
27
+ **Yarn**:
28
+
29
+ ```bash
30
+ yarn add @mastra/memory@latest @mastra/libsql@latest
31
+ ```
32
+
33
+ **Bun**:
34
+
35
+ ```bash
36
+ bun add @mastra/memory@latest @mastra/libsql@latest
37
+ ```
38
+
39
+ Then set `observationalMemory: true` in your Memory config to enable Observational Memory.
14
40
 
15
41
  ```typescript
16
42
  import { Memory } from '@mastra/memory'
@@ -149,6 +175,8 @@ OM can activate buffered observations before the token threshold is reached. Thi
149
175
  Top-level early activation settings apply to observations by default:
150
176
 
151
177
  ```typescript
178
+ import { Memory } from '@mastra/memory'
179
+
152
180
  const memory = new Memory({
153
181
  options: {
154
182
  observationalMemory: {
@@ -163,6 +191,8 @@ const memory = new Memory({
163
191
  Use nested `observation` and `reflection` settings for per-phase control. Reflection early activation is opt-in, so top-level settings affect only observations.
164
192
 
165
193
  ```typescript
194
+ import { Memory } from '@mastra/memory'
195
+
166
196
  const memory = new Memory({
167
197
  options: {
168
198
  observationalMemory: {
@@ -187,6 +217,8 @@ In this example, the top-level idle setting is disabled for observations, while
187
217
  Set `observation.bufferOnIdle` to `true` to run background observation buffering when an agent turn ends and the agent becomes idle. This is useful for apps that want short turns to be observed without waiting for the next turn or the `messageTokens` threshold.
188
218
 
189
219
  ```typescript
220
+ import { Memory } from '@mastra/memory'
221
+
190
222
  const memory = new Memory({
191
223
  options: {
192
224
  observationalMemory: {
@@ -209,6 +241,8 @@ Observer and Reflector model calls are retried on transient provider errors. By
209
241
  - `failurePolicy`: what happens once retries are exhausted, either `'abort'` (default) or `'continue'`.
210
242
 
211
243
  ```typescript
244
+ import { Memory } from '@mastra/memory'
245
+
212
246
  const memory = new Memory({
213
247
  options: {
214
248
  observationalMemory: {
@@ -391,6 +425,8 @@ This setting adds `WorkingMemoryExtractor`, defaults `workingMemory.agentManaged
391
425
  Use `onExtracted` to normalize or react to custom extracted values before they're persisted:
392
426
 
393
427
  ```typescript
428
+ import { z } from 'zod'
429
+
394
430
  new Extractor({
395
431
  name: 'Project status',
396
432
  instructions: 'Extract the current project status.',