@mastra/memory 1.32.0-alpha.1 → 1.32.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
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.32.0
|
|
6
|
+
version: "1.32.0"
|
|
7
7
|
---
|
|
8
8
|
|
|
9
9
|
## When to use
|
|
@@ -65,7 +65,7 @@ Read the individual reference documents for detailed explanations and code examp
|
|
|
65
65
|
- [Reference: Memory.updateThreadResourceId()](references/reference-memory-updateThreadResourceId.md) - The .updateThreadResourceId() method transfers ownership of a thread to a different resource by reassigning its resourceId.
|
|
66
66
|
- [Migration: AgentNetwork to .network()](references/reference-migrations-agentnetwork.md) - Migrate deprecated AgentNetwork usage to supervisor agents and the standard Agent.generate() or Agent.stream() APIs in current Mastra releases.
|
|
67
67
|
- [Memory](references/reference-migrations-upgrade-to-v1-memory.md) - Memory configuration now requires explicit parameters, and default settings have been updated for better performance and predictability.
|
|
68
|
-
- [Reference: TokenLimiterProcessor](references/reference-processors-token-limiter-processor.md) - Use TokenLimiterProcessor to constrain message tokens during
|
|
68
|
+
- [Reference: TokenLimiterProcessor](references/reference-processors-token-limiter-processor.md) - Use TokenLimiterProcessor to constrain message tokens during prompt, input, or output processing with configurable limits and strategies.
|
|
69
69
|
- [Reference: libSQL vector store](references/reference-vectors-libsql.md) - Configure LibSQLVector for similarity search and metadata filtering with local libSQL, SQLite-compatible vector extensions, or Turso databases.
|
|
70
70
|
- [Reference: MongoDB vector store](references/reference-vectors-mongodb.md) - The MongoDBVector class provides vector search using MongoDB Vector Search. It enables efficient similarity search and metadata filtering within your MongoDB collections.
|
|
71
71
|
- [Reference: OracleDB vector store](references/reference-vectors-oracledb.md) - OracleVector stores embeddings in Oracle Database VECTOR columns and exposes them through Mastra's vector interface.
|
|
@@ -4,10 +4,10 @@
|
|
|
4
4
|
|
|
5
5
|
# TokenLimiterProcessor
|
|
6
6
|
|
|
7
|
-
The `TokenLimiterProcessor` limits the number of tokens in messages.
|
|
7
|
+
The `TokenLimiterProcessor` limits the number of tokens in messages. Depending on `trimMode`, it acts as a prompt processor, an input processor, and an output processor:
|
|
8
8
|
|
|
9
|
-
- **
|
|
10
|
-
- **
|
|
9
|
+
- **Prompt processor** (`processLLMRequest`): In the default `best-fit` and `contiguous` trim modes, enforces the input budget on the provider prompt right before each model call, at every step of the agentic loop. The prompt is measured after earlier prompt processors (such as `ToolCallFilter`) have transformed it, so only tokens that actually reach the model are counted. Tool call and tool result messages are grouped so they're kept or removed together, and trimming is transient: stored messages are never modified.
|
|
10
|
+
- **Input processor** (`processInput`): In `memory-only` trim mode, filters historical messages to fit within the context window before the agentic loop starts, prioritizing recent messages
|
|
11
11
|
- **Output processor**: Limits generated response tokens via streaming or non-streaming with configurable strategies for handling exceeded limits
|
|
12
12
|
|
|
13
13
|
## Usage example
|
|
@@ -34,7 +34,7 @@ const processor = new TokenLimiterProcessor({
|
|
|
34
34
|
|
|
35
35
|
**options.countMode** (`'cumulative' | 'part'`): Whether to count tokens from the beginning of the stream or just the current part: 'cumulative' counts all tokens from start, 'part' only counts tokens in current part
|
|
36
36
|
|
|
37
|
-
**options.trimMode** (`'best-fit' | 'contiguous'`): Controls how
|
|
37
|
+
**options.trimMode** (`'best-fit' | 'contiguous' | 'memory-only'`): Controls how the token limit is enforced: 'best-fit' trims the provider prompt while keeping as many messages as possible (may create gaps), 'contiguous' trims the provider prompt but stops at the first message that does not fit (keeping a continuous suffix of conversation history), and 'memory-only' trims stored history in processInput instead of the prompt
|
|
38
38
|
|
|
39
39
|
## Returns
|
|
40
40
|
|
|
@@ -42,9 +42,11 @@ const processor = new TokenLimiterProcessor({
|
|
|
42
42
|
|
|
43
43
|
**name** (`string`): Optional processor display name
|
|
44
44
|
|
|
45
|
-
**processInput** (`(args: { messages: MastraDBMessage[]; abort: (reason?: string) => never }) => Promise<MastraDBMessage[]>`):
|
|
45
|
+
**processInput** (`(args: { messages: MastraDBMessage[]; abort: (reason?: string) => never }) => Promise<MastraDBMessage[]>`): 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
|
-
**processInputStep** (`(args: ProcessInputStepArgs) => Promise<void>`):
|
|
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
|
+
|
|
49
|
+
**processLLMRequest** (`(args: ProcessLLMRequestArgs) => Promise<ProcessLLMRequestResult>`): Enforces the input budget on the provider prompt in the 'best-fit' and 'contiguous' trim modes. Runs after earlier prompt processors have transformed the prompt, counts that exact prompt, and returns a trimmed copy for the model call only. System messages are always preserved, and tool call and tool result messages are grouped so they are kept or removed together.
|
|
48
50
|
|
|
49
51
|
**processOutputStream** (`(args: ProcessOutputStreamArgs) => Promise<ChunkType | null>`): Processes streaming output parts to limit token count during streaming. Only text and object parts count against the limit and can be withheld; lifecycle, reasoning and tool parts always pass through.
|
|
50
52
|
|
|
@@ -72,10 +74,11 @@ Images and file attachments are estimated instead of tokenized, including `file`
|
|
|
72
74
|
|
|
73
75
|
## Error behavior
|
|
74
76
|
|
|
75
|
-
When
|
|
77
|
+
When trimming input, `TokenLimiterProcessor` throws a `TripWire` error in the following cases:
|
|
76
78
|
|
|
77
|
-
- **Empty messages**: If there are no messages to process, a TripWire is thrown because you can't send an LLM request with no messages.
|
|
79
|
+
- **Empty messages**: If there are no non-system messages to process, a TripWire is thrown because you can't send an LLM request with no messages.
|
|
78
80
|
- **System messages exceed limit**: If system messages alone exceed the token limit, a TripWire is thrown because you can't send an LLM request with only system messages and no user/assistant messages.
|
|
81
|
+
- **No messages fit**: If no message fits within the remaining token budget, a TripWire is thrown because you can't send an LLM request with no messages.
|
|
79
82
|
|
|
80
83
|
```typescript
|
|
81
84
|
import { TripWire } from '@mastra/core/agent'
|
|
@@ -112,9 +115,9 @@ export const agent = new Agent({
|
|
|
112
115
|
})
|
|
113
116
|
```
|
|
114
117
|
|
|
115
|
-
### As a per-step
|
|
118
|
+
### As a per-step processor (limit multi-step token growth)
|
|
116
119
|
|
|
117
|
-
When an agent uses tools across multiple steps (e.g. `maxSteps > 1`), each step accumulates conversation history from all previous steps.
|
|
120
|
+
When an agent uses tools across multiple steps (e.g. `maxSteps > 1`), each step accumulates conversation history from all previous steps. `TokenLimiterProcessor` applies its limit at every step, measuring the prompt that's about to be sent after any earlier prompt processors have run. Register prompt-shrinking processors such as `ToolCallFilter` before it, so the limiter counts the prompt the model actually receives:
|
|
118
121
|
|
|
119
122
|
```typescript
|
|
120
123
|
import { Agent } from '@mastra/core/agent'
|
|
@@ -136,6 +139,8 @@ const result = await agent.generate('Research this topic using your tools', {
|
|
|
136
139
|
})
|
|
137
140
|
```
|
|
138
141
|
|
|
142
|
+
Processor workflows don't run `processLLMRequest`, so a `TokenLimiterProcessor` inside a processor workflow trims stored messages in `processInputStep`, before prompt processors such as `ToolCallFilter` remove anything from the request. To count the prompt the model receives, add the limiter directly to `inputProcessors`.
|
|
143
|
+
|
|
139
144
|
### As an output processor (limit response length)
|
|
140
145
|
|
|
141
146
|
Use `outputProcessors` to limit the length of generated responses:
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@mastra/memory",
|
|
3
|
-
"version": "1.32.0
|
|
3
|
+
"version": "1.32.0",
|
|
4
4
|
"description": "",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"main": "./dist/index.js",
|
|
@@ -69,12 +69,12 @@
|
|
|
69
69
|
"typescript": "^6.0.3",
|
|
70
70
|
"typescript-eslint": "^8.57.0",
|
|
71
71
|
"vitest": "4.1.11",
|
|
72
|
-
"@internal/
|
|
73
|
-
"@internal/ai-
|
|
74
|
-
"@
|
|
75
|
-
"@
|
|
76
|
-
"@internal/
|
|
77
|
-
"@internal/ai-
|
|
72
|
+
"@internal/ai-sdk-v4": "0.0.83",
|
|
73
|
+
"@internal/ai-sdk-v5": "0.0.83",
|
|
74
|
+
"@mastra/core": "1.70.0",
|
|
75
|
+
"@internal/lint": "0.0.136",
|
|
76
|
+
"@internal/types-builder": "0.0.111",
|
|
77
|
+
"@internal/ai-v6": "0.0.83"
|
|
78
78
|
},
|
|
79
79
|
"peerDependencies": {
|
|
80
80
|
"@mastra/core": ">=1.4.1-0 <2.0.0-0"
|