@mastra/memory 1.41.0 → 1.41.1-alpha.0
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.
- package/dist/docs/SKILL.md +3 -2
- package/dist/docs/assets/SOURCE_MAP.json +225 -191
- package/dist/docs/references/docs-harness-goals.md +1 -1
- package/dist/docs/references/docs-knowledge-overview.md +106 -0
- package/dist/docs/references/docs-memory-observational-memory.md +23 -23
- package/dist/docs/references/docs-memory-overview.md +19 -7
- package/dist/docs/references/reference-core-getMemory.md +2 -2
- package/dist/docs/references/reference-core-listMemory.md +3 -3
- package/dist/docs/references/reference-memory-observational-memory.md +9 -7
- package/dist/docs/references/reference-processors-token-limiter-processor.md +1 -1
- package/dist/index.cjs +1 -1
- package/dist/index.js +1 -1
- package/dist/processors/index.cjs +1 -1
- package/dist/processors/index.js +1 -1
- package/dist/{src-BncFunCW.js → src-BIae5T_v.js} +191 -122
- package/dist/src-BIae5T_v.js.map +1 -0
- package/dist/{src-gNoNdZv8.cjs → src-BbbBzTaj.cjs} +191 -122
- package/dist/src-BbbBzTaj.cjs.map +1 -0
- package/package.json +2 -2
- package/dist/src-BncFunCW.js.map +0 -1
- package/dist/src-gNoNdZv8.cjs.map +0 -1
|
@@ -108,7 +108,7 @@ The agent now has humanlike long-term memory that persists across conversations.
|
|
|
108
108
|
const memory = new Memory({
|
|
109
109
|
options: {
|
|
110
110
|
observationalMemory: {
|
|
111
|
-
model: 'deepseek/deepseek-
|
|
111
|
+
model: 'deepseek/deepseek-flash',
|
|
112
112
|
},
|
|
113
113
|
},
|
|
114
114
|
})
|
|
@@ -154,7 +154,7 @@ export const agent = new Agent({
|
|
|
154
154
|
memory: new Memory({
|
|
155
155
|
options: {
|
|
156
156
|
observationalMemory: {
|
|
157
|
-
model: '
|
|
157
|
+
model: 'auto',
|
|
158
158
|
temporalMarkers: true,
|
|
159
159
|
},
|
|
160
160
|
},
|
|
@@ -180,7 +180,7 @@ import { Memory } from '@mastra/memory'
|
|
|
180
180
|
const memory = new Memory({
|
|
181
181
|
options: {
|
|
182
182
|
observationalMemory: {
|
|
183
|
-
model: '
|
|
183
|
+
model: 'auto',
|
|
184
184
|
activateAfterIdle: 'auto',
|
|
185
185
|
activateOnProviderChange: true,
|
|
186
186
|
},
|
|
@@ -196,7 +196,7 @@ import { Memory } from '@mastra/memory'
|
|
|
196
196
|
const memory = new Memory({
|
|
197
197
|
options: {
|
|
198
198
|
observationalMemory: {
|
|
199
|
-
model: '
|
|
199
|
+
model: 'auto',
|
|
200
200
|
activateAfterIdle: '5m',
|
|
201
201
|
observation: {
|
|
202
202
|
activateAfterIdle: false,
|
|
@@ -455,7 +455,7 @@ new Agent({
|
|
|
455
455
|
options: {
|
|
456
456
|
observationalMemory: {
|
|
457
457
|
observation: {
|
|
458
|
-
model: 'deepseek/deepseek-
|
|
458
|
+
model: 'deepseek/deepseek-flash',
|
|
459
459
|
observeAttachments: false,
|
|
460
460
|
},
|
|
461
461
|
},
|
|
@@ -522,7 +522,7 @@ Set `retrieval: true` to enable the recall tool for browsing raw messages. No ve
|
|
|
522
522
|
const memory = new Memory({
|
|
523
523
|
options: {
|
|
524
524
|
observationalMemory: {
|
|
525
|
-
model: '
|
|
525
|
+
model: 'auto',
|
|
526
526
|
retrieval: true,
|
|
527
527
|
},
|
|
528
528
|
},
|
|
@@ -540,7 +540,7 @@ const memory = new Memory({
|
|
|
540
540
|
embedder: myEmbedder,
|
|
541
541
|
options: {
|
|
542
542
|
observationalMemory: {
|
|
543
|
-
model: '
|
|
543
|
+
model: 'auto',
|
|
544
544
|
retrieval: { vector: true },
|
|
545
545
|
},
|
|
546
546
|
},
|
|
@@ -557,7 +557,7 @@ By default, the recall tool scope is `'resource'`, the agent can list threads an
|
|
|
557
557
|
const memory = new Memory({
|
|
558
558
|
options: {
|
|
559
559
|
observationalMemory: {
|
|
560
|
-
model: '
|
|
560
|
+
model: 'auto',
|
|
561
561
|
retrieval: { vector: true, scope: 'thread' },
|
|
562
562
|
},
|
|
563
563
|
},
|
|
@@ -572,7 +572,7 @@ Mastra injects scope-aware instructions that teach the agent when to search, lis
|
|
|
572
572
|
const memory = new Memory({
|
|
573
573
|
options: {
|
|
574
574
|
observationalMemory: {
|
|
575
|
-
model: '
|
|
575
|
+
model: 'auto',
|
|
576
576
|
retrieval: {
|
|
577
577
|
vector: true,
|
|
578
578
|
instructions: `
|
|
@@ -641,13 +641,13 @@ const memory = new Memory({
|
|
|
641
641
|
|
|
642
642
|
Mastra recommends using a model that has a large context window (128K+ tokens) and is fast enough to run in the background without slowing down your actions.
|
|
643
643
|
|
|
644
|
-
To pin a model instead, set a concrete model ID. We've also successfully tested `openai/gpt-6-luna`, `anthropic/claude-haiku-5-5`,
|
|
644
|
+
To pin a model instead, set a concrete model ID. We've also successfully tested `openai/gpt-6-luna`, `anthropic/claude-haiku-5-5`, and `deepseek/deepseek-flash`.
|
|
645
645
|
|
|
646
646
|
```typescript
|
|
647
647
|
const memory = new Memory({
|
|
648
648
|
options: {
|
|
649
649
|
observationalMemory: {
|
|
650
|
-
model: 'deepseek/deepseek-
|
|
650
|
+
model: 'deepseek/deepseek-flash',
|
|
651
651
|
},
|
|
652
652
|
},
|
|
653
653
|
})
|
|
@@ -655,9 +655,9 @@ const memory = new Memory({
|
|
|
655
655
|
|
|
656
656
|
See [model configuration](https://mastra.ai/reference/memory/observational-memory) for using different models per agent.
|
|
657
657
|
|
|
658
|
-
> **Note:** `google/gemini-2.5-flash`
|
|
658
|
+
> **Note:** Some models preserve detail in long output unusually well. In testing, `google/gemini-2.5-flash` did this. Other models may behave differently. With such a model, the Reflector can produce reflections that stay above the configured `reflection.observationTokens` threshold even after the maximum compression retry. When this happens, the Reflector returns the smallest non-degenerate candidate produced during retries so the loop terminates instead of running forever.
|
|
659
659
|
>
|
|
660
|
-
> If you'd rather have more aggressive compression on the Reflector,
|
|
660
|
+
> If you'd rather have more aggressive compression on the Reflector, pick a model that condenses more readily, such as `deepseek/deepseek-flash`. You can use a detail-preserving model for the Observer and a condensing one for the Reflector. See [different models per agent](https://mastra.ai/reference/memory/observational-memory).
|
|
661
661
|
|
|
662
662
|
### Token-tiered model selection
|
|
663
663
|
|
|
@@ -678,7 +678,7 @@ const memory = new Memory({
|
|
|
678
678
|
5_000: 'openrouter/mistralai/ministral-8b-2512',
|
|
679
679
|
20_000: 'openrouter/mistralai/mistral-small-2603',
|
|
680
680
|
40_000: 'openai/gpt-6-luna',
|
|
681
|
-
1_000_000: 'google/gemini-3.
|
|
681
|
+
1_000_000: 'google/gemini-3.8-flash',
|
|
682
682
|
},
|
|
683
683
|
}),
|
|
684
684
|
},
|
|
@@ -686,7 +686,7 @@ const memory = new Memory({
|
|
|
686
686
|
model: new ModelByInputTokens({
|
|
687
687
|
upTo: {
|
|
688
688
|
20_000: 'openai/gpt-6-luna',
|
|
689
|
-
100_000: '
|
|
689
|
+
100_000: 'deepseek/deepseek-flash',
|
|
690
690
|
},
|
|
691
691
|
}),
|
|
692
692
|
},
|
|
@@ -709,7 +709,7 @@ Each thread has its own observations. This scope is well tested and works well a
|
|
|
709
709
|
const memory = new Memory({
|
|
710
710
|
options: {
|
|
711
711
|
observationalMemory: {
|
|
712
|
-
model: '
|
|
712
|
+
model: 'auto',
|
|
713
713
|
scope: 'thread',
|
|
714
714
|
},
|
|
715
715
|
},
|
|
@@ -728,7 +728,7 @@ In resource scope, observations are shared across all threads for a resource (ty
|
|
|
728
728
|
- **Agent understanding:** Each thread sees a mix of observations from every thread for the resource. Every new thread starts with context from earlier threads, and the agent may continue work that another thread started but didn't finish.
|
|
729
729
|
- **Performance:** Unobserved messages across _all_ threads are processed together, which is slow for users with many existing threads.
|
|
730
730
|
|
|
731
|
-
|
|
731
|
+
[Knowledge](https://mastra.ai/docs/knowledge/overview), now in alpha, gives agents shared information across threads and is planned to replace resource scope. Until it's stable, use the alternatives below.
|
|
732
732
|
|
|
733
733
|
#### Cross-thread continuity without resource scope
|
|
734
734
|
|
|
@@ -743,7 +743,7 @@ Use thread scope with one or both of these features instead:
|
|
|
743
743
|
const memory = new Memory({
|
|
744
744
|
options: {
|
|
745
745
|
observationalMemory: {
|
|
746
|
-
model: '
|
|
746
|
+
model: 'auto',
|
|
747
747
|
retrieval: true,
|
|
748
748
|
},
|
|
749
749
|
workingMemory: {
|
|
@@ -762,7 +762,7 @@ OM uses token thresholds to decide when to observe and reflect. See [token budge
|
|
|
762
762
|
const memory = new Memory({
|
|
763
763
|
options: {
|
|
764
764
|
observationalMemory: {
|
|
765
|
-
model: '
|
|
765
|
+
model: 'auto',
|
|
766
766
|
observation: {
|
|
767
767
|
// when to run the Observer (default: 30,000)
|
|
768
768
|
messageTokens: 30_000,
|
|
@@ -873,7 +873,7 @@ With `"auto"`, Mastra chooses an idle activation TTL from the active model provi
|
|
|
873
873
|
const memory = new Memory({
|
|
874
874
|
options: {
|
|
875
875
|
observationalMemory: {
|
|
876
|
-
model: '
|
|
876
|
+
model: 'auto',
|
|
877
877
|
activateAfterIdle: 'auto',
|
|
878
878
|
activateOnProviderChange: true,
|
|
879
879
|
},
|
|
@@ -893,7 +893,7 @@ Changing models or providers mid-thread will invalidate the prompt cache. If you
|
|
|
893
893
|
const memory = new Memory({
|
|
894
894
|
options: {
|
|
895
895
|
observationalMemory: {
|
|
896
|
-
model: '
|
|
896
|
+
model: 'auto',
|
|
897
897
|
activateAfterIdle: { default: 'auto', anthropic: '1h' },
|
|
898
898
|
},
|
|
899
899
|
},
|
|
@@ -917,7 +917,7 @@ To disable async buffering and use synchronous observation/reflection instead:
|
|
|
917
917
|
const memory = new Memory({
|
|
918
918
|
options: {
|
|
919
919
|
observationalMemory: {
|
|
920
|
-
model: '
|
|
920
|
+
model: 'auto',
|
|
921
921
|
observation: {
|
|
922
922
|
bufferTokens: false,
|
|
923
923
|
},
|
|
@@ -940,7 +940,7 @@ Set `observation.previousObserverTokens` to limit how many tokens of previous ob
|
|
|
940
940
|
const memory = new Memory({
|
|
941
941
|
options: {
|
|
942
942
|
observationalMemory: {
|
|
943
|
-
model: '
|
|
943
|
+
model: 'auto',
|
|
944
944
|
observation: {
|
|
945
945
|
previousObserverTokens: 10_000, // keep only ~10k tokens of recent observations
|
|
946
946
|
},
|
|
@@ -9,8 +9,7 @@ Memory gives your agent access to earlier messages and tool results. The agent c
|
|
|
9
9
|
Mastra agents can be configured to store [message history](https://mastra.ai/docs/memory/message-history). Additionally, you can enable:
|
|
10
10
|
|
|
11
11
|
- [Observational Memory](https://mastra.ai/docs/memory/observational-memory) (Recommended): Uses background agents to maintain a dense observation log that replaces raw message history as it grows. This keeps the context window small while preserving long-term memory.
|
|
12
|
-
- [Working memory](https://mastra.ai/docs/memory/working-memory): Stores persistent, structured user
|
|
13
|
-
- [Semantic recall](https://mastra.ai/docs/memory/semantic-recall): Retrieves relevant past messages based on semantic meaning rather than exact keywords.
|
|
12
|
+
- [Working memory](https://mastra.ai/docs/memory/working-memory): Stores persistent, structured information about the user, the application, or the task, such as names, preferences, and goals.
|
|
14
13
|
- [Multi-user threads](https://mastra.ai/docs/memory/multi-user-threads): Share one thread between multiple users.
|
|
15
14
|
|
|
16
15
|
If the combined memory exceeds the model's context limit, [memory processors](https://mastra.ai/docs/memory/memory-processors) can filter, trim, or prioritize content so the most relevant information is preserved.
|
|
@@ -161,7 +160,7 @@ const response = await memoryAgent.generate('Remember my favorite color is blue.
|
|
|
161
160
|
})
|
|
162
161
|
```
|
|
163
162
|
|
|
164
|
-
Scopes can also come from the
|
|
163
|
+
Scopes can also come from the request context and from the agent. Scopes from the call and the request context arrive first. The agent's `scopes` option then adds a list to them, or a function receives them and returns the run's final set:
|
|
165
164
|
|
|
166
165
|
```typescript
|
|
167
166
|
import { Agent } from '@mastra/core/agent'
|
|
@@ -170,10 +169,10 @@ import { Memory } from '@mastra/memory'
|
|
|
170
169
|
export const memoryAgent = new Agent({
|
|
171
170
|
id: 'memory-agent',
|
|
172
171
|
name: 'Memory Agent',
|
|
173
|
-
scopes: ({ requestContext }) => {
|
|
172
|
+
scopes: ({ scopes, requestContext }) => {
|
|
174
173
|
// Set by your auth middleware. Request bodies can fill unreserved keys.
|
|
175
174
|
const orgId = requestContext.get('org-id')
|
|
176
|
-
return orgId ? [`org:${orgId}`] :
|
|
175
|
+
return orgId ? [...scopes, `org:${orgId}`] : scopes
|
|
177
176
|
},
|
|
178
177
|
memory: new Memory(),
|
|
179
178
|
})
|
|
@@ -181,7 +180,7 @@ export const memoryAgent = new Agent({
|
|
|
181
180
|
|
|
182
181
|
The resolver's inputs must come from the server, not the client: a request body can set any request context key that isn't reserved. Trusted server middleware can also set scopes directly with the `MASTRA_SCOPES_KEY` request context key. Visit [Request Context](https://mastra.ai/docs/server/request-context) for details. Clients can't send scopes in a request body.
|
|
183
182
|
|
|
184
|
-
You can mix scopes with `memory.resource`, `memory.thread`, or the resource and thread request context keys, as long as they agree. If a `resource:` or `thread:` scope names a different value than another source, the call throws an error.
|
|
183
|
+
You can mix scopes with `memory.resource`, `memory.thread`, or the resource and thread request context keys, as long as they agree. If a `resource:` or `thread:` scope names a different value than another source, the call throws an error. A `scopes` function must also return every `resource:` and `thread:` scope it receives. Dropping one throws an error.
|
|
185
184
|
|
|
186
185
|
Tools, processors, and subagents receive the run's other scopes, but not its `resource:` and `thread:` scopes. Each nested agent call picks its own resource and thread.
|
|
187
186
|
|
|
@@ -189,6 +188,8 @@ Tools, processors, and subagents receive the run's other scopes, but not its `re
|
|
|
189
188
|
|
|
190
189
|
Long conversations can fill the context window with raw message history and reduce agent performance. [Observational Memory](https://mastra.ai/docs/memory/observational-memory) uses background agents to compress older messages into observations. This reduces the context used by message history while retaining information for later turns.
|
|
191
190
|
|
|
191
|
+
Compression loses exact wording, so Observational Memory can register a `recall` tool that goes back to the original messages. The tool is off by default: set `retrieval: true` to enable browsing, which lists earlier messages across the resource's threads unless you pass `scope: 'thread'`. With `retrieval: { vector: true }` plus a vector store and embedder on `Memory`, it can also search by meaning. That search matches observation groups rather than raw messages, so a detail the summary dropped may not turn up, and each hit links back to the messages it came from. See [retrieval mode](https://mastra.ai/docs/memory/observational-memory).
|
|
192
|
+
|
|
192
193
|
**For AI agents:** Using Observational Memory requires a storage provider! You either need to set it on the Mastra instance at `src/mastra/index.ts` or pass it to the Agent constructor.
|
|
193
194
|
|
|
194
195
|
```typescript
|
|
@@ -302,4 +303,15 @@ Visit [Request Context](https://mastra.ai/docs/server/request-context) for more
|
|
|
302
303
|
- [`Memory` reference](https://mastra.ai/reference/memory/memory-class)
|
|
303
304
|
- [Tracing](https://mastra.ai/docs/observability/tracing/overview)
|
|
304
305
|
- [Request Context](https://mastra.ai/docs/server/request-context)
|
|
305
|
-
- [Mastra Code](https://code.mastra.ai/): A coding agent using Mastra's memory system
|
|
306
|
+
- [Mastra Code](https://code.mastra.ai/): A coding agent using Mastra's memory system
|
|
307
|
+
|
|
308
|
+
**For AI agents:** Observational Memory has a few failure modes that cause real problems.
|
|
309
|
+
|
|
310
|
+
- Thread scope requires a `threadId` when you call the agent. Without one, Observational Memory throws.
|
|
311
|
+
- On an existing thread, the first turn loads every stored message until the first observation completes. A large thread pays a one-time context cost.
|
|
312
|
+
- `lastMessages` does nothing under Observational Memory. It replaces raw history itself, so the MessageHistory processor is skipped.
|
|
313
|
+
- Leave `observation.observeOnContextOverflow` at its default `true`. When the main model's context overflows, it can activate buffered observations, observe pending messages, and retry the request. It skips read-only requests and only retries when it observed or activated something. With it off, the overflowing request fails.
|
|
314
|
+
- Some invalid options are validated on first use, not when you construct `Memory`. For example, `shareTokenBudget: true` with async buffering enabled fails on the first memory operation. Read the error instead of retrying.
|
|
315
|
+
- With async buffering, work continues in the background. Call `await memory.settled()` before closing storage or shutting down, or that work is lost.
|
|
316
|
+
- The observation mutex only works inside one process. Across processes, coordination comes from a shared PubSub backend and storage: the agent loop uses a backend with leases to run one loop per thread, and the Observer runs inside that loop. Configure every process with the same backend with leases and the same storage. See [Running across processes](https://mastra.ai/docs/signals/running-across-processes).
|
|
317
|
+
- Debug with `OM_DEBUG=1`, which writes `om-debug.log`, plus `getStatus()` and the `onDebugEvent` callback.
|
|
@@ -20,11 +20,11 @@ const thread = await memory.createThread({
|
|
|
20
20
|
|
|
21
21
|
## Parameters
|
|
22
22
|
|
|
23
|
-
**
|
|
23
|
+
**name** (`TMemoryName extends keyof TMemory`): The registry key of the memory instance to retrieve. Must match a key used when registering memory in the Mastra constructor.
|
|
24
24
|
|
|
25
25
|
## Returns
|
|
26
26
|
|
|
27
|
-
**memory** (`TMemory[
|
|
27
|
+
**memory** (`TMemory[TMemoryName]`): The memory instance with the specified key. Throws an error if the memory is not found.
|
|
28
28
|
|
|
29
29
|
## Example: Registering and retrieving memory
|
|
30
30
|
|
|
@@ -9,7 +9,7 @@ The `.listMemory()` method returns all memory instances registered with the Mast
|
|
|
9
9
|
## Usage example
|
|
10
10
|
|
|
11
11
|
```typescript
|
|
12
|
-
const memoryInstances = mastra.listMemory()
|
|
12
|
+
const memoryInstances = mastra.listMemory() ?? {}
|
|
13
13
|
|
|
14
14
|
for (const [key, memory] of Object.entries(memoryInstances)) {
|
|
15
15
|
console.log(`Memory "${key}": ${memory.id}`)
|
|
@@ -22,7 +22,7 @@ This method takes no parameters.
|
|
|
22
22
|
|
|
23
23
|
## Returns
|
|
24
24
|
|
|
25
|
-
**memory** (`Record<string, MastraMemory
|
|
25
|
+
**memory** (`Record<string, MastraMemory> | undefined`): An object containing all registered memory instances, keyed by their registry keys.
|
|
26
26
|
|
|
27
27
|
## Example: Checking registered memory
|
|
28
28
|
|
|
@@ -49,7 +49,7 @@ const mastra = new Mastra({
|
|
|
49
49
|
})
|
|
50
50
|
|
|
51
51
|
// List all registered memory instances
|
|
52
|
-
const allMemory = mastra.listMemory()
|
|
52
|
+
const allMemory = mastra.listMemory() ?? {}
|
|
53
53
|
console.log(Object.keys(allMemory)) // ["conversationMemory", "analyticsMemory"]
|
|
54
54
|
```
|
|
55
55
|
|
|
@@ -43,6 +43,8 @@ OM performs thresholding with fast local token estimation. Text uses `tokenx`, a
|
|
|
43
43
|
|
|
44
44
|
**resolveModel** (`(modelId: string, context: { requestContext?: RequestContext }) => MastraModelConfig | Promise<MastraModelConfig>`): Creates the model automatic selection picked, so it can use your credentials and routing. Receives only concrete model IDs, never "auto". When omitted, the picked ID goes through Mastra model routing.
|
|
45
45
|
|
|
46
|
+
**canUseProvider** (`(providerId: string, context: { requestContext?: RequestContext }) => boolean`): Decides whether "auto" treats a provider as usable. Replaces the built-in GOOGLE_GENERATIVE_AI_API_KEY check that decides whether automatic selection prefers Gemini. Return false for any provider the current request cannot authenticate, for example a provider whose key is not available in the request context. The context.requestContext is the request context of the run making the OM model call, so credentials can be resolved per request instead of from the server environment. See the model row for the selection order.
|
|
47
|
+
|
|
46
48
|
**scope** (`'resource' | 'thread'`): Memory scope for observations. 'thread' keeps observations per-thread. 'resource' is deprecated and will be removed in a future release. It shares observations across all threads for a resource and works much worse than thread scope for prompt caching and agent understanding. For cross-thread continuity, use thread scope with retrieval or resource-scoped working memory. See resource scope (deprecated). (Default: `'thread'`)
|
|
47
49
|
|
|
48
50
|
**activateAfterIdle** (`number | string | false | "auto" | Record<string, number | string | false | "auto">`): Time before buffered observations are forced to activate after inactivity, even before observation.messageTokens is reached. Accepts a numeric millisecond value such as 300_000, duration strings like "5m" or "1hr", "auto" for a provider-aware prompt cache TTL, false to disable inherited observation idle activation, or an object of per-provider TTLs such as { default: "auto", anthropic: "1h" }. Object keys match the actor model provider before the first ., case-insensitively, so anthropic covers the direct Anthropic provider but not Claude through another provider such as amazon-bedrock; default covers every other provider. Reflections do not inherit this setting. Use reflection.activateAfterIdle to opt reflections into idle activation.
|
|
@@ -71,7 +73,7 @@ OM performs thresholding with fast local token estimation. Text uses `tokenx`, a
|
|
|
71
73
|
|
|
72
74
|
**observation.manageWorkingMemory** (`boolean`): Let the Observer manage working memory through OM extraction. Adds WorkingMemoryExtractor, defaults workingMemory.agentManaged to false, and defaults workingMemory.useStateSignals to true. See Working memory updates.
|
|
73
75
|
|
|
74
|
-
**observation.observeAttachments** (`'auto' | boolean | string[]`): Controls which image/file attachments are forwarded to the Observer model alongside their placeholder text lines.
|
|
76
|
+
**observation.observeAttachments** (`'auto' | boolean | string[]`): Controls which image/file attachments are forwarded to the Observer model alongside their placeholder text lines. By default only images and PDFs are forwarded. true forwards all attachments. false drops all attachments while keeping placeholders visible. 'auto' uses the provider capabilities registry to decide: attachments are forwarded when the Observer model supports multimodal input, dropped otherwise, and forwarded when no capability data is available for the model. An array is a case-insensitive mimeType allowlist supporting exact matches ('application/pdf'), wildcard subtypes ('image/\*'), and bare '\*' for everything. Useful when the Observer model is text-only (e.g. some DeepSeek endpoints) while the main agent uses a multimodal model, or when you only want specific file types forwarded. Tool-result attachments are filtered using the same rule.
|
|
75
77
|
|
|
76
78
|
**observation.maxRetries** (`number`): Retries after the initial Observer model call on transient provider errors. Governs OM's own retry ladder; the Observer model call itself is configured with no provider-level retries.
|
|
77
79
|
|
|
@@ -244,7 +246,7 @@ export const agent = new Agent({
|
|
|
244
246
|
memory: new Memory({
|
|
245
247
|
options: {
|
|
246
248
|
observationalMemory: {
|
|
247
|
-
model: '
|
|
249
|
+
model: 'auto',
|
|
248
250
|
observation: {
|
|
249
251
|
messageTokens: 20_000,
|
|
250
252
|
},
|
|
@@ -325,7 +327,7 @@ export const agent = new Agent({
|
|
|
325
327
|
options: {
|
|
326
328
|
observationalMemory: {
|
|
327
329
|
observation: {
|
|
328
|
-
model: '
|
|
330
|
+
model: 'auto',
|
|
329
331
|
},
|
|
330
332
|
reflection: {
|
|
331
333
|
model: 'openai/gpt-6-luna',
|
|
@@ -352,7 +354,7 @@ export const agent = new Agent({
|
|
|
352
354
|
memory: new Memory({
|
|
353
355
|
options: {
|
|
354
356
|
observationalMemory: {
|
|
355
|
-
model: '
|
|
357
|
+
model: 'auto',
|
|
356
358
|
observation: {
|
|
357
359
|
// Focus observations on health-related preferences and goals
|
|
358
360
|
instruction:
|
|
@@ -397,7 +399,7 @@ export const agent = new Agent({
|
|
|
397
399
|
memory: new Memory({
|
|
398
400
|
options: {
|
|
399
401
|
observationalMemory: {
|
|
400
|
-
model: '
|
|
402
|
+
model: 'auto',
|
|
401
403
|
observation: {
|
|
402
404
|
messageTokens: 30_000,
|
|
403
405
|
// Buffer every 5k tokens (runs in background)
|
|
@@ -424,7 +426,7 @@ To disable async buffering entirely:
|
|
|
424
426
|
|
|
425
427
|
```typescript
|
|
426
428
|
observationalMemory: {
|
|
427
|
-
model: "
|
|
429
|
+
model: "auto",
|
|
428
430
|
observation: {
|
|
429
431
|
bufferTokens: false,
|
|
430
432
|
},
|
|
@@ -910,7 +912,7 @@ Group IDs in search results include the record that holds them (`groupId@recordI
|
|
|
910
912
|
new ModelByInputTokens(config)
|
|
911
913
|
```
|
|
912
914
|
|
|
913
|
-
Where `config` is an object with `upTo` keys that map token thresholds (numbers) to model targets.
|
|
915
|
+
Where `config` is an object with `upTo` keys that map token thresholds (numbers) to model targets. Each tier needs a concrete model. The example below names specific models instead of `"auto"`.
|
|
914
916
|
|
|
915
917
|
#### Example
|
|
916
918
|
|
|
@@ -42,7 +42,7 @@ const processor = new TokenLimiterProcessor({
|
|
|
42
42
|
|
|
43
43
|
**name** (`string`): Processor display name set to 'Token Limiter'
|
|
44
44
|
|
|
45
|
-
**processInput** (`(args:
|
|
45
|
+
**processInput** (`(args: ProcessInputArgs) => Promise<MessageList>`): Trims stored history to fit within the token limit before the agentic loop starts in 'memory-only' trim mode, prioritizing recent messages while preserving system messages and the current turn
|
|
46
46
|
|
|
47
47
|
**processInputStep** (`(args: ProcessInputStepArgs) => Promise<void>`): In 'memory-only' trim mode, applies stored-history trimming at each step. In the 'best-fit' and 'contiguous' trim modes, it leaves trimming to processLLMRequest when the agent runs that method for this processor. Otherwise it trims stored history, for example in generateLegacy() and streamLegacy() or when the limiter is inside a processor workflow.
|
|
48
48
|
|
package/dist/index.cjs
CHANGED
|
@@ -1,5 +1,5 @@
|
|
|
1
1
|
Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
|
|
2
|
-
const require_src = require("./src-
|
|
2
|
+
const require_src = require("./src-BbbBzTaj.cjs");
|
|
3
3
|
let _mastra_core_processors = require("@mastra/core/processors");
|
|
4
4
|
exports.AUTO_MODEL_BY_PROVIDER = require_src.AUTO_MODEL_BY_PROVIDER;
|
|
5
5
|
exports.Extractor = require_src.Extractor;
|
package/dist/index.js
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
export { d as AUTO_MODEL_BY_PROVIDER, U as Extractor, w as KnowledgeSemanticIndexCoordinator, t as Memory, n as MessageHistory, g as ModelByInputTokens, k as SUMMARIZE_THREAD_DEFAULTS, r as SemanticRecall, T as StaleKnowledgeSemanticIndexError, E as Subconscious, p as WORKING_MEMORY_STATE_ID, m as WORKING_MEMORY_STATE_PROCESSOR_ID, i as WorkingMemory, D as WorkingMemoryExtractor, h as WorkingMemoryStateProcessor, O as deepMergeWorkingMemory, a as extractWorkingMemoryContent, o as extractWorkingMemoryTags, c as getObservationsAsOf, s as removeWorkingMemoryTags, f as resolveAutoModelId, A as summarizeConversation } from "./src-
|
|
1
|
+
export { d as AUTO_MODEL_BY_PROVIDER, U as Extractor, w as KnowledgeSemanticIndexCoordinator, t as Memory, n as MessageHistory, g as ModelByInputTokens, k as SUMMARIZE_THREAD_DEFAULTS, r as SemanticRecall, T as StaleKnowledgeSemanticIndexError, E as Subconscious, p as WORKING_MEMORY_STATE_ID, m as WORKING_MEMORY_STATE_PROCESSOR_ID, i as WorkingMemory, D as WorkingMemoryExtractor, h as WorkingMemoryStateProcessor, O as deepMergeWorkingMemory, a as extractWorkingMemoryContent, o as extractWorkingMemoryTags, c as getObservationsAsOf, s as removeWorkingMemoryTags, f as resolveAutoModelId, A as summarizeConversation } from "./src-BIae5T_v.js";
|
|
@@ -1,5 +1,5 @@
|
|
|
1
1
|
Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
|
|
2
|
-
const require_src = require("../src-
|
|
2
|
+
const require_src = require("../src-BbbBzTaj.cjs");
|
|
3
3
|
exports.AUTO_MODEL_BY_PROVIDER = require_src.AUTO_MODEL_BY_PROVIDER;
|
|
4
4
|
exports.Extractor = require_src.Extractor;
|
|
5
5
|
exports.ModelByInputTokens = require_src.ModelByInputTokens;
|
package/dist/processors/index.js
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
export { d as AUTO_MODEL_BY_PROVIDER, U as Extractor, g as ModelByInputTokens, W as OBSERVATIONAL_MEMORY_DEFAULTS, G as OBSERVATION_CONTEXT_INSTRUCTIONS, K as OBSERVATION_CONTEXT_PROMPT, q as OBSERVATION_CONTEXT_PROMPT_THREAD, J as OBSERVATION_CONTINUATION_HINT, M as OBSERVER_SYSTEM_PROMPT, u as ObservationalMemory, l as ObservationalMemoryProcessor, j as TokenCounter, D as WorkingMemoryExtractor, N as buildObserverPrompt, P as buildObserverSystemPrompt, _ as combineObservationGroupRanges, v as deriveObservationGroupProvenance, F as extractCurrentTask, I as formatMessagesForObserver, Y as getObservationContextPrompt, c as getObservationsAsOf, L as hasCurrentTaskSection, B as injectAnchorIds, R as optimizeObservationsForContext, V as parseAnchorId, y as parseObservationGroups, z as parseObserverOutput, b as reconcileObservationGroupsFromReflection, x as renderObservationGroupsForReflection, f as resolveAutoModelId, H as stripEphemeralAnchorIds, S as stripObservationGroups, A as summarizeConversation, C as wrapInObservationGroup } from "../src-
|
|
1
|
+
export { d as AUTO_MODEL_BY_PROVIDER, U as Extractor, g as ModelByInputTokens, W as OBSERVATIONAL_MEMORY_DEFAULTS, G as OBSERVATION_CONTEXT_INSTRUCTIONS, K as OBSERVATION_CONTEXT_PROMPT, q as OBSERVATION_CONTEXT_PROMPT_THREAD, J as OBSERVATION_CONTINUATION_HINT, M as OBSERVER_SYSTEM_PROMPT, u as ObservationalMemory, l as ObservationalMemoryProcessor, j as TokenCounter, D as WorkingMemoryExtractor, N as buildObserverPrompt, P as buildObserverSystemPrompt, _ as combineObservationGroupRanges, v as deriveObservationGroupProvenance, F as extractCurrentTask, I as formatMessagesForObserver, Y as getObservationContextPrompt, c as getObservationsAsOf, L as hasCurrentTaskSection, B as injectAnchorIds, R as optimizeObservationsForContext, V as parseAnchorId, y as parseObservationGroups, z as parseObserverOutput, b as reconcileObservationGroupsFromReflection, x as renderObservationGroupsForReflection, f as resolveAutoModelId, H as stripEphemeralAnchorIds, S as stripObservationGroups, A as summarizeConversation, C as wrapInObservationGroup } from "../src-BIae5T_v.js";
|