@mastra/oracledb 0.5.4-alpha.0 → 0.5.5-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/_types/@internal_core/dist/memory/index.d.ts +12 -15
- package/dist/docs/SKILL.md +1 -1
- package/dist/docs/assets/SOURCE_MAP.json +1 -1
- package/dist/docs/references/docs-memory-observational-memory.md +28 -16
- package/dist/docs/references/docs-memory-semantic-recall.md +29 -3
- package/dist/docs/references/docs-memory-working-memory.md +3 -3
- package/dist/docs/references/docs-storage.md +1 -1
- package/dist/docs/references/integrations-databases-oracledb.md +1 -1
- package/dist/docs/references/reference-rag-metadata-filters.md +1 -1
- package/dist/docs/references/reference-rag-retrieval.md +24 -13
- package/dist/docs/references/reference-storage-retention.md +1 -1
- package/dist/docs/references/reference-vectors-oracledb.md +2 -2
- package/dist/index.cjs +58 -91
- package/dist/index.cjs.map +1 -1
- package/dist/index.js +56 -88
- package/dist/index.js.map +1 -1
- package/dist/storage/domains/memory/index.d.ts +1 -1
- package/dist/storage/domains/memory/index.d.ts.map +1 -1
- package/dist/storage/domains/memory/observational-buffering.d.ts +1 -1
- package/dist/storage/domains/memory/observational-buffering.d.ts.map +1 -1
- package/dist/storage/domains/memory/observational.d.ts +1 -1
- package/dist/storage/domains/memory/observational.d.ts.map +1 -1
- package/package.json +11 -12
|
@@ -1,4 +1,3 @@
|
|
|
1
|
-
//#region src/memory/index.d.ts
|
|
2
1
|
/**
|
|
3
2
|
* Shared rules for observational memory lifecycle writes. Every storage adapter applies
|
|
4
3
|
* these inside its own atomic section (lock, transaction, or conditional update), so the
|
|
@@ -9,18 +8,18 @@
|
|
|
9
8
|
* into the table schema they get from `@mastra/core`, so the columns exist even when the
|
|
10
9
|
* installed core predates them.
|
|
11
10
|
*/
|
|
12
|
-
declare const OBSERVATIONAL_MEMORY_LIFECYCLE_COLUMNS: {
|
|
11
|
+
export declare const OBSERVATIONAL_MEMORY_LIFECYCLE_COLUMNS: {
|
|
13
12
|
readonly supersededBy: {
|
|
14
13
|
readonly type: 'text';
|
|
15
14
|
readonly nullable: true;
|
|
16
15
|
};
|
|
17
16
|
};
|
|
18
17
|
/** `schema` plus {@link OBSERVATIONAL_MEMORY_LIFECYCLE_COLUMNS}; `undefined` when `schema` is. */
|
|
19
|
-
declare function withObservationalMemoryLifecycleColumns<T extends object>(schema: T | undefined): (T & typeof OBSERVATIONAL_MEMORY_LIFECYCLE_COLUMNS) | undefined;
|
|
18
|
+
export declare function withObservationalMemoryLifecycleColumns<T extends object>(schema: T | undefined): (T & typeof OBSERVATIONAL_MEMORY_LIFECYCLE_COLUMNS) | undefined;
|
|
20
19
|
/**
|
|
21
20
|
* Result of `commitActiveObservations`.
|
|
22
21
|
*/
|
|
23
|
-
interface UpdateActiveObservationsResult {
|
|
22
|
+
export interface UpdateActiveObservationsResult {
|
|
24
23
|
/** Whether the observations were written. */
|
|
25
24
|
applied: boolean;
|
|
26
25
|
/**
|
|
@@ -38,14 +37,14 @@ interface UpdateActiveObservationsResult {
|
|
|
38
37
|
* the head's cursor. Chunks carry `lastObservedAt = max message time + 1ms`, so a chunk is
|
|
39
38
|
* wholly covered iff `head.lastObservedAt >= chunk.lastObservedAt - 1ms`.
|
|
40
39
|
*/
|
|
41
|
-
interface UpdateBufferedObservationsResult {
|
|
40
|
+
export interface UpdateBufferedObservationsResult {
|
|
42
41
|
/** Whether the chunk was stored. */
|
|
43
42
|
persisted: boolean;
|
|
44
43
|
/** The record the chunk was written to (or would have been written to). */
|
|
45
44
|
recordId: string;
|
|
46
45
|
}
|
|
47
46
|
/** The fields of an observational memory record that decide head order. */
|
|
48
|
-
interface ObservationalMemoryHeadOrderFields {
|
|
47
|
+
export interface ObservationalMemoryHeadOrderFields {
|
|
49
48
|
generationCount: number;
|
|
50
49
|
createdAt: Date | string;
|
|
51
50
|
id: string;
|
|
@@ -54,16 +53,16 @@ interface ObservationalMemoryHeadOrderFields {
|
|
|
54
53
|
* Canonical head order: `generationCount DESC, createdAt ASC, id ASC`.
|
|
55
54
|
* Returns a negative number when `a` sorts before `b` (i.e. `a` is the better head candidate).
|
|
56
55
|
*/
|
|
57
|
-
declare function compareObservationalMemoryHeadOrder(a: ObservationalMemoryHeadOrderFields, b: ObservationalMemoryHeadOrderFields): number;
|
|
56
|
+
export declare function compareObservationalMemoryHeadOrder(a: ObservationalMemoryHeadOrderFields, b: ObservationalMemoryHeadOrderFields): number;
|
|
58
57
|
/**
|
|
59
58
|
* A buffered chunk stores `lastObservedAt = max message time + 1ms`. It is wholly covered
|
|
60
59
|
* (every message it observed is already at or before the cursor) iff
|
|
61
60
|
* `cursor >= chunk.lastObservedAt - 1ms`.
|
|
62
61
|
*/
|
|
63
|
-
declare function isBufferedChunkCoveredByCursor(chunkLastObservedAt: Date | string, cursor: Date | string | null | undefined): boolean;
|
|
62
|
+
export declare function isBufferedChunkCoveredByCursor(chunkLastObservedAt: Date | string, cursor: Date | string | null | undefined): boolean;
|
|
64
63
|
/** The later of two cursors; `undefined` only when both are absent. */
|
|
65
|
-
declare function maxObservationCursor(a: Date | string | null | undefined, b: Date | string | null | undefined): Date | undefined;
|
|
66
|
-
interface ReflectionTextPlan {
|
|
64
|
+
export declare function maxObservationCursor(a: Date | string | null | undefined, b: Date | string | null | undefined): Date | undefined;
|
|
65
|
+
export interface ReflectionTextPlan {
|
|
67
66
|
/** `equal`: stored text equals the snapshot. `append`: observations were appended after the snapshot. */
|
|
68
67
|
mode: 'equal' | 'append';
|
|
69
68
|
observations: string;
|
|
@@ -78,7 +77,7 @@ interface ReflectionTextPlan {
|
|
|
78
77
|
* after the reflection, and its tokens are added.
|
|
79
78
|
* - Anything else (a non-append rewrite): `null` — the reflection must not be applied.
|
|
80
79
|
*/
|
|
81
|
-
declare function planReflectionGenerationText(input: {
|
|
80
|
+
export declare function planReflectionGenerationText(input: {
|
|
82
81
|
storedObservations: string;
|
|
83
82
|
storedObservationTokenCount: number;
|
|
84
83
|
snapshotObservations: string;
|
|
@@ -91,12 +90,10 @@ declare function planReflectionGenerationText(input: {
|
|
|
91
90
|
* Callers of `updateActiveObservations` (which resolves `void`) can't see a commit result, so a
|
|
92
91
|
* write that was not applied throws instead of resolving as if it had committed.
|
|
93
92
|
*/
|
|
94
|
-
declare function assertActiveObservationsApplied(result: UpdateActiveObservationsResult, id: string): void;
|
|
93
|
+
export declare function assertActiveObservationsApplied(result: UpdateActiveObservationsResult, id: string): void;
|
|
95
94
|
/**
|
|
96
95
|
* Whether the stored text can still accept a reflection built from `snapshot`
|
|
97
96
|
* (equal, or only appended to since).
|
|
98
97
|
*/
|
|
99
|
-
declare function isAppendOnlySince(storedObservations: string, snapshotObservations: string): boolean;
|
|
100
|
-
//#endregion
|
|
101
|
-
export { OBSERVATIONAL_MEMORY_LIFECYCLE_COLUMNS, ObservationalMemoryHeadOrderFields, ReflectionTextPlan, UpdateActiveObservationsResult, UpdateBufferedObservationsResult, assertActiveObservationsApplied, compareObservationalMemoryHeadOrder, isAppendOnlySince, isBufferedChunkCoveredByCursor, maxObservationCursor, planReflectionGenerationText, withObservationalMemoryLifecycleColumns };
|
|
98
|
+
export declare function isAppendOnlySince(storedObservations: string, snapshotObservations: string): boolean;
|
|
102
99
|
//# sourceMappingURL=index.d.ts.map
|
package/dist/docs/SKILL.md
CHANGED
|
@@ -3,7 +3,7 @@ name: mastra-oracledb
|
|
|
3
3
|
description: Documentation for @mastra/oracledb. Use when working with @mastra/oracledb APIs, configuration, or implementation.
|
|
4
4
|
metadata:
|
|
5
5
|
package: "@mastra/oracledb"
|
|
6
|
-
version: "0.5.
|
|
6
|
+
version: "0.5.5-alpha.0"
|
|
7
7
|
---
|
|
8
8
|
|
|
9
9
|
## When to use
|
|
@@ -20,7 +20,7 @@ export const agent = new Agent({
|
|
|
20
20
|
id: 'my-agent',
|
|
21
21
|
name: 'my-agent',
|
|
22
22
|
instructions: 'You are a helpful assistant.',
|
|
23
|
-
model: 'openai/gpt-
|
|
23
|
+
model: 'openai/gpt-6-luna',
|
|
24
24
|
memory: new Memory({
|
|
25
25
|
options: {
|
|
26
26
|
observationalMemory: true,
|
|
@@ -45,7 +45,7 @@ const memory = new Memory({
|
|
|
45
45
|
}),
|
|
46
46
|
options: {
|
|
47
47
|
observationalMemory: {
|
|
48
|
-
model: 'openai/gpt-
|
|
48
|
+
model: 'openai/gpt-6-luna',
|
|
49
49
|
},
|
|
50
50
|
},
|
|
51
51
|
})
|
|
@@ -54,7 +54,7 @@ const agent = new Agent({
|
|
|
54
54
|
id: 'memory-agent',
|
|
55
55
|
name: 'Memory Agent',
|
|
56
56
|
instructions: 'You are a helpful assistant.',
|
|
57
|
-
model: 'openai/gpt-
|
|
57
|
+
model: 'openai/gpt-6-luna',
|
|
58
58
|
memory,
|
|
59
59
|
})
|
|
60
60
|
|
|
@@ -124,7 +124,7 @@ export const agent = new Agent({
|
|
|
124
124
|
id: 'my-agent',
|
|
125
125
|
name: 'my-agent',
|
|
126
126
|
instructions: 'You are a helpful assistant.',
|
|
127
|
-
model: 'openai/gpt-
|
|
127
|
+
model: 'openai/gpt-6-luna',
|
|
128
128
|
memory: new Memory({
|
|
129
129
|
options: {
|
|
130
130
|
observationalMemory: {
|
|
@@ -149,6 +149,8 @@ OM can activate buffered observations before the token threshold is reached. Thi
|
|
|
149
149
|
Top-level early activation settings apply to observations by default:
|
|
150
150
|
|
|
151
151
|
```typescript
|
|
152
|
+
import { Memory } from '@mastra/memory'
|
|
153
|
+
|
|
152
154
|
const memory = new Memory({
|
|
153
155
|
options: {
|
|
154
156
|
observationalMemory: {
|
|
@@ -163,6 +165,8 @@ const memory = new Memory({
|
|
|
163
165
|
Use nested `observation` and `reflection` settings for per-phase control. Reflection early activation is opt-in, so top-level settings affect only observations.
|
|
164
166
|
|
|
165
167
|
```typescript
|
|
168
|
+
import { Memory } from '@mastra/memory'
|
|
169
|
+
|
|
166
170
|
const memory = new Memory({
|
|
167
171
|
options: {
|
|
168
172
|
observationalMemory: {
|
|
@@ -187,10 +191,12 @@ In this example, the top-level idle setting is disabled for observations, while
|
|
|
187
191
|
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
192
|
|
|
189
193
|
```typescript
|
|
194
|
+
import { Memory } from '@mastra/memory'
|
|
195
|
+
|
|
190
196
|
const memory = new Memory({
|
|
191
197
|
options: {
|
|
192
198
|
observationalMemory: {
|
|
193
|
-
model: 'openai/gpt-
|
|
199
|
+
model: 'openai/gpt-6-luna',
|
|
194
200
|
observation: {
|
|
195
201
|
bufferOnIdle: true,
|
|
196
202
|
},
|
|
@@ -203,12 +209,14 @@ const memory = new Memory({
|
|
|
203
209
|
|
|
204
210
|
### Retries and failure policy
|
|
205
211
|
|
|
206
|
-
Observer and Reflector model calls are retried on transient provider errors,
|
|
212
|
+
Observer and Reflector model calls are retried on transient provider errors. By default, a synchronous observation or reflection that still fails aborts the turn. Each stage is controlled independently by:
|
|
207
213
|
|
|
208
214
|
- `maxRetries`: retries after the initial model call (default `8`).
|
|
209
215
|
- `failurePolicy`: what happens once retries are exhausted, either `'abort'` (default) or `'continue'`.
|
|
210
216
|
|
|
211
217
|
```typescript
|
|
218
|
+
import { Memory } from '@mastra/memory'
|
|
219
|
+
|
|
212
220
|
const memory = new Memory({
|
|
213
221
|
options: {
|
|
214
222
|
observationalMemory: {
|
|
@@ -231,7 +239,9 @@ With `failurePolicy: 'continue'`, Mastra retries as configured, reports the fail
|
|
|
231
239
|
|
|
232
240
|
A provider outage usually takes out both stages, so set the policy on both if you want the turn to survive one.
|
|
233
241
|
|
|
234
|
-
This policy applies only to Observer and Reflector model and provider failures
|
|
242
|
+
This policy applies only to Observer and Reflector model and provider failures when observation or reflection runs synchronously: at `blockAfter`, when async buffering is disabled, and in resource-scoped observation. In those paths, persistence, indexing, transform, locking, invariant, and explicit abort failures remain fatal. It doesn't prevent the underlying provider or network error, change `blockAfter`, or change attachment handling.
|
|
243
|
+
|
|
244
|
+
Background (async buffered) observation and reflection failures never stop the turn, whatever the policy. They're reported as `om_buffering_failed`, and the failed input stays pending. If it keeps growing, it reaches `blockAfter`, where synchronous observation applies `failurePolicy`.
|
|
235
245
|
|
|
236
246
|
> **Warning:** `'continue'` has no backstop for a sustained outage. Unobserved messages stay pending and keep accruing in the main agent's context. A long outage moves the failure from the memory layer to the model's context limit.
|
|
237
247
|
|
|
@@ -276,7 +286,7 @@ import { z } from 'zod'
|
|
|
276
286
|
const memory = new Memory({
|
|
277
287
|
options: {
|
|
278
288
|
observationalMemory: {
|
|
279
|
-
model: 'openai/gpt-
|
|
289
|
+
model: 'openai/gpt-6-luna',
|
|
280
290
|
observation: {
|
|
281
291
|
extract: [
|
|
282
292
|
new Extractor({
|
|
@@ -298,7 +308,7 @@ export const agent = new Agent({
|
|
|
298
308
|
id: 'assistant',
|
|
299
309
|
name: 'assistant',
|
|
300
310
|
instructions: 'You are a helpful assistant.',
|
|
301
|
-
model: 'openai/gpt-
|
|
311
|
+
model: 'openai/gpt-6-luna',
|
|
302
312
|
memory,
|
|
303
313
|
})
|
|
304
314
|
```
|
|
@@ -389,6 +399,8 @@ This setting adds `WorkingMemoryExtractor`, defaults `workingMemory.agentManaged
|
|
|
389
399
|
Use `onExtracted` to normalize or react to custom extracted values before they're persisted:
|
|
390
400
|
|
|
391
401
|
```typescript
|
|
402
|
+
import { z } from 'zod'
|
|
403
|
+
|
|
392
404
|
new Extractor({
|
|
393
405
|
name: 'Project status',
|
|
394
406
|
instructions: 'Extract the current project status.',
|
|
@@ -412,7 +424,7 @@ new Agent({
|
|
|
412
424
|
id: 'assistant',
|
|
413
425
|
name: 'assistant',
|
|
414
426
|
instructions: 'You are a helpful assistant.',
|
|
415
|
-
model: 'openai/gpt-
|
|
427
|
+
model: 'openai/gpt-6-luna',
|
|
416
428
|
memory: new Memory({
|
|
417
429
|
options: {
|
|
418
430
|
observationalMemory: {
|
|
@@ -592,7 +604,7 @@ Use `autoModels` to change the model picked for a provider, and `resolveModel` t
|
|
|
592
604
|
const memory = new Memory({
|
|
593
605
|
options: {
|
|
594
606
|
observationalMemory: {
|
|
595
|
-
autoModels: { openai: 'openai/gpt-
|
|
607
|
+
autoModels: { openai: 'openai/gpt-6-luna' },
|
|
596
608
|
resolveModel: (modelId, { requestContext }) => createRoutedModel(modelId, requestContext),
|
|
597
609
|
},
|
|
598
610
|
},
|
|
@@ -603,7 +615,7 @@ const memory = new Memory({
|
|
|
603
615
|
|
|
604
616
|
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.
|
|
605
617
|
|
|
606
|
-
To pin a model instead, set a concrete model ID. We've also successfully tested `openai/gpt-
|
|
618
|
+
To pin a model instead, set a concrete model ID. We've also successfully tested `openai/gpt-6-luna`, `anthropic/claude-haiku-5-5`, `deepseek/deepseek-reasoner`, `deepseek/deepseek-v4-pro`, `deepseek/deepseek-v4-flash`, `xai/grok-4-1-fast`, `qwen3`, and `glm-4.7`.
|
|
607
619
|
|
|
608
620
|
```typescript
|
|
609
621
|
const memory = new Memory({
|
|
@@ -639,7 +651,7 @@ const memory = new Memory({
|
|
|
639
651
|
// Faster, cheaper models for smaller inputs; stronger models for larger contexts
|
|
640
652
|
5_000: 'openrouter/mistralai/ministral-8b-2512',
|
|
641
653
|
20_000: 'openrouter/mistralai/mistral-small-2603',
|
|
642
|
-
40_000: 'openai/gpt-
|
|
654
|
+
40_000: 'openai/gpt-6-luna',
|
|
643
655
|
1_000_000: 'google/gemini-3.1-flash-lite-preview',
|
|
644
656
|
},
|
|
645
657
|
}),
|
|
@@ -647,7 +659,7 @@ const memory = new Memory({
|
|
|
647
659
|
reflection: {
|
|
648
660
|
model: new ModelByInputTokens({
|
|
649
661
|
upTo: {
|
|
650
|
-
20_000: 'openai/gpt-
|
|
662
|
+
20_000: 'openai/gpt-6-luna',
|
|
651
663
|
100_000: 'google/gemini-2.5-flash',
|
|
652
664
|
},
|
|
653
665
|
}),
|
|
@@ -926,7 +938,7 @@ OM exposes two kinds of config-level hooks on `observationalMemory.hooks`:
|
|
|
926
938
|
const memory = new Memory({
|
|
927
939
|
options: {
|
|
928
940
|
observationalMemory: {
|
|
929
|
-
model: 'google/gemini-
|
|
941
|
+
model: 'google/gemini-3.8-flash',
|
|
930
942
|
hooks: {
|
|
931
943
|
// Drop or redact messages before the Observer sees them.
|
|
932
944
|
beforeObservation: ({ messages }) => ({
|
|
@@ -966,7 +978,7 @@ import { skillResultRedactor } from '@mastra/memory/hooks'
|
|
|
966
978
|
const memory = new Memory({
|
|
967
979
|
options: {
|
|
968
980
|
observationalMemory: {
|
|
969
|
-
model: 'google/gemini-
|
|
981
|
+
model: 'google/gemini-3.8-flash',
|
|
970
982
|
hooks: {
|
|
971
983
|
beforeObservation: skillResultRedactor(),
|
|
972
984
|
},
|
|
@@ -4,7 +4,11 @@
|
|
|
4
4
|
|
|
5
5
|
# Semantic recall
|
|
6
6
|
|
|
7
|
-
|
|
7
|
+
Semantic recall is a built-in form of Retrieval-Augmented Generation (RAG) for agent memory. When a user sends a message, Mastra searches earlier messages for ones with a similar meaning and adds the most relevant ones to the agent's context.
|
|
8
|
+
|
|
9
|
+
Matching on meaning matters because people often remember the idea behind something, not the exact words they used. A user might ask "What did we decide about the refund?" after originally writing "Let's give them their money back." A keyword search misses that connection, but semantic recall finds it.
|
|
10
|
+
|
|
11
|
+
Use semantic recall when your agent needs details from earlier in a long conversation, or from a user's other conversations, that are no longer in [recent message history](https://mastra.ai/docs/memory/message-history).
|
|
8
12
|
|
|
9
13
|
> **📹 Watch:** Watch [Mastra semantic recall](https://www.youtube.com/watch?v=UVZtK8cK8xQ\&pp=ygUVbWFzdHJhIHdvcmtpbmcgbWVtb3J5) to see how agents retrieve relevant messages from past conversations.
|
|
10
14
|
|
|
@@ -34,7 +38,7 @@ const agent = new Agent({
|
|
|
34
38
|
id: 'support-agent',
|
|
35
39
|
name: 'SupportAgent',
|
|
36
40
|
instructions: 'You are a helpful support agent.',
|
|
37
|
-
model: 'openai/gpt-
|
|
41
|
+
model: 'openai/gpt-6.1-sol',
|
|
38
42
|
memory: new Memory({
|
|
39
43
|
storage: new LibSQLStore({
|
|
40
44
|
id: 'agent-storage',
|
|
@@ -64,7 +68,7 @@ const agent = new Agent({
|
|
|
64
68
|
id: 'support-agent',
|
|
65
69
|
name: 'SupportAgent',
|
|
66
70
|
instructions: 'You are a helpful support agent.',
|
|
67
|
-
model: 'openai/gpt-
|
|
71
|
+
model: 'openai/gpt-6.1-sol',
|
|
68
72
|
memory: new Memory({
|
|
69
73
|
storage: new MongoDBStore({
|
|
70
74
|
id: 'agent-storage',
|
|
@@ -403,6 +407,28 @@ Memory uses a single embedder for both storing and recalling messages, so pick o
|
|
|
403
407
|
|
|
404
408
|
Multilingual E5 produces 1024-dimensional vectors. Your vector index must be created with matching dimensions, and E5 vectors can't be mixed with vectors from another embedder in the same index.
|
|
405
409
|
|
|
410
|
+
FastEmbed models embed at most 512 tokens per input (roughly 2,000 to 2,500 characters of English text). Longer inputs are truncated, so text past the limit doesn't affect the embedding and can't be found by semantic recall. The AI SDK v3 FastEmbed models return a warning when this happens. The legacy v1 and v2 models don't. If you embed long documents with FastEmbed, chunk them to fit the window, for example with `maxSize: 1500` in `MDocument.chunk()`.
|
|
411
|
+
|
|
412
|
+
### Setting the embedding dimension
|
|
413
|
+
|
|
414
|
+
To name the vector index, Memory needs the embedder's output dimension. By default it finds the dimension by embedding a short probe string the first time semantic recall is set up, once per `Memory` instance. If you already know the dimension, set `embeddingDimension`. Memory then skips the probe, so startup makes no embedding call and doesn't depend on the embedding provider being reachable:
|
|
415
|
+
|
|
416
|
+
```ts
|
|
417
|
+
import { Memory } from '@mastra/memory'
|
|
418
|
+
|
|
419
|
+
const memory = new Memory({
|
|
420
|
+
embedder: 'openai/text-embedding-3-small',
|
|
421
|
+
embeddingDimension: 1536,
|
|
422
|
+
options: {
|
|
423
|
+
semanticRecall: true,
|
|
424
|
+
},
|
|
425
|
+
})
|
|
426
|
+
```
|
|
427
|
+
|
|
428
|
+
The index name is the same whether the dimension is configured or probed, so existing indexes keep working.
|
|
429
|
+
|
|
430
|
+
The value must match the vectors the embedder returns. Memory compares it with the first real embedding, and on a mismatch it throws a `MASTRA_MEMORY_EMBEDDING_DIMENSION_MISMATCH` error naming both values before creating or querying any index. Update `embeddingDimension` whenever you change the embedding model or its output dimension.
|
|
431
|
+
|
|
406
432
|
## PostgreSQL index optimization
|
|
407
433
|
|
|
408
434
|
When using PostgreSQL as your vector store, you can optimize semantic recall performance by configuring the vector index. This is particularly important for large-scale deployments with thousands of messages.
|
|
@@ -34,7 +34,7 @@ const agent = new Agent({
|
|
|
34
34
|
id: 'personal-assistant',
|
|
35
35
|
name: 'PersonalAssistant',
|
|
36
36
|
instructions: 'You are a helpful personal assistant.',
|
|
37
|
-
model: 'openai/gpt-
|
|
37
|
+
model: 'openai/gpt-6.1-sol',
|
|
38
38
|
memory: new Memory({
|
|
39
39
|
options: {
|
|
40
40
|
workingMemory: {
|
|
@@ -217,7 +217,7 @@ const paragraphMemory = new Memory({
|
|
|
217
217
|
|
|
218
218
|
Working memory can also be defined using a structured schema instead of a Markdown template. A [Standard JSON Schema](https://standardschema.dev/json-schema) ([Zod](https://zod.dev/), [Valibot](https://valibot.dev/), [ArkType](https://arktype.io/), etc.). When using a schema, the agent will see and update working memory as a JSON object matching your schema.
|
|
219
219
|
|
|
220
|
-
|
|
220
|
+
You can specify either `template` or `schema`, but not both. If you omit both, Mastra uses the default working memory template.
|
|
221
221
|
|
|
222
222
|
### Example: Schema-Based Working Memory
|
|
223
223
|
|
|
@@ -418,7 +418,7 @@ const response = await agent.generate('What do you know about me?', {
|
|
|
418
418
|
|
|
419
419
|
## Opt in to state signals (experimental)
|
|
420
420
|
|
|
421
|
-
By default, working memory reaches the model as part of the system message. You can opt into delivering it as a [state signal](https://mastra.ai/docs/
|
|
421
|
+
By default, working memory reaches the model as part of the system message. You can opt into delivering it as a [state signal](https://mastra.ai/docs/signals/state-signals) instead by setting `useStateSignals: true`:
|
|
422
422
|
|
|
423
423
|
```typescript
|
|
424
424
|
const memory = new Memory({
|
|
@@ -146,7 +146,7 @@ export const supportAgent = new Agent({
|
|
|
146
146
|
id: 'support-agent',
|
|
147
147
|
name: 'Support agent',
|
|
148
148
|
instructions: 'Answer customer support questions.',
|
|
149
|
-
model: 'openai/gpt-
|
|
149
|
+
model: 'openai/gpt-6.1-sol',
|
|
150
150
|
memory: new Memory({
|
|
151
151
|
storage: new PostgresStore({
|
|
152
152
|
id: 'support-agent-storage',
|
|
@@ -228,7 +228,7 @@ export const oracleAgent = new Agent({
|
|
|
228
228
|
id: 'oracle-agent',
|
|
229
229
|
name: 'Oracle Agent',
|
|
230
230
|
instructions: 'You are an assistant with persistent OracleDB-backed memory.',
|
|
231
|
-
model: 'openai/gpt-
|
|
231
|
+
model: 'openai/gpt-6.1-sol',
|
|
232
232
|
memory: new Memory({ storage }),
|
|
233
233
|
})
|
|
234
234
|
```
|
|
@@ -36,7 +36,7 @@ const results = await store.query({
|
|
|
36
36
|
|
|
37
37
|
### Array Operators
|
|
38
38
|
|
|
39
|
-
`$in`Matches any value in array{ category: { $in: \["A", "B"] } }Supported by: All except Couchbase`$nin`Matches none of the values{ status: { $nin: \["deleted", "archived"] } }Supported by: All except Couchbase`$all`Matches arrays containing all elements{ tags: { $all: \["urgent", "high"] } }Supported by: Astra, Pinecone, Upstash, MongoDB, OracleDB`$elemMatch`Matches array elements meeting criteria{ scores: { $elemMatch: { $gt: 80 } } }Supported by: libSQL, PgVector, MongoDB, OracleDB
|
|
39
|
+
`$in`Matches any value in array{ category: { $in: \["A", "B"] } }Supported by: All except Couchbase`$nin`Matches none of the values{ status: { $nin: \["deleted", "archived"] } }Supported by: All except Couchbase`$all`Matches arrays containing all elements{ tags: { $all: \["urgent", "high"] } }Supported by: Astra, Pinecone, Qdrant, Upstash, MongoDB, OracleDB`$elemMatch`Matches array elements meeting criteria{ scores: { $elemMatch: { $gt: 80 } } }Supported by: libSQL, PgVector, MongoDB, OracleDB
|
|
40
40
|
|
|
41
41
|
### Logical Operators
|
|
42
42
|
|
|
@@ -382,11 +382,12 @@ Vector store prompts define query patterns and filtering capabilities for each v
|
|
|
382
382
|
|
|
383
383
|
```ts
|
|
384
384
|
import { MONGODB_PROMPT } from '@mastra/mongodb'
|
|
385
|
+
import { Agent } from '@mastra/core/agent'
|
|
385
386
|
|
|
386
387
|
export const ragAgent = new Agent({
|
|
387
388
|
id: 'rag-agent',
|
|
388
389
|
name: 'RAG Agent',
|
|
389
|
-
model: 'openai/gpt-
|
|
390
|
+
model: 'openai/gpt-6.1-sol',
|
|
390
391
|
instructions: `
|
|
391
392
|
Process queries using the provided context. Structure responses to be concise and relevant.
|
|
392
393
|
${MONGODB_PROMPT}
|
|
@@ -403,7 +404,7 @@ import { PGVECTOR_PROMPT } from '@mastra/pg'
|
|
|
403
404
|
export const ragAgent = new Agent({
|
|
404
405
|
id: 'rag-agent',
|
|
405
406
|
name: 'RAG Agent',
|
|
406
|
-
model: 'openai/gpt-
|
|
407
|
+
model: 'openai/gpt-6.1-sol',
|
|
407
408
|
instructions: `
|
|
408
409
|
Process queries using the provided context. Structure responses to be concise and relevant.
|
|
409
410
|
${PGVECTOR_PROMPT}
|
|
@@ -416,11 +417,12 @@ export const ragAgent = new Agent({
|
|
|
416
417
|
|
|
417
418
|
```ts
|
|
418
419
|
import { PINECONE_PROMPT } from '@mastra/pinecone'
|
|
420
|
+
import { Agent } from '@mastra/core/agent'
|
|
419
421
|
|
|
420
422
|
export const ragAgent = new Agent({
|
|
421
423
|
id: 'rag-agent',
|
|
422
424
|
name: 'RAG Agent',
|
|
423
|
-
model: 'openai/gpt-
|
|
425
|
+
model: 'openai/gpt-6.1-sol',
|
|
424
426
|
instructions: `
|
|
425
427
|
Process queries using the provided context. Structure responses to be concise and relevant.
|
|
426
428
|
${PINECONE_PROMPT}
|
|
@@ -433,11 +435,12 @@ export const ragAgent = new Agent({
|
|
|
433
435
|
|
|
434
436
|
```ts
|
|
435
437
|
import { QDRANT_PROMPT } from '@mastra/qdrant'
|
|
438
|
+
import { Agent } from '@mastra/core/agent'
|
|
436
439
|
|
|
437
440
|
export const ragAgent = new Agent({
|
|
438
441
|
id: 'rag-agent',
|
|
439
442
|
name: 'RAG Agent',
|
|
440
|
-
model: 'openai/gpt-
|
|
443
|
+
model: 'openai/gpt-6.1-sol',
|
|
441
444
|
instructions: `
|
|
442
445
|
Process queries using the provided context. Structure responses to be concise and relevant.
|
|
443
446
|
${QDRANT_PROMPT}
|
|
@@ -450,11 +453,12 @@ export const ragAgent = new Agent({
|
|
|
450
453
|
|
|
451
454
|
```ts
|
|
452
455
|
import { CHROMA_PROMPT } from '@mastra/chroma'
|
|
456
|
+
import { Agent } from '@mastra/core/agent'
|
|
453
457
|
|
|
454
458
|
export const ragAgent = new Agent({
|
|
455
459
|
id: 'rag-agent',
|
|
456
460
|
name: 'RAG Agent',
|
|
457
|
-
model: 'openai/gpt-
|
|
461
|
+
model: 'openai/gpt-6.1-sol',
|
|
458
462
|
instructions: `
|
|
459
463
|
Process queries using the provided context. Structure responses to be concise and relevant.
|
|
460
464
|
${CHROMA_PROMPT}
|
|
@@ -467,11 +471,12 @@ export const ragAgent = new Agent({
|
|
|
467
471
|
|
|
468
472
|
```ts
|
|
469
473
|
import { ASTRA_PROMPT } from '@mastra/astra'
|
|
474
|
+
import { Agent } from '@mastra/core/agent'
|
|
470
475
|
|
|
471
476
|
export const ragAgent = new Agent({
|
|
472
477
|
id: 'rag-agent',
|
|
473
478
|
name: 'RAG Agent',
|
|
474
|
-
model: 'openai/gpt-
|
|
479
|
+
model: 'openai/gpt-6.1-sol',
|
|
475
480
|
instructions: `
|
|
476
481
|
Process queries using the provided context. Structure responses to be concise and relevant.
|
|
477
482
|
${ASTRA_PROMPT}
|
|
@@ -484,11 +489,12 @@ export const ragAgent = new Agent({
|
|
|
484
489
|
|
|
485
490
|
```ts
|
|
486
491
|
import { LIBSQL_PROMPT } from '@mastra/libsql'
|
|
492
|
+
import { Agent } from '@mastra/core/agent'
|
|
487
493
|
|
|
488
494
|
export const ragAgent = new Agent({
|
|
489
495
|
id: 'rag-agent',
|
|
490
496
|
name: 'RAG Agent',
|
|
491
|
-
model: 'openai/gpt-
|
|
497
|
+
model: 'openai/gpt-6.1-sol',
|
|
492
498
|
instructions: `
|
|
493
499
|
Process queries using the provided context. Structure responses to be concise and relevant.
|
|
494
500
|
${LIBSQL_PROMPT}
|
|
@@ -501,11 +507,12 @@ export const ragAgent = new Agent({
|
|
|
501
507
|
|
|
502
508
|
```ts
|
|
503
509
|
import { UPSTASH_PROMPT } from '@mastra/upstash'
|
|
510
|
+
import { Agent } from '@mastra/core/agent'
|
|
504
511
|
|
|
505
512
|
export const ragAgent = new Agent({
|
|
506
513
|
id: 'rag-agent',
|
|
507
514
|
name: 'RAG Agent',
|
|
508
|
-
model: 'openai/gpt-
|
|
515
|
+
model: 'openai/gpt-6.1-sol',
|
|
509
516
|
instructions: `
|
|
510
517
|
Process queries using the provided context. Structure responses to be concise and relevant.
|
|
511
518
|
${UPSTASH_PROMPT}
|
|
@@ -518,11 +525,12 @@ export const ragAgent = new Agent({
|
|
|
518
525
|
|
|
519
526
|
```ts
|
|
520
527
|
import { VECTORIZE_PROMPT } from '@mastra/vectorize'
|
|
528
|
+
import { Agent } from '@mastra/core/agent'
|
|
521
529
|
|
|
522
530
|
export const ragAgent = new Agent({
|
|
523
531
|
id: 'rag-agent',
|
|
524
532
|
name: 'RAG Agent',
|
|
525
|
-
model: 'openai/gpt-
|
|
533
|
+
model: 'openai/gpt-6.1-sol',
|
|
526
534
|
instructions: `
|
|
527
535
|
Process queries using the provided context. Structure responses to be concise and relevant.
|
|
528
536
|
${VECTORIZE_PROMPT}
|
|
@@ -535,11 +543,12 @@ export const ragAgent = new Agent({
|
|
|
535
543
|
|
|
536
544
|
```ts
|
|
537
545
|
import { OPENSEARCH_PROMPT } from '@mastra/opensearch'
|
|
546
|
+
import { Agent } from '@mastra/core/agent'
|
|
538
547
|
|
|
539
548
|
export const ragAgent = new Agent({
|
|
540
549
|
id: 'rag-agent',
|
|
541
550
|
name: 'RAG Agent',
|
|
542
|
-
model: 'openai/gpt-
|
|
551
|
+
model: 'openai/gpt-6.1-sol',
|
|
543
552
|
instructions: `
|
|
544
553
|
Process queries using the provided context. Structure responses to be concise and relevant.
|
|
545
554
|
${OPENSEARCH_PROMPT}
|
|
@@ -552,11 +561,12 @@ export const ragAgent = new Agent({
|
|
|
552
561
|
|
|
553
562
|
```ts
|
|
554
563
|
import { ORACLEDB_PROMPT } from '@mastra/oracledb'
|
|
564
|
+
import { Agent } from '@mastra/core/agent'
|
|
555
565
|
|
|
556
566
|
export const ragAgent = new Agent({
|
|
557
567
|
id: 'rag-agent',
|
|
558
568
|
name: 'RAG Agent',
|
|
559
|
-
model: 'openai/gpt-
|
|
569
|
+
model: 'openai/gpt-6.1-sol',
|
|
560
570
|
instructions: `
|
|
561
571
|
Process queries using the provided context. Structure responses to be concise and relevant.
|
|
562
572
|
${ORACLEDB_PROMPT}
|
|
@@ -569,11 +579,12 @@ export const ragAgent = new Agent({
|
|
|
569
579
|
|
|
570
580
|
```ts
|
|
571
581
|
import { S3VECTORS_PROMPT } from '@mastra/s3vectors'
|
|
582
|
+
import { Agent } from '@mastra/core/agent'
|
|
572
583
|
|
|
573
584
|
export const ragAgent = new Agent({
|
|
574
585
|
id: 'rag-agent',
|
|
575
586
|
name: 'RAG Agent',
|
|
576
|
-
model: 'openai/gpt-
|
|
587
|
+
model: 'openai/gpt-6.1-sol',
|
|
577
588
|
instructions: `
|
|
578
589
|
Process queries using the provided context. Structure responses to be concise and relevant.
|
|
579
590
|
${S3VECTORS_PROMPT}
|
|
@@ -605,7 +616,7 @@ const initialResults = await pgVector.query({
|
|
|
605
616
|
// Create a relevance scorer
|
|
606
617
|
const relevanceProvider = new MastraAgentRelevanceScorer(
|
|
607
618
|
'relevance-scorer',
|
|
608
|
-
'openai/gpt-
|
|
619
|
+
'openai/gpt-6.1-sol',
|
|
609
620
|
)
|
|
610
621
|
|
|
611
622
|
// Re-rank the results
|
|
@@ -294,7 +294,7 @@ const storage = new MongoDBStore({
|
|
|
294
294
|
|
|
295
295
|
## Reclaiming disk
|
|
296
296
|
|
|
297
|
-
`prune()` deletes rows but doesn't shrink the database file. On SQLite/libSQL the freed pages go on a freelist
|
|
297
|
+
`prune()` deletes rows but doesn't shrink the database file. On SQLite/libSQL the freed pages go on a freelist for reuse by future writes. Reusing these pages prevents unbounded file growth for most users.
|
|
298
298
|
|
|
299
299
|
Handing that free space back to the OS is a separate concern that Mastra doesn't manage. If you specifically need to shrink the file, run the underlying database's compaction (for example `VACUUM` on self-hosted libSQL) yourself in a maintenance window. A full `VACUUM` locks the file and needs roughly twice the file size in free disk. On PostgreSQL, autovacuum reclaims dead tuples for reuse automatically. A manual `VACUUM FULL` is only needed if you must return disk to the OS.
|
|
300
300
|
|
|
@@ -283,7 +283,7 @@ const vectorQueryTool = createVectorQueryTool({
|
|
|
283
283
|
export const ragAgent = new Agent({
|
|
284
284
|
id: 'oracle-rag-agent',
|
|
285
285
|
name: 'Oracle RAG Agent',
|
|
286
|
-
model: 'openai/gpt-
|
|
286
|
+
model: 'openai/gpt-6.1-sol',
|
|
287
287
|
instructions: `
|
|
288
288
|
Use the retrieval tool when you need source context.
|
|
289
289
|
Available metadata fields: resource_id, thread_id, source, category, tags.
|
|
@@ -330,7 +330,7 @@ export const oracleAgent = new Agent({
|
|
|
330
330
|
id: 'oracle-agent',
|
|
331
331
|
name: 'Oracle Agent',
|
|
332
332
|
instructions: 'You are an assistant with OracleDB-backed memory and semantic recall.',
|
|
333
|
-
model: 'openai/gpt-
|
|
333
|
+
model: 'openai/gpt-6.1-sol',
|
|
334
334
|
memory: new Memory({
|
|
335
335
|
storage,
|
|
336
336
|
vector,
|