From db21791925b8d396b7bcea58402a881e076fd78e Mon Sep 17 00:00:00 2001 From: Jamie Lee Nichols <10267569+CodingButter@users.noreply.github.com> Date: Mon, 16 Nov 2026 12:40:49 -0500 Subject: [PATCH 1/3] fix(memory): save turns when observational memory is enabled only per call The OM engine is built from the Memory instance config, so a call-only observationalMemory opt-in had no engine, yet memory processors and the durable finalize gate still treated OM as active and skipped message history. The regular agent stored nothing and durable stored only the user message. Resolve the merged config to OM-off in that case. Co-Authored-By: mastracode <284800079+mastra-platform[bot]@users.noreply.github.com> --- .changeset/call-only-om-saves.md | 5 ++ .../src/durable-agent-call-only-om.test.ts | 72 +++++++++++++++++++ packages/memory/src/index.ts | 14 ++++ 3 files changed, 91 insertions(+) create mode 100644 .changeset/call-only-om-saves.md create mode 100644 packages/memory/integration-tests/src/durable-agent-call-only-om.test.ts diff --git a/.changeset/call-only-om-saves.md b/.changeset/call-only-om-saves.md new file mode 100644 index 00000000000..e97ca31fd1d --- /dev/null +++ b/.changeset/call-only-om-saves.md @@ -0,0 +1,5 @@ +--- +'@mastra/memory': patch +--- + +Fixed agent turns being lost when `observationalMemory` is enabled only in a call's `memory.options` and not on the `Memory` instance. Observational memory runs only when it is configured on the instance, so a call-only setting now falls back to normal message history instead of skipping the save. Before, the regular agent saved nothing for the turn and durable agents saved only the user message. diff --git a/packages/memory/integration-tests/src/durable-agent-call-only-om.test.ts b/packages/memory/integration-tests/src/durable-agent-call-only-om.test.ts new file mode 100644 index 00000000000..87895b91ee3 --- /dev/null +++ b/packages/memory/integration-tests/src/durable-agent-call-only-om.test.ts @@ -0,0 +1,72 @@ +/** + * Observational memory turned on only in the call's `memory.options` (not on `new Memory`). + * + * The OM engine is built from the Memory instance config, so a call-only OM setting has no + * engine to save the turn. Every engine must still store the user message and the reply. + */ +import { randomUUID } from 'node:crypto'; +import { MockLanguageModelV2, convertArrayToReadableStream } from '@internal/ai-sdk-v5/test'; +import { Agent } from '@mastra/core/agent'; +import { createDurableAgent } from '@mastra/core/agent/durable'; +import { Mastra } from '@mastra/core/mastra'; +import { LibSQLStore } from '@mastra/libsql'; +import { Memory } from '@mastra/memory'; +import { describe, expect, it } from 'vitest'; +import { persistedMessages, streamTurn } from './durable-harness-helpers'; + +const REPLY = 'Lisbon is sunny.'; + +function mockModel() { + return new MockLanguageModelV2({ + doStream: async () => ({ + rawCall: { rawPrompt: null, rawSettings: {} }, + warnings: [], + stream: convertArrayToReadableStream([ + { type: 'stream-start', warnings: [] }, + { type: 'response-metadata', id: 'r1', modelId: 'mock', timestamp: new Date(0) }, + { type: 'text-start', id: 't1' }, + { type: 'text-delta', id: 't1', delta: REPLY }, + { type: 'text-end', id: 't1' }, + { type: 'finish', finishReason: 'stop', usage: { inputTokens: 5, outputTokens: 5, totalTokens: 10 } }, + ]), + }), + }); +} + +const omOptions = { observationalMemory: { enabled: true, model: mockModel(), scope: 'thread' } } as any; + +const CASES = { + 'regular Agent, OM on call only': { engine: 'plain', instanceOM: false, callOM: true }, + 'DurableAgent, OM on Memory and call': { engine: 'durable', instanceOM: true, callOM: true }, + 'DurableAgent, OM on call only': { engine: 'durable', instanceOM: false, callOM: true }, + 'DurableAgent, OM on Memory only': { engine: 'durable', instanceOM: true, callOM: false }, +} as const; + +describe('call-only observational memory', () => { + it.each(Object.entries(CASES))('%s stores the user message and the reply', async (_name, c) => { + const storage = new LibSQLStore({ id: randomUUID(), url: ':memory:' }); + const memory = new Memory({ + storage, + options: { + lastMessages: 10, + semanticRecall: false, + generateTitle: false, + ...(c.instanceOM ? omOptions : {}), + } as any, + }); + const agent = new Agent({ id: `a-${randomUUID()}`, name: 'a', model: mockModel(), memory, instructions: 'hi' }); + const runner = c.engine === 'plain' ? agent : createDurableAgent({ agent }); + const mastra = new Mastra({ agents: { a: runner as any }, storage, logger: false }); + + const thread = randomUUID(); + const resource = randomUUID(); + const run = await streamTurn(runner, c.engine, 'Weather in Lisbon?', { + memory: { thread, resource, ...(c.callOM ? { options: omOptions } : {}) }, + }); + await (mastra as any).stopWorkers?.(); + expect(run.threw).toBeNull(); + + const messages = await persistedMessages(memory, thread, resource); + expect(messages.map(m => m.role)).toEqual(['user', 'assistant']); + }); +}); diff --git a/packages/memory/src/index.ts b/packages/memory/src/index.ts index d68ca42b37c..5a868703fc8 100644 --- a/packages/memory/src/index.ts +++ b/packages/memory/src/index.ts @@ -541,8 +541,22 @@ export class Memory extends MastraMemory { } } + // False while the base constructor merges the instance options into threadConfig. + private readonly instanceConfigured = true; + public override getMergedThreadConfig(config?: MemoryConfigInternal): MemoryConfigInternal { const merged = super.getMergedThreadConfig(config); + // The OM engine is built from the instance config only (_initOMEngine), so a per-call + // opt-in on an instance without OM has nothing to observe or save the turn. Treat it as off + // so message history keeps saving instead of every engine skipping persistence. + if ( + this.instanceConfigured && + !normalizeObservationalMemoryConfig(this.threadConfig.observationalMemory) && + merged.observationalMemory !== undefined && + merged.observationalMemory !== false + ) { + return this.applyManagedWorkingMemoryDefaults({ ...merged, observationalMemory: false }); + } return this.applyManagedWorkingMemoryDefaults(merged); } From df97b75d7e4ec72fbad2cd631adb3ba77511f91b Mon Sep 17 00:00:00 2001 From: Jamie Lee Nichols <10267569+CodingButter@users.noreply.github.com> Date: Mon, 16 Nov 2026 13:09:09 -0500 Subject: [PATCH 2/3] fix(memory,core): ignore call-only OM opt-ins with a warning and keep durable saving Round 2: normalized opt-in predicate (opt-outs untouched), one-time warning, durable flag requires the merged config to keep OM on so call-only runs flush and title in finalize, JSDoc that OM must be configured on the instance, and tests asserting OM artifacts for instance-level controls. Co-Authored-By: mastracode <284800079+mastra-platform[bot]@users.noreply.github.com> --- .changeset/call-only-om-saves.md | 2 +- .changeset/durable-om-merged-config.md | 5 ++ .../core/src/agent/durable/preparation.ts | 9 +- packages/core/src/memory/types.ts | 4 + .../src/durable-agent-call-only-om.test.ts | 83 ++++++++++++++----- .../call-only-observational-memory.test.ts | 50 +++++++++++ packages/memory/src/index.ts | 17 ++-- 7 files changed, 143 insertions(+), 27 deletions(-) create mode 100644 .changeset/durable-om-merged-config.md create mode 100644 packages/memory/src/call-only-observational-memory.test.ts diff --git a/.changeset/call-only-om-saves.md b/.changeset/call-only-om-saves.md index e97ca31fd1d..0a9c57b2cad 100644 --- a/.changeset/call-only-om-saves.md +++ b/.changeset/call-only-om-saves.md @@ -2,4 +2,4 @@ '@mastra/memory': patch --- -Fixed agent turns being lost when `observationalMemory` is enabled only in a call's `memory.options` and not on the `Memory` instance. Observational memory runs only when it is configured on the instance, so a call-only setting now falls back to normal message history instead of skipping the save. Before, the regular agent saved nothing for the turn and durable agents saved only the user message. +Fixed agent turns being lost when `observationalMemory` is enabled only in a call's `memory.options` and not on the `Memory` instance. Observational memory runs only when it is configured on the instance, so a call-only opt-in now falls back to normal message history instead of skipping the save, and Memory logs a one-time warning that the opt-in was ignored. Per-call opt-outs are unchanged. Before, the regular agent saved nothing for the turn and durable agents saved only the user message. diff --git a/.changeset/durable-om-merged-config.md b/.changeset/durable-om-merged-config.md new file mode 100644 index 00000000000..6601faaa2db --- /dev/null +++ b/.changeset/durable-om-merged-config.md @@ -0,0 +1,5 @@ +--- +'@mastra/core': patch +--- + +Durable agents no longer treat a call-level `observationalMemory` opt-in as active when the Memory instance does not run observational memory, so such calls save their messages and generate the thread title like any other run. diff --git a/packages/core/src/agent/durable/preparation.ts b/packages/core/src/agent/durable/preparation.ts index 0d131753af7..63369fa7da2 100644 --- a/packages/core/src/agent/durable/preparation.ts +++ b/packages/core/src/agent/durable/preparation.ts @@ -843,7 +843,14 @@ export async function prepareForDurableExecution( // 12. Resolve memory persistence flags const savePerStep = execOptions?.savePerStep; - const observationalMemory = isObservationalMemoryEnabled(memoryConfig?.observationalMemory); + // A call-level OM setting only counts when the Memory instance can run it: the merged config turns + // an opt-in OM cannot run back to off, so the run saves through finalize like any other. Instance-only + // OM (#28886) still reads as off here; durable relies on the finalize flush for output-processor edits. + const observationalMemory = + isObservationalMemoryEnabled(memoryConfig?.observationalMemory) && + isObservationalMemoryEnabled( + (memory ? memory.getMergedThreadConfig(memoryConfig) : memoryConfig)?.observationalMemory, + ); if (execOptions.isTaskComplete) await loadDefaultOptions(); // 12b. Open MODEL_GENERATION under the AGENT_RUN opened in step 6, and export both diff --git a/packages/core/src/memory/types.ts b/packages/core/src/memory/types.ts index cdd4d4f335f..bafb7cd9662 100644 --- a/packages/core/src/memory/types.ts +++ b/packages/core/src/memory/types.ts @@ -1111,6 +1111,10 @@ type BaseMemoryConfig = { * * Set to `true` to enable with defaults, `false` to disable, or an object to customize. * + * Observational memory must be configured on the `Memory` instance. A per-call value in + * `memory.options` can tune it or turn it off for that call, but cannot turn it on for an + * instance that does not configure it; such a call falls back to message history. + * * @example * ```typescript * // Enable with defaults diff --git a/packages/memory/integration-tests/src/durable-agent-call-only-om.test.ts b/packages/memory/integration-tests/src/durable-agent-call-only-om.test.ts index 87895b91ee3..efde34a81e6 100644 --- a/packages/memory/integration-tests/src/durable-agent-call-only-om.test.ts +++ b/packages/memory/integration-tests/src/durable-agent-call-only-om.test.ts @@ -2,7 +2,8 @@ * Observational memory turned on only in the call's `memory.options` (not on `new Memory`). * * The OM engine is built from the Memory instance config, so a call-only OM setting has no - * engine to save the turn. Every engine must still store the user message and the reply. + * engine to save the turn. Every engine must still store the turn once, through the normal + * save path (durable: finalize flush + title), while instance-level OM keeps observing. */ import { randomUUID } from 'node:crypto'; import { MockLanguageModelV2, convertArrayToReadableStream } from '@internal/ai-sdk-v5/test'; @@ -15,46 +16,76 @@ import { describe, expect, it } from 'vitest'; import { persistedMessages, streamTurn } from './durable-harness-helpers'; const REPLY = 'Lisbon is sunny.'; +const TITLE = 'Lisbon weather'; -function mockModel() { +function mockModel(text: string, calls?: { count: number }) { return new MockLanguageModelV2({ - doStream: async () => ({ - rawCall: { rawPrompt: null, rawSettings: {} }, - warnings: [], - stream: convertArrayToReadableStream([ - { type: 'stream-start', warnings: [] }, - { type: 'response-metadata', id: 'r1', modelId: 'mock', timestamp: new Date(0) }, - { type: 'text-start', id: 't1' }, - { type: 'text-delta', id: 't1', delta: REPLY }, - { type: 'text-end', id: 't1' }, - { type: 'finish', finishReason: 'stop', usage: { inputTokens: 5, outputTokens: 5, totalTokens: 10 } }, - ]), - }), + doGenerate: async () => { + if (calls) calls.count++; + return { + content: [{ type: 'text', text }], + finishReason: 'stop', + usage: { inputTokens: 5, outputTokens: 5, totalTokens: 10 }, + warnings: [], + }; + }, + doStream: async () => { + if (calls) calls.count++; + return { + rawCall: { rawPrompt: null, rawSettings: {} }, + warnings: [], + stream: convertArrayToReadableStream([ + { type: 'stream-start', warnings: [] }, + { type: 'response-metadata', id: 'r1', modelId: 'mock', timestamp: new Date(0) }, + { type: 'text-start', id: 't1' }, + { type: 'text-delta', id: 't1', delta: text }, + { type: 'text-end', id: 't1' }, + { type: 'finish', finishReason: 'stop', usage: { inputTokens: 5, outputTokens: 5, totalTokens: 10 } }, + ]), + }; + }, }); } -const omOptions = { observationalMemory: { enabled: true, model: mockModel(), scope: 'thread' } } as any; - const CASES = { 'regular Agent, OM on call only': { engine: 'plain', instanceOM: false, callOM: true }, - 'DurableAgent, OM on Memory and call': { engine: 'durable', instanceOM: true, callOM: true }, 'DurableAgent, OM on call only': { engine: 'durable', instanceOM: false, callOM: true }, + 'DurableAgent, OM on Memory and call': { engine: 'durable', instanceOM: true, callOM: true }, 'DurableAgent, OM on Memory only': { engine: 'durable', instanceOM: true, callOM: false }, } as const; describe('call-only observational memory', () => { - it.each(Object.entries(CASES))('%s stores the user message and the reply', async (_name, c) => { + it.each(Object.entries(CASES))('%s stores the turn once', async (_name, c) => { + const observerCalls = { count: 0 }; + const omOptions = { + observationalMemory: { + enabled: true, + scope: 'thread', + observation: { + model: mockModel('\n* 🔴 User asked about Lisbon\n', observerCalls), + messageTokens: 1, + bufferTokens: false, + }, + reflection: { model: mockModel(''), observationTokens: 50_000 }, + }, + } as any; const storage = new LibSQLStore({ id: randomUUID(), url: ':memory:' }); const memory = new Memory({ storage, options: { lastMessages: 10, semanticRecall: false, - generateTitle: false, + generateTitle: { model: mockModel(TITLE) }, ...(c.instanceOM ? omOptions : {}), } as any, }); - const agent = new Agent({ id: `a-${randomUUID()}`, name: 'a', model: mockModel(), memory, instructions: 'hi' }); + const agent = new Agent({ + id: `a-${randomUUID()}`, + name: 'a', + model: mockModel(REPLY), + memory, + instructions: 'hi', + }); const runner = c.engine === 'plain' ? agent : createDurableAgent({ agent }); const mastra = new Mastra({ agents: { a: runner as any }, storage, logger: false }); @@ -68,5 +99,17 @@ describe('call-only observational memory', () => { const messages = await persistedMessages(memory, thread, resource); expect(messages.map(m => m.role)).toEqual(['user', 'assistant']); + expect(new Set(messages.map(m => m.id)).size).toBe(messages.length); + + if (c.instanceOM) { + // OM still runs: the observer was invoked and an observation was stored. + expect(observerCalls.count).toBeGreaterThan(0); + const record = await (await memory.omEngine)!.getRecord(thread, resource); + expect(record?.activeObservations).toContain('Lisbon'); + } else { + // The normal save path ran, including thread titling. + expect(observerCalls.count).toBe(0); + await expect.poll(async () => (await memory.getThreadById({ threadId: thread }))?.title).toBe(TITLE); + } }); }); diff --git a/packages/memory/src/call-only-observational-memory.test.ts b/packages/memory/src/call-only-observational-memory.test.ts new file mode 100644 index 00000000000..8472636a064 --- /dev/null +++ b/packages/memory/src/call-only-observational-memory.test.ts @@ -0,0 +1,50 @@ +import { InMemoryStore } from '@mastra/core/storage'; +import { describe, expect, it, vi } from 'vitest'; +import { Memory } from './index'; + +const om = { scope: 'thread', model: 'openai/gpt-4o-mini' } as const; + +function memoryWith(observationalMemory?: unknown) { + const memory = new Memory({ + storage: new InMemoryStore(), + options: observationalMemory === undefined ? {} : ({ observationalMemory } as any), + }); + const warn = vi.spyOn((memory as any).logger, 'warn'); + return { memory, warn }; +} + +describe('per-call observationalMemory on Memory.getMergedThreadConfig', () => { + it('turns a call opt-in off when the instance has no OM, and warns once', () => { + const { memory, warn } = memoryWith(); + expect(memory.getMergedThreadConfig({ observationalMemory: true }).observationalMemory).toBe(false); + expect(memory.getMergedThreadConfig({ observationalMemory: om as any }).observationalMemory).toBe(false); + expect(warn).toHaveBeenCalledTimes(1); + }); + + it('turns a call opt-in off when the instance sets { enabled: false }', () => { + const { memory, warn } = memoryWith({ enabled: false }); + expect(memory.getMergedThreadConfig({ observationalMemory: true }).observationalMemory).toBe(false); + expect(warn).toHaveBeenCalledTimes(1); + }); + + it('leaves a call opt-out unchanged and does not warn', () => { + const withOM = memoryWith(om); + expect(withOM.memory.getMergedThreadConfig({ observationalMemory: false }).observationalMemory).toBe(false); + expect( + withOM.memory.getMergedThreadConfig({ observationalMemory: { enabled: false } as any }).observationalMemory, + ).toMatchObject({ enabled: false }); + + const withoutOM = memoryWith(); + expect( + withoutOM.memory.getMergedThreadConfig({ observationalMemory: { enabled: false } as any }).observationalMemory, + ).toEqual({ enabled: false }); + expect(withOM.warn).not.toHaveBeenCalled(); + expect(withoutOM.warn).not.toHaveBeenCalled(); + }); + + it('keeps a call opt-in when the instance configures OM', () => { + const { memory, warn } = memoryWith(om); + expect(memory.getMergedThreadConfig({ observationalMemory: true }).observationalMemory).toBeTruthy(); + expect(warn).not.toHaveBeenCalled(); + }); +}); diff --git a/packages/memory/src/index.ts b/packages/memory/src/index.ts index 5a868703fc8..f7125e23043 100644 --- a/packages/memory/src/index.ts +++ b/packages/memory/src/index.ts @@ -541,8 +541,10 @@ export class Memory extends MastraMemory { } } - // False while the base constructor merges the instance options into threadConfig. - private readonly instanceConfigured = true; + // Undefined while the base constructor runs getMergedThreadConfig to build threadConfig; + // true once this class's field initializers have run. + private readonly derivedFieldsInitialized = true; + private warnedIgnoredCallObservationalMemory = false; public override getMergedThreadConfig(config?: MemoryConfigInternal): MemoryConfigInternal { const merged = super.getMergedThreadConfig(config); @@ -550,11 +552,16 @@ export class Memory extends MastraMemory { // opt-in on an instance without OM has nothing to observe or save the turn. Treat it as off // so message history keeps saving instead of every engine skipping persistence. if ( - this.instanceConfigured && + this.derivedFieldsInitialized && !normalizeObservationalMemoryConfig(this.threadConfig.observationalMemory) && - merged.observationalMemory !== undefined && - merged.observationalMemory !== false + normalizeObservationalMemoryConfig(merged.observationalMemory) ) { + if (!this.warnedIgnoredCallObservationalMemory) { + this.warnedIgnoredCallObservationalMemory = true; + this.logger.warn( + 'observationalMemory is enabled in call options but not on the Memory instance; it is ignored and message history is used instead. Configure observationalMemory on new Memory({ options }).', + ); + } return this.applyManagedWorkingMemoryDefaults({ ...merged, observationalMemory: false }); } return this.applyManagedWorkingMemoryDefaults(merged); From b996d2810797667cdfd7252099b8c047b58fe94e Mon Sep 17 00:00:00 2001 From: Jamie Lee Nichols <10267569+CodingButter@users.noreply.github.com> Date: Mon, 16 Nov 2026 13:17:12 -0500 Subject: [PATCH 3/3] test(memory): cover the regular agent with instance OM; narrow the per-call OM docs Co-Authored-By: mastracode <284800079+mastra-platform[bot]@users.noreply.github.com> --- packages/core/src/agent/durable/preparation.ts | 6 +++--- packages/core/src/memory/types.ts | 4 ++-- .../src/durable-agent-call-only-om.test.ts | 5 ++++- 3 files changed, 9 insertions(+), 6 deletions(-) diff --git a/packages/core/src/agent/durable/preparation.ts b/packages/core/src/agent/durable/preparation.ts index 63369fa7da2..00af9b2ce3d 100644 --- a/packages/core/src/agent/durable/preparation.ts +++ b/packages/core/src/agent/durable/preparation.ts @@ -843,9 +843,9 @@ export async function prepareForDurableExecution( // 12. Resolve memory persistence flags const savePerStep = execOptions?.savePerStep; - // A call-level OM setting only counts when the Memory instance can run it: the merged config turns - // an opt-in OM cannot run back to off, so the run saves through finalize like any other. Instance-only - // OM (#28886) still reads as off here; durable relies on the finalize flush for output-processor edits. + // A call-level OM opt-in counts only if it is still on after merging with the Memory instance's + // config; otherwise the run saves through finalize like any other. Instance-only OM (#28886) still + // reads as off here; durable relies on the finalize flush for output-processor edits. const observationalMemory = isObservationalMemoryEnabled(memoryConfig?.observationalMemory) && isObservationalMemoryEnabled( diff --git a/packages/core/src/memory/types.ts b/packages/core/src/memory/types.ts index bafb7cd9662..13f5f271600 100644 --- a/packages/core/src/memory/types.ts +++ b/packages/core/src/memory/types.ts @@ -1112,8 +1112,8 @@ type BaseMemoryConfig = { * Set to `true` to enable with defaults, `false` to disable, or an object to customize. * * Observational memory must be configured on the `Memory` instance. A per-call value in - * `memory.options` can tune it or turn it off for that call, but cannot turn it on for an - * instance that does not configure it; such a call falls back to message history. + * `memory.options` can turn it off for that call, but cannot turn it on for an instance that + * does not configure it; such a call falls back to message history. * * @example * ```typescript diff --git a/packages/memory/integration-tests/src/durable-agent-call-only-om.test.ts b/packages/memory/integration-tests/src/durable-agent-call-only-om.test.ts index efde34a81e6..61161f3fa39 100644 --- a/packages/memory/integration-tests/src/durable-agent-call-only-om.test.ts +++ b/packages/memory/integration-tests/src/durable-agent-call-only-om.test.ts @@ -49,6 +49,7 @@ function mockModel(text: string, calls?: { count: number }) { const CASES = { 'regular Agent, OM on call only': { engine: 'plain', instanceOM: false, callOM: true }, + 'regular Agent, OM on Memory and call': { engine: 'plain', instanceOM: true, callOM: true }, 'DurableAgent, OM on call only': { engine: 'durable', instanceOM: false, callOM: true }, 'DurableAgent, OM on Memory and call': { engine: 'durable', instanceOM: true, callOM: true }, 'DurableAgent, OM on Memory only': { engine: 'durable', instanceOM: true, callOM: false }, @@ -109,7 +110,9 @@ describe('call-only observational memory', () => { } else { // The normal save path ran, including thread titling. expect(observerCalls.count).toBe(0); - await expect.poll(async () => (await memory.getThreadById({ threadId: thread }))?.title).toBe(TITLE); + await expect + .poll(async () => (await memory.getThreadById({ threadId: thread }))?.title, { timeout: 5000 }) + .toBe(TITLE); } }); });