@mastra/memory 1.23.0-alpha.1 → 1.23.0-alpha.3

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 (33) hide show
  1. package/CHANGELOG.md +19 -0
  2. package/dist/{chunk-HF2E2T6Z.js → chunk-FNWCP2TI.js} +48 -6
  3. package/dist/chunk-FNWCP2TI.js.map +1 -0
  4. package/dist/{chunk-5HE6DK63.cjs → chunk-WZKTIB4U.cjs} +48 -6
  5. package/dist/chunk-WZKTIB4U.cjs.map +1 -0
  6. package/dist/docs/SKILL.md +2 -1
  7. package/dist/docs/assets/SOURCE_MAP.json +57 -57
  8. package/dist/docs/references/docs-agents-supervisor-agents.md +3 -4
  9. package/dist/docs/references/docs-evals-evals-with-memory.md +1 -3
  10. package/dist/docs/references/docs-long-running-agents-background-tasks.md +1 -1
  11. package/dist/docs/references/docs-long-running-agents-goals.md +1 -3
  12. package/dist/docs/references/docs-memory-observational-memory.md +2 -1
  13. package/dist/docs/references/docs-memory-overview.md +6 -4
  14. package/dist/docs/references/docs-memory-semantic-recall.md +1 -1
  15. package/dist/docs/references/docs-memory-working-memory.md +3 -3
  16. package/dist/docs/references/reference-file-based-agents-memory.md +58 -0
  17. package/dist/docs/references/reference-memory-memory-class.md +1 -1
  18. package/dist/index.cjs +15 -15
  19. package/dist/index.js +1 -1
  20. package/dist/{observational-memory-XKEEBG2S.js → observational-memory-GAYCVM5R.js} +3 -3
  21. package/dist/{observational-memory-XKEEBG2S.js.map → observational-memory-GAYCVM5R.js.map} +1 -1
  22. package/dist/{observational-memory-LEIZSPQ5.cjs → observational-memory-HZP3D5IO.cjs} +29 -29
  23. package/dist/{observational-memory-LEIZSPQ5.cjs.map → observational-memory-HZP3D5IO.cjs.map} +1 -1
  24. package/dist/processors/index.cjs +27 -27
  25. package/dist/processors/index.js +1 -1
  26. package/dist/processors/observational-memory/observation-turn/step.d.ts +13 -0
  27. package/dist/processors/observational-memory/observation-turn/step.d.ts.map +1 -1
  28. package/dist/processors/observational-memory/observation-turn/turn.d.ts +25 -0
  29. package/dist/processors/observational-memory/observation-turn/turn.d.ts.map +1 -1
  30. package/dist/processors/observational-memory/processor.d.ts.map +1 -1
  31. package/package.json +4 -4
  32. package/dist/chunk-5HE6DK63.cjs.map +0 -1
  33. package/dist/chunk-HF2E2T6Z.js.map +0 -1
package/dist/docs/SKILL.md CHANGED
@@ -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: "1.23.0-alpha.1"
6
+ version: "1.23.0-alpha.3"
7
7
  ---
8
8
 
9
9
  ## When to use
@@ -35,6 +35,7 @@ Read the individual reference documents for detailed explanations and code examp
35
35
 
36
36
  - [Reference: Mastra.getMemory()](references/reference-core-getMemory.md) - Documentation for the `Mastra.getMemory()` method in Mastra, which retrieves a registered memory instance by its registry key.
37
37
  - [Reference: Mastra.listMemory()](references/reference-core-listMemory.md) - Documentation for the `Mastra.listMemory()` method in Mastra, which returns all registered memory instances.
38
+ - [Memory](references/reference-file-based-agents-memory.md) - Give a file-based agent persistent memory with a memory.ts module.
38
39
  - [Reference: Cloned thread utilities](references/reference-memory-clone-utilities.md) - Documentation for utility methods to work with cloned threads in Mastra Memory.
39
40
  - [Reference: Memory.cloneThread()](references/reference-memory-cloneThread.md) - Documentation for the `Memory.cloneThread()` method in Mastra, which creates a copy of a conversation thread with all its messages.
40
41
  - [Reference: Memory.createThread()](references/reference-memory-createThread.md) - Documentation for the `Memory.createThread()` method in Mastra, which creates a new conversation thread in the memory system.
package/dist/docs/assets/SOURCE_MAP.json CHANGED
@@ -1,133 +1,133 @@
1
1
  {
2
- "version": "1.23.0-alpha.1",
2
+ "version": "1.23.0-alpha.3",
3
3
  "package": "@mastra/memory",
4
4
  "exports": {
5
5
  "Extractor": {
6
6
  "types": "dist/processors/index.d.ts",
7
- "implementation": "dist/chunk-HF2E2T6Z.js",
7
+ "implementation": "dist/chunk-FNWCP2TI.js",
8
8
  "line": 316
9
9
  },
10
10
  "ModelByInputTokens": {
11
11
  "types": "dist/processors/index.d.ts",
12
- "implementation": "dist/chunk-HF2E2T6Z.js",
12
+ "implementation": "dist/chunk-FNWCP2TI.js",
13
13
  "line": 1354
14
14
  },
15
15
  "OBSERVER_SYSTEM_PROMPT": {
16
16
  "types": "dist/processors/index.d.ts",
17
- "implementation": "dist/chunk-HF2E2T6Z.js"
17
+ "implementation": "dist/chunk-FNWCP2TI.js"
18
18
  },
19
19
  "ObservationalMemory": {
20
20
  "types": "dist/processors/index.d.ts",
21
- "implementation": "dist/chunk-HF2E2T6Z.js",
22
- "line": 27685
21
+ "implementation": "dist/chunk-FNWCP2TI.js",
22
+ "line": 27724
23
23
  },
24
24
  "ObservationalMemoryProcessor": {
25
25
  "types": "dist/processors/index.d.ts",
26
- "implementation": "dist/chunk-HF2E2T6Z.js",
27
- "line": 30316
26
+ "implementation": "dist/chunk-FNWCP2TI.js",
27
+ "line": 30358
28
28
  },
29
29
  "TokenCounter": {
30
30
  "types": "dist/processors/index.d.ts",
31
- "implementation": "dist/chunk-HF2E2T6Z.js",
32
- "line": 21467
31
+ "implementation": "dist/chunk-FNWCP2TI.js",
32
+ "line": 21506
33
33
  },
34
34
  "WorkingMemoryExtractor": {
35
35
  "types": "dist/processors/index.d.ts",
36
- "implementation": "dist/chunk-HF2E2T6Z.js",
37
- "line": 22134
36
+ "implementation": "dist/chunk-FNWCP2TI.js",
37
+ "line": 22173
38
38
  },
39
39
  "buildObserverPrompt": {
40
40
  "types": "dist/processors/index.d.ts",
41
- "implementation": "dist/chunk-HF2E2T6Z.js",
42
- "line": 4465
41
+ "implementation": "dist/chunk-FNWCP2TI.js",
42
+ "line": 4504
43
43
  },
44
44
  "buildObserverSystemPrompt": {
45
45
  "types": "dist/processors/index.d.ts",
46
- "implementation": "dist/chunk-HF2E2T6Z.js",
47
- "line": 3732
46
+ "implementation": "dist/chunk-FNWCP2TI.js",
47
+ "line": 3771
48
48
  },
49
49
  "combineObservationGroupRanges": {
50
50
  "types": "dist/processors/index.d.ts",
51
- "implementation": "dist/chunk-HF2E2T6Z.js",
51
+ "implementation": "dist/chunk-FNWCP2TI.js",
52
52
  "line": 1446
53
53
  },
54
54
  "deriveObservationGroupProvenance": {
55
55
  "types": "dist/processors/index.d.ts",
56
- "implementation": "dist/chunk-HF2E2T6Z.js",
56
+ "implementation": "dist/chunk-FNWCP2TI.js",
57
57
  "line": 1480
58
58
  },
59
59
  "extractCurrentTask": {
60
60
  "types": "dist/processors/index.d.ts",
61
- "implementation": "dist/chunk-HF2E2T6Z.js",
62
- "line": 4588
61
+ "implementation": "dist/chunk-FNWCP2TI.js",
62
+ "line": 4627
63
63
  },
64
64
  "formatMessagesForObserver": {
65
65
  "types": "dist/processors/index.d.ts",
66
- "implementation": "dist/chunk-HF2E2T6Z.js",
67
- "line": 4187
66
+ "implementation": "dist/chunk-FNWCP2TI.js",
67
+ "line": 4226
68
68
  },
69
69
  "getObservationsAsOf": {
70
70
  "types": "dist/processors/index.d.ts",
71
- "implementation": "dist/chunk-HF2E2T6Z.js",
72
- "line": 30538
71
+ "implementation": "dist/chunk-FNWCP2TI.js",
72
+ "line": 30580
73
73
  },
74
74
  "hasCurrentTaskSection": {
75
75
  "types": "dist/processors/index.d.ts",
76
- "implementation": "dist/chunk-HF2E2T6Z.js",
77
- "line": 4576
76
+ "implementation": "dist/chunk-FNWCP2TI.js",
77
+ "line": 4615
78
78
  },
79
79
  "injectAnchorIds": {
80
80
  "types": "dist/processors/index.d.ts",
81
- "implementation": "dist/chunk-HF2E2T6Z.js",
82
- "line": 3287
81
+ "implementation": "dist/chunk-FNWCP2TI.js",
82
+ "line": 3326
83
83
  },
84
84
  "optimizeObservationsForContext": {
85
85
  "types": "dist/processors/index.d.ts",
86
- "implementation": "dist/chunk-HF2E2T6Z.js",
87
- "line": 4599
86
+ "implementation": "dist/chunk-FNWCP2TI.js",
87
+ "line": 4638
88
88
  },
89
89
  "parseAnchorId": {
90
90
  "types": "dist/processors/index.d.ts",
91
- "implementation": "dist/chunk-HF2E2T6Z.js",
92
- "line": 3260
91
+ "implementation": "dist/chunk-FNWCP2TI.js",
92
+ "line": 3299
93
93
  },
94
94
  "parseObservationGroups": {
95
95
  "types": "dist/processors/index.d.ts",
96
- "implementation": "dist/chunk-HF2E2T6Z.js",
96
+ "implementation": "dist/chunk-FNWCP2TI.js",
97
97
  "line": 1415
98
98
  },
99
99
  "parseObserverOutput": {
100
100
  "types": "dist/processors/index.d.ts",
101
- "implementation": "dist/chunk-HF2E2T6Z.js",
102
- "line": 4479
101
+ "implementation": "dist/chunk-FNWCP2TI.js",
102
+ "line": 4518
103
103
  },
104
104
  "reconcileObservationGroupsFromReflection": {
105
105
  "types": "dist/processors/index.d.ts",
106
- "implementation": "dist/chunk-HF2E2T6Z.js",
106
+ "implementation": "dist/chunk-FNWCP2TI.js",
107
107
  "line": 1504
108
108
  },
109
109
  "renderObservationGroupsForReflection": {
110
110
  "types": "dist/processors/index.d.ts",
111
- "implementation": "dist/chunk-HF2E2T6Z.js",
111
+ "implementation": "dist/chunk-FNWCP2TI.js",
112
112
  "line": 1460
113
113
  },
114
114
  "stripEphemeralAnchorIds": {
115
115
  "types": "dist/processors/index.d.ts",
116
- "implementation": "dist/chunk-HF2E2T6Z.js",
117
- "line": 3317
116
+ "implementation": "dist/chunk-FNWCP2TI.js",
117
+ "line": 3356
118
118
  },
119
119
  "stripObservationGroups": {
120
120
  "types": "dist/processors/index.d.ts",
121
- "implementation": "dist/chunk-HF2E2T6Z.js",
121
+ "implementation": "dist/chunk-FNWCP2TI.js",
122
122
  "line": 1437
123
123
  },
124
124
  "summarizeConversation": {
125
125
  "types": "dist/processors/index.d.ts",
126
- "implementation": "dist/chunk-HF2E2T6Z.js"
126
+ "implementation": "dist/chunk-FNWCP2TI.js"
127
127
  },
128
128
  "wrapInObservationGroup": {
129
129
  "types": "dist/processors/index.d.ts",
130
- "implementation": "dist/chunk-HF2E2T6Z.js",
130
+ "implementation": "dist/chunk-FNWCP2TI.js",
131
131
  "line": 1408
132
132
  },
133
133
  "OBSERVATIONAL_MEMORY_DEFAULTS": {
@@ -148,44 +148,44 @@
148
148
  },
149
149
  "Memory": {
150
150
  "types": "dist/index.d.ts",
151
- "implementation": "dist/chunk-HF2E2T6Z.js",
152
- "line": 23559
151
+ "implementation": "dist/chunk-FNWCP2TI.js",
152
+ "line": 23598
153
153
  },
154
154
  "MessageHistory": {
155
155
  "types": "dist/index.d.ts",
156
- "implementation": "dist/chunk-HF2E2T6Z.js"
156
+ "implementation": "dist/chunk-FNWCP2TI.js"
157
157
  },
158
158
  "SUMMARIZE_THREAD_DEFAULTS": {
159
159
  "types": "dist/index.d.ts",
160
- "implementation": "dist/chunk-HF2E2T6Z.js"
160
+ "implementation": "dist/chunk-FNWCP2TI.js"
161
161
  },
162
162
  "SemanticRecall": {
163
163
  "types": "dist/index.d.ts",
164
- "implementation": "dist/chunk-HF2E2T6Z.js"
164
+ "implementation": "dist/chunk-FNWCP2TI.js"
165
165
  },
166
166
  "WorkingMemory": {
167
167
  "types": "dist/index.d.ts",
168
- "implementation": "dist/chunk-HF2E2T6Z.js"
168
+ "implementation": "dist/chunk-FNWCP2TI.js"
169
169
  },
170
170
  "deepMergeWorkingMemory": {
171
171
  "types": "dist/index.d.ts",
172
- "implementation": "dist/chunk-HF2E2T6Z.js",
173
- "line": 23198
172
+ "implementation": "dist/chunk-FNWCP2TI.js",
173
+ "line": 23237
174
174
  },
175
175
  "extractWorkingMemoryContent": {
176
176
  "types": "dist/index.d.ts",
177
- "implementation": "dist/chunk-HF2E2T6Z.js",
178
- "line": 23514
177
+ "implementation": "dist/chunk-FNWCP2TI.js",
178
+ "line": 23553
179
179
  },
180
180
  "extractWorkingMemoryTags": {
181
181
  "types": "dist/index.d.ts",
182
- "implementation": "dist/chunk-HF2E2T6Z.js",
183
- "line": 23482
182
+ "implementation": "dist/chunk-FNWCP2TI.js",
183
+ "line": 23521
184
184
  },
185
185
  "removeWorkingMemoryTags": {
186
186
  "types": "dist/index.d.ts",
187
- "implementation": "dist/chunk-HF2E2T6Z.js",
188
- "line": 23495
187
+ "implementation": "dist/chunk-FNWCP2TI.js",
188
+ "line": 23534
189
189
  },
190
190
  "WORKING_MEMORY_STATE_ID": {
191
191
  "types": "dist/index.d.ts",
@@ -205,7 +205,7 @@
205
205
  "processors": {
206
206
  "index": "dist/processors/index.js",
207
207
  "chunks": [
208
- "chunk-HF2E2T6Z.js",
208
+ "chunk-FNWCP2TI.js",
209
209
  "chunk-LSJJAJAF.js"
210
210
  ]
211
211
  }
package/dist/docs/references/docs-agents-supervisor-agents.md CHANGED
@@ -226,9 +226,7 @@ How it works:
226
226
  2. **Scoped memory saves**: Only the delegation prompt and the subagent's response are saved to the subagent's memory
227
227
  3. **Fresh thread per invocation**: Each delegation uses a unique thread ID, ensuring clean separation
228
228
 
229
- This ensures subagents have the context they need without cluttering their memory with the entire supervisor conversation.
230
-
231
- > **Note:** Visit [memory in multi-agent systems](https://mastra.ai/docs/memory/overview) for more details.
229
+ This ensures subagents have the context they need without cluttering their memory with the entire supervisor conversation. Visit [memory in multi-agent systems](https://mastra.ai/docs/memory/overview) for more details.
232
230
 
233
231
  ## Tool approval propagation
234
232
 
@@ -428,4 +426,5 @@ Version overrides propagate automatically through delegation. See [Subagent vers
428
426
  - [Agent.generate() reference](https://mastra.ai/reference/agents/generate)
429
427
  - [Agent approval](https://mastra.ai/docs/agents/agent-approval)
430
428
  - [Memory in multi-agent systems](https://mastra.ai/docs/memory/overview)
431
- - [Concept: Multi-agent systems](https://mastra.ai/guides/concepts/multi-agent-systems)
429
+ - [Concept: Multi-agent systems](https://mastra.ai/guides/concepts/multi-agent-systems)
430
+ - 📹 [Mastra supervisor agents workshop](https://www.youtube.com/watch?v=FNb2fL9WhQg\&t=1872s)
package/dist/docs/references/docs-evals-evals-with-memory.md CHANGED
@@ -136,9 +136,7 @@ const summary = await dataset.startExperiment({
136
136
  })
137
137
  ```
138
138
 
139
- The inline `task` receives the item's `metadata`, so each row can drive its own thread without changing the agent or any scorer.
140
-
141
- > **Note:** Visit [runEvals reference](https://mastra.ai/reference/evals/run-evals) and [Dataset reference](https://mastra.ai/reference/datasets/dataset) for full configuration.
139
+ The inline `task` receives the item's `metadata`, so each row can drive its own thread without changing the agent or any scorer. Visit [runEvals reference](https://mastra.ai/reference/evals/run-evals) and [Dataset reference](https://mastra.ai/reference/datasets/dataset) for full configuration.
142
140
 
143
141
  ## Related
144
142
 
package/dist/docs/references/docs-long-running-agents-background-tasks.md CHANGED
@@ -168,7 +168,7 @@ const stream = await agent.stream('Research solana for me', {
168
168
  })
169
169
  ```
170
170
 
171
- > **Note:** Visit [`Agent.stream()`](https://mastra.ai/reference/streaming/agents/stream) for the full API.
171
+ Visit [`Agent.stream()`](https://mastra.ai/reference/streaming/agents/stream) for the full API.
172
172
 
173
173
  ### Aggregate properties
174
174
 
package/dist/docs/references/docs-long-running-agents-goals.md CHANGED
@@ -103,9 +103,7 @@ await worker.updateObjectiveOptions({ threadId, maxRuns: 100 })
103
103
  await worker.clearObjective({ threadId })
104
104
  ```
105
105
 
106
- Per-objective values written by `setObjective` / `updateObjectiveOptions` take precedence over the agent's `goal` config, and that precedence is remembered in thread state.
107
-
108
- > **Note:** See the [`GoalEvaluationPayload` in the ChunkType reference](https://mastra.ai/reference/streaming/ChunkType) for the full goal chunk shape.
106
+ Per-objective values written by `setObjective` / `updateObjectiveOptions` take precedence over the agent's `goal` config, and that precedence is remembered in thread state. See the [`GoalEvaluationPayload` in the ChunkType reference](https://mastra.ai/reference/streaming/ChunkType) for the full goal chunk shape.
109
107
 
110
108
  ## Related
111
109
 
package/dist/docs/references/docs-memory-observational-memory.md CHANGED
@@ -714,4 +714,5 @@ In practical terms, OM replaces both working memory and message history, and has
714
714
  - [Memory Overview](https://mastra.ai/docs/memory/overview)
715
715
  - [Message History](https://mastra.ai/docs/memory/message-history)
716
716
  - [Memory Processors](https://mastra.ai/docs/memory/memory-processors)
717
- - [Mastra Code](https://code.mastra.ai/): A coding agent using Observational Memory
717
+ - [Mastra Code](https://code.mastra.ai/): A coding agent using Observational Memory
718
+ - 📹 [Mastra processors and Observational Memory workshop](https://www.youtube.com/watch?v=4Vpp7xQYvl0)
package/dist/docs/references/docs-memory-overview.md CHANGED
@@ -15,6 +15,8 @@ If the combined memory exceeds the model's context limit, [memory processors](ht
15
15
 
16
16
  Memory results will be stored in one or more of your configured [storage providers](https://mastra.ai/docs/storage/overview).
17
17
 
18
+ > **📹 Watch:** Watch [Mastra memory concepts](https://www.youtube.com/watch?v=18iIHQtIPmc) for a conceptual overview of the memory layers agents can use.
19
+
18
20
  ## When to use memory
19
21
 
20
22
  Use memory when your agent needs to maintain multi-turn conversations that reference prior exchanges, recall user preferences or facts from earlier in a session, or build context over time within a conversation thread. Skip memory for single-turn requests where each interaction is independent.
@@ -75,7 +77,7 @@ Use memory when your agent needs to maintain multi-turn conversations that refer
75
77
  bun add @mastra/libsql@latest
76
78
  ```
77
79
 
78
- > **Note:** For more details on available providers and how storage works in Mastra, visit the [storage](https://mastra.ai/docs/storage/overview) documentation.
80
+ For more details on available providers and how storage works in Mastra, visit the [storage](https://mastra.ai/docs/storage/overview) documentation.
79
81
 
80
82
  3. Add the storage provider to your main Mastra instance to enable memory across all configured agents.
81
83
 
@@ -108,7 +110,7 @@ Use memory when your agent needs to maintain multi-turn conversations that refer
108
110
  })
109
111
  ```
110
112
 
111
- > **Note:** Visit [Memory Class](https://mastra.ai/reference/memory/memory-class) for a full list of configuration options.
113
+ Visit [Memory Class](https://mastra.ai/reference/memory/memory-class) for a full list of configuration options.
112
114
 
113
115
  5. Call your agent, for example in [Studio](https://mastra.ai/docs/studio/overview). Inside Studio, start a new chat with your agent and take a look at the right sidebar. It'll now display various memory-related information.
114
116
 
@@ -164,7 +166,7 @@ export const memoryAgent = new Agent({
164
166
  })
165
167
  ```
166
168
 
167
- > **Note:** See [Observational Memory](https://mastra.ai/docs/memory/observational-memory) for details on how observations and reflections work, and [the reference](https://mastra.ai/reference/memory/observational-memory) for all configuration options.
169
+ See [Observational Memory](https://mastra.ai/docs/memory/observational-memory) for details on how observations and reflections work, and [the reference](https://mastra.ai/reference/memory/observational-memory) for all configuration options.
168
170
 
169
171
  ## Memory in multi-agent systems
170
172
 
@@ -236,7 +238,7 @@ export const memoryAgent = new Agent({
236
238
  })
237
239
  ```
238
240
 
239
- > **Note:** Visit [Request Context](https://mastra.ai/docs/server/request-context) for more information.
241
+ Visit [Request Context](https://mastra.ai/docs/server/request-context) for more information.
240
242
 
241
243
  ## Related
242
244
 
package/dist/docs/references/docs-memory-semantic-recall.md CHANGED
@@ -4,7 +4,7 @@
4
4
 
5
5
  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.
6
6
 
7
- > **Watch 📹:** What semantic recall is, how it works, and how to configure it in Mastra → [YouTube (5 minutes)](https://youtu.be/UVZtK8cK8xQ)
7
+ > **📹 Watch:** Watch [Mastra semantic recall](https://www.youtube.com/watch?v=UVZtK8cK8xQ\&pp=ygUVbWFzdHJhIHdvcmtpbmcgbWVtb3J5) to see how agents retrieve relevant messages from past conversations.
8
8
 
9
9
  ## How semantic recall works
10
10
 
package/dist/docs/references/docs-memory-working-memory.md CHANGED
@@ -10,6 +10,8 @@ This is useful for maintaining ongoing state that's always relevant and should a
10
10
 
11
11
  If you use [Observational Memory](https://mastra.ai/docs/memory/observational-memory), `observationalMemory.observation.manageWorkingMemory` lets OM update working memory for the agent.
12
12
 
13
+ > **📹 Watch:** Watch [Mastra working memory](https://www.youtube.com/watch?v=UMy_JHLf1n8\&pp=ygUVbWFzdHJhIHdvcmtpbmcgbWVtb3J5) to see how agents keep persistent user context available across interactions.
14
+
13
15
  Working memory can persist at two different scopes:
14
16
 
15
17
  - **Resource-scoped** (default): Memory persists across all conversation threads for the same user
@@ -43,9 +45,7 @@ const agent = new Agent({
43
45
 
44
46
  ## How it works
45
47
 
46
- Working memory is a block of Markdown text that the agent is able to update over time to store continuously relevant information:
47
-
48
- [YouTube video player](https://www.youtube-nocookie.com/embed/UMy_JHLf1n8)
48
+ Working memory is a block of Markdown text that the agent is able to update over time to store continuously relevant information.
49
49
 
50
50
  ## Memory persistence scopes
51
51
 
package/dist/docs/references/reference-file-based-agents-memory.md ADDED
@@ -0,0 +1,58 @@
1
+ > Discover all available pages from the documentation index: https://mastra.ai/llms.txt
2
+
3
+ # Memory
4
+
5
+ A file-based agent gets [memory](https://mastra.ai/docs/memory/overview) from a `memory.ts` file that default-exports a [`Memory`](https://mastra.ai/reference/memory/memory-class) instance. Use this page for the file-based convention; use the memory docs for message history, semantic recall, storage, and processors.
6
+
7
+ Without `memory.ts` or `config.memory`, the agent has no memory by default. Each `generate()` or `stream()` call starts without remembered conversation state unless you pass the prior context yourself.
8
+
9
+ ## Quickstart
10
+
11
+ Create `memory.ts` next to the agent's `config.ts`:
12
+
13
+ ```typescript
14
+ import { Memory } from '@mastra/memory'
15
+
16
+ export default new Memory()
17
+ ```
18
+
19
+ The exported instance becomes the agent's `memory`. If your app configures a storage provider on the main Mastra instance, memory data is stored there. See [storage](https://mastra.ai/docs/storage/overview) for more information.
20
+
21
+ Use the same `resource` and `thread` values when calling the agent to continue a conversation:
22
+
23
+ ```typescript
24
+ const response = await weatherAgent.generate('Remember that I prefer Celsius.', {
25
+ memory: {
26
+ resource: 'user-123',
27
+ thread: 'weather-chat',
28
+ },
29
+ })
30
+ ```
31
+
32
+ ## Configure memory
33
+
34
+ Pass options to `new Memory()` when the default behavior isn't enough.
35
+
36
+ ```typescript
37
+ import { Memory } from '@mastra/memory'
38
+
39
+ export default new Memory({
40
+ options: {
41
+ lastMessages: 20,
42
+ workingMemory: {
43
+ enabled: true,
44
+ scope: 'resource',
45
+ },
46
+ },
47
+ })
48
+ ```
49
+
50
+ Visit the [`Memory` reference](https://mastra.ai/reference/memory/memory-class) for constructor options. Use these pages for related memory features:
51
+
52
+ - [Storage](https://mastra.ai/docs/storage/overview): configure persistence for memory data.
53
+ - [Semantic recall](https://mastra.ai/docs/memory/semantic-recall): retrieve relevant past messages by semantic meaning.
54
+ - [Memory processors](https://mastra.ai/docs/memory/memory-processors): filter, trim, or transform messages before memory adds them to model context.
55
+
56
+ ## Precedence with config
57
+
58
+ `config.memory` wins over `memory.ts`. If neither is present, the assembled file-based agent has no memory. See [`config.ts` precedence](https://mastra.ai/reference/file-based-agents/config) for the full merge table.
package/dist/docs/references/reference-memory-memory-class.md CHANGED
@@ -37,7 +37,7 @@ export const agent = new Agent({
37
37
 
38
38
  **options** (`MemoryConfig`): Memory configuration options.
39
39
 
40
- **options.lastMessages** (`number | false`): Number of most recent messages to include in context. Set to false to disable loading conversation history into context. Use Number.MAX\_SAFE\_INTEGER to retrieve all messages with no limit. To prevent saving new messages, use the readOnly option instead.
40
+ **options.lastMessages** (`number | false`): Number of most recent messages to include in context. Set to false to disable the message history feature entirely (messages are not loaded into context or saved). Use Number.MAX\_SAFE\_INTEGER to retrieve all messages with no limit. To load messages without saving new ones, use the readOnly option.
41
41
 
42
42
  **options.readOnly** (`boolean`): When true, prevents memory from saving new messages and provides working memory as read-only context (without the updateWorkingMemory tool). Useful for read-only operations like previews, internal routing agents, or sub agents that should reference but not modify memory.
43
43
 
package/dist/index.cjs CHANGED
@@ -1,65 +1,65 @@
1
1
  'use strict';
2
2
 
3
- var chunk5HE6DK63_cjs = require('./chunk-5HE6DK63.cjs');
3
+ var chunkWZKTIB4U_cjs = require('./chunk-WZKTIB4U.cjs');
4
4
  var chunk43FJOLKM_cjs = require('./chunk-43FJOLKM.cjs');
5
5
 
6
6
 
7
7
 
8
8
  Object.defineProperty(exports, "Extractor", {
9
9
  enumerable: true,
10
- get: function () { return chunk5HE6DK63_cjs.Extractor; }
10
+ get: function () { return chunkWZKTIB4U_cjs.Extractor; }
11
11
  });
12
12
  Object.defineProperty(exports, "Memory", {
13
13
  enumerable: true,
14
- get: function () { return chunk5HE6DK63_cjs.Memory; }
14
+ get: function () { return chunkWZKTIB4U_cjs.Memory; }
15
15
  });
16
16
  Object.defineProperty(exports, "MessageHistory", {
17
17
  enumerable: true,
18
- get: function () { return chunk5HE6DK63_cjs.MessageHistory; }
18
+ get: function () { return chunkWZKTIB4U_cjs.MessageHistory; }
19
19
  });
20
20
  Object.defineProperty(exports, "ModelByInputTokens", {
21
21
  enumerable: true,
22
- get: function () { return chunk5HE6DK63_cjs.ModelByInputTokens; }
22
+ get: function () { return chunkWZKTIB4U_cjs.ModelByInputTokens; }
23
23
  });
24
24
  Object.defineProperty(exports, "SUMMARIZE_THREAD_DEFAULTS", {
25
25
  enumerable: true,
26
- get: function () { return chunk5HE6DK63_cjs.SUMMARIZE_THREAD_DEFAULTS; }
26
+ get: function () { return chunkWZKTIB4U_cjs.SUMMARIZE_THREAD_DEFAULTS; }
27
27
  });
28
28
  Object.defineProperty(exports, "SemanticRecall", {
29
29
  enumerable: true,
30
- get: function () { return chunk5HE6DK63_cjs.SemanticRecall; }
30
+ get: function () { return chunkWZKTIB4U_cjs.SemanticRecall; }
31
31
  });
32
32
  Object.defineProperty(exports, "WorkingMemory", {
33
33
  enumerable: true,
34
- get: function () { return chunk5HE6DK63_cjs.WorkingMemory; }
34
+ get: function () { return chunkWZKTIB4U_cjs.WorkingMemory; }
35
35
  });
36
36
  Object.defineProperty(exports, "WorkingMemoryExtractor", {
37
37
  enumerable: true,
38
- get: function () { return chunk5HE6DK63_cjs.WorkingMemoryExtractor; }
38
+ get: function () { return chunkWZKTIB4U_cjs.WorkingMemoryExtractor; }
39
39
  });
40
40
  Object.defineProperty(exports, "deepMergeWorkingMemory", {
41
41
  enumerable: true,
42
- get: function () { return chunk5HE6DK63_cjs.deepMergeWorkingMemory; }
42
+ get: function () { return chunkWZKTIB4U_cjs.deepMergeWorkingMemory; }
43
43
  });
44
44
  Object.defineProperty(exports, "extractWorkingMemoryContent", {
45
45
  enumerable: true,
46
- get: function () { return chunk5HE6DK63_cjs.extractWorkingMemoryContent; }
46
+ get: function () { return chunkWZKTIB4U_cjs.extractWorkingMemoryContent; }
47
47
  });
48
48
  Object.defineProperty(exports, "extractWorkingMemoryTags", {
49
49
  enumerable: true,
50
- get: function () { return chunk5HE6DK63_cjs.extractWorkingMemoryTags; }
50
+ get: function () { return chunkWZKTIB4U_cjs.extractWorkingMemoryTags; }
51
51
  });
52
52
  Object.defineProperty(exports, "getObservationsAsOf", {
53
53
  enumerable: true,
54
- get: function () { return chunk5HE6DK63_cjs.getObservationsAsOf; }
54
+ get: function () { return chunkWZKTIB4U_cjs.getObservationsAsOf; }
55
55
  });
56
56
  Object.defineProperty(exports, "removeWorkingMemoryTags", {
57
57
  enumerable: true,
58
- get: function () { return chunk5HE6DK63_cjs.removeWorkingMemoryTags; }
58
+ get: function () { return chunkWZKTIB4U_cjs.removeWorkingMemoryTags; }
59
59
  });
60
60
  Object.defineProperty(exports, "summarizeConversation", {
61
61
  enumerable: true,
62
- get: function () { return chunk5HE6DK63_cjs.summarizeConversation; }
62
+ get: function () { return chunkWZKTIB4U_cjs.summarizeConversation; }
63
63
  });
64
64
  Object.defineProperty(exports, "WORKING_MEMORY_STATE_ID", {
65
65
  enumerable: true,
package/dist/index.js CHANGED
@@ -1,4 +1,4 @@
1
- export { Extractor, Memory, MessageHistory, ModelByInputTokens, SUMMARIZE_THREAD_DEFAULTS, SemanticRecall, WorkingMemory, WorkingMemoryExtractor, deepMergeWorkingMemory, extractWorkingMemoryContent, extractWorkingMemoryTags, getObservationsAsOf, removeWorkingMemoryTags, summarizeConversation } from './chunk-HF2E2T6Z.js';
1
+ export { Extractor, Memory, MessageHistory, ModelByInputTokens, SUMMARIZE_THREAD_DEFAULTS, SemanticRecall, WorkingMemory, WorkingMemoryExtractor, deepMergeWorkingMemory, extractWorkingMemoryContent, extractWorkingMemoryTags, getObservationsAsOf, removeWorkingMemoryTags, summarizeConversation } from './chunk-FNWCP2TI.js';
2
2
  export { WORKING_MEMORY_STATE_ID, WORKING_MEMORY_STATE_PROCESSOR_ID, WorkingMemoryStateProcessor } from './chunk-WCGXQIEN.js';
3
3
  //# sourceMappingURL=index.js.map
4
4
  //# sourceMappingURL=index.js.map
package/dist/{observational-memory-XKEEBG2S.js → observational-memory-GAYCVM5R.js} RENAMED
@@ -1,4 +1,4 @@
1
- export { Extractor, ModelByInputTokens, OBSERVER_SYSTEM_PROMPT, ObservationalMemory, ObservationalMemoryProcessor, TokenCounter, WorkingMemoryExtractor, buildObserverPrompt, buildObserverSystemPrompt, combineObservationGroupRanges, deriveObservationGroupProvenance, extractCurrentTask, formatMessagesForObserver, getObservationsAsOf, hasCurrentTaskSection, injectAnchorIds, optimizeObservationsForContext, parseAnchorId, parseObservationGroups, parseObserverOutput, reconcileObservationGroupsFromReflection, renderObservationGroupsForReflection, stripEphemeralAnchorIds, stripObservationGroups, summarizeConversation, wrapInObservationGroup } from './chunk-HF2E2T6Z.js';
1
+ export { Extractor, ModelByInputTokens, OBSERVER_SYSTEM_PROMPT, ObservationalMemory, ObservationalMemoryProcessor, TokenCounter, WorkingMemoryExtractor, buildObserverPrompt, buildObserverSystemPrompt, combineObservationGroupRanges, deriveObservationGroupProvenance, extractCurrentTask, formatMessagesForObserver, getObservationsAsOf, hasCurrentTaskSection, injectAnchorIds, optimizeObservationsForContext, parseAnchorId, parseObservationGroups, parseObserverOutput, reconcileObservationGroupsFromReflection, renderObservationGroupsForReflection, stripEphemeralAnchorIds, stripObservationGroups, summarizeConversation, wrapInObservationGroup } from './chunk-FNWCP2TI.js';
2
2
  export { OBSERVATIONAL_MEMORY_DEFAULTS, OBSERVATION_CONTEXT_INSTRUCTIONS, OBSERVATION_CONTEXT_PROMPT, OBSERVATION_CONTINUATION_HINT } from './chunk-LSJJAJAF.js';
3
- //# sourceMappingURL=observational-memory-XKEEBG2S.js.map
4
- //# sourceMappingURL=observational-memory-XKEEBG2S.js.map
3
+ //# sourceMappingURL=observational-memory-GAYCVM5R.js.map
4
+ //# sourceMappingURL=observational-memory-GAYCVM5R.js.map
package/dist/{observational-memory-XKEEBG2S.js.map → observational-memory-GAYCVM5R.js.map} RENAMED
@@ -1 +1 @@
1
- {"version":3,"sources":[],"names":[],"mappings":"","file":"observational-memory-XKEEBG2S.js"}
1
+ {"version":3,"sources":[],"names":[],"mappings":"","file":"observational-memory-GAYCVM5R.js"}