feat(memory): add OM-managed working memory by TylerBarnes · Pull Request #18654 · mastra-ai/mastra

TylerBarnes · 2026-06-29T23:17:10Z

Summary

Adds a built-in WorkingMemoryExtractor and a simpler OM-managed working memory setup.

With manageWorkingMemory, OM can extract working-memory updates from observations and apply them after the turn. The sugar defaults working memory to prompt-cache-friendly state signals and disables direct agent tool management unless the user opts back in.

new Memory({
  options: {
    observationalMemory: {
      enabled: true,
      observation: {
        manageWorkingMemory: true,
        // extractors: [new WorkingMemoryExtractor()] <- added internally by manageWorkingMemory: true
      },
    },
    workingMemory: {
      enabled: true,
      // these are configured internally by observation.manageWorkingMemory: true
      // agentManaged: false, <- disables the agent managing working memory via tool calls and removes system instructions saying to do so
      // useStateSignals: true,
    },
  },
});

Users who still want both paths can opt in explicitly:

workingMemory: {
  enabled: true,
  agentManaged: true
}

Test plan

pnpm --filter ./packages/memory test:unit -- --run src/processors/observational-memory/__tests__/extractor.test.ts src/processors/observational-memory/__tests__/observational-memory-api.test.ts --reporter=dot --bail 1
pnpm --filter ./packages/memory check
Stack rebase verified linear against feat(memory): add observational memory extractors #18653

Stack

changeset-bot · 2026-06-29T23:17:15Z

🦋 Changeset detected

Latest commit: 298d8e0

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 25 packages

Name	Type
@mastra/memory	Minor
@mastra/core	Minor
mastracode	Patch
@mastra/agent-builder	Patch
@mastra/editor	Patch
@internal/playground	Patch
@mastra/express	Patch
@mastra/fastify	Patch
@mastra/hono	Patch
@mastra/koa	Patch
@mastra/nestjs	Patch
@mastra/opencode	Patch
@mastra/longmemeval	Patch
@mastra/mcp-docs-server	Patch
@mastra/client-js	Patch
@mastra/server	Minor
mastra	Patch
@mastra/deployer-cloud	Minor
@mastra/react	Patch
@mastra/playground-ui	Patch
@mastra/deployer	Minor
create-mastra	Patch
@mastra/next	Patch
@mastra/tanstack-start	Patch
@mastra/temporal	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

vercel · 2026-06-29T23:17:17Z

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
mastra-docs-1.x	Ready	Preview, Comment	Jun 30, 2026 12:16am
mastra-playground-ui	Ready	Preview, Comment	Jun 30, 2026 12:16am

1 Skipped Deployment

Project	Deployment	Actions	Updated (UTC)
mastra-studio-preview	Ignored	Preview	Jun 30, 2026 12:16am

coderabbitai · 2026-06-29T23:17:17Z

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: 5883155d-4673-4c13-9c5f-2abe0eabde4e

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

Create PR with unit tests
Commit unit tests in branch feat/working-memory-extractor

_{Comment @coderabbitai help to get the list of available commands.}

dane-ai-mastra · 2026-06-29T23:18:17Z

PR triage

Linked issue check skipped for core contributor @TylerBarnes.

PR complexity score

Factor	Value	Score impact
Files changed	13	+26
Lines changed	470	+27
Author merged PRs	564	-20
Test files changed	Yes	-10
Final score		23

Applied label: complexity: medium

Changed test gate

Changed tests failed against the base branch as expected.

Label: tests: green ✅

Adds a WorkingMemoryExtractor that lets Observational Memory update working memory through the normal extractor pipeline. The extractor reads the active working memory template or schema, writes updates through the memory instance, and does not duplicate the value under OM extracted metadata. Also adds injectTools: boolean (default true) to BaseWorkingMemory config. Set to false when OM extractors or another path owns working memory updates, preventing the working memory tool from being injected into the main agent. Co-Authored-By: Mastra Code (crof/glm-5.2) <noreply@mastra.ai>

Co-Authored-By: Mastra Code (crof/glm-5.2) <noreply@mastra.ai>

TylerBarnes · 2026-06-29T23:49:36Z

+Adds a built-in `WorkingMemoryExtractor` for the Observational Memory extractor pipeline. When included in observation or reflection config, the observer/reflector can update working memory through the normal extractor pipeline instead of requiring the main agent to call the working memory tool.
+
+Adds `workingMemory.agentManaged` to control whether the main agent receives working memory tool/instruction injection, and `observationalMemory.observation.manageWorkingMemory` to automatically add the working memory extractor, default `agentManaged` to false, and default `useStateSignals` to true when working memory is enabled.


add an example of configuring OM to manage working memory (just the sugar example)

TylerBarnes · 2026-06-29T23:51:27Z

 })
 ```

+This setting adds `WorkingMemoryExtractor`, defaults `workingMemory.agentManaged` to `false`, and defaults `workingMemory.useStateSignals` to `true`. Set `workingMemory.agentManaged: true` if the main agent should still receive working memory tool and instruction injection.


lets lead with the outcome: the agent no longer needs to manage its own working memory, it's managed automatically by the observer. This fixes issues with working memory:

main agent is busy with other things and doesn't always remember to update working memory

working memory updates invalidate the prompt cache because working memory is in the system prompt. since OM is all about maintaining prompt cache, turning on OM managed working memory also turns on state signals for WM, which makes them prompt cache friendly

TylerBarnes · 2026-06-29T23:52:23Z

+
+function buildWorkingMemoryInstructions(details: Awaited<ReturnType<typeof getWorkingMemoryDetails>>): string {
+  if (!details.memory) {
+    return 'Working memory is unavailable. Do not output this section.';


this seems odd, when would this happen?

TylerBarnes · 2026-06-29T23:53:14Z

+        if (!memory) {
+          throw new Error('Working memory extractor requires an active Memory instance.');
+        }


how is this possible? we extract from within the memory system, memory must always exist here

TylerBarnes · 2026-06-29T23:54:18Z

+          const existing = parseJsonObject(await memory.getWorkingMemory({ threadId, resourceId, memoryConfig }));
+          const update = parseJsonObject(current);
+          if (!update) {
+            throw new Error('Working memory extractor expected a JSON object update.');


what if there was no update to make? it should be allowed to be omitted, and actually we may need to add that in to the working memory schema here somehow. The observer needs to be able to opt out of updating if there's no need to update

TylerBarnes · 2026-06-29T23:54:34Z

+          if (!update) {
+            throw new Error('Working memory extractor expected a JSON object update.');
+          }
+          workingMemory = JSON.stringify(deepMergeWorkingMemory(existing, update));


is this how existing working memory works? I thought it just always replaced it

Move the unreleased working memory extraction controls to the final agentManaged/manageWorkingMemory API. This keeps the working memory extractor branch from introducing the discarded injectTools name and documents the managed working memory defaults. Co-Authored-By: Mastra Code (openai/gpt-5.5) <noreply@mastra.ai>

vercel Bot deployed to Preview – mastra-docs-1.x June 29, 2026 23:17 View deployment

github-actions Bot added the Documentation Improvements or additions to documentation label Jun 29, 2026

TylerBarnes mentioned this pull request Jun 29, 2026

fix(playground): stabilize OM extraction markers #18655

Open

dane-ai-mastra Bot added the complexity: medium Medium-complexity PR label Jun 29, 2026

TylerBarnes mentioned this pull request Jun 29, 2026

feat(memory): add observational memory extractors #18653

Open

dane-ai-mastra Bot added the tests: green ✅ Changed tests failed against base as expected label Jun 29, 2026

TylerBarnes and others added 2 commits June 29, 2026 16:49

chore: add changeset for working memory extractor

baa1d38

Co-Authored-By: Mastra Code (crof/glm-5.2) <noreply@mastra.ai>

TylerBarnes force-pushed the feat/om-extractors branch from 331daf4 to 7fe1030 Compare June 29, 2026 23:57

TylerBarnes force-pushed the feat/working-memory-extractor branch from 5d3d2b8 to 298e17e Compare June 29, 2026 23:57

TylerBarnes commented Jun 29, 2026

View reviewed changes

dane-ai-mastra Bot added tests: failing ❌ Changed tests passed against base and removed tests: green ✅ Changed tests failed against base as expected labels Jun 29, 2026

vercel Bot deployed to Preview – mastra-playground-ui June 29, 2026 23:59 View deployment

vercel Bot deployed to Preview – mastra-docs-1.x June 29, 2026 23:59 View deployment

TylerBarnes requested review from CalebBarnes and abhiaiyer91 June 30, 2026 00:02

dane-ai-mastra Bot added tests: green ✅ Changed tests failed against base as expected and removed tests: failing ❌ Changed tests passed against base labels Jun 30, 2026

TylerBarnes force-pushed the feat/working-memory-extractor branch from 298e17e to 298d8e0 Compare June 30, 2026 00:14

vercel Bot deployed to Preview – mastra-playground-ui June 30, 2026 00:15 View deployment

vercel Bot deployed to Preview – mastra-docs-1.x June 30, 2026 00:16 View deployment

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

feat(memory): add OM-managed working memory#18654

feat(memory): add OM-managed working memory#18654
TylerBarnes wants to merge 3 commits into
feat/om-extractorsfrom
feat/working-memory-extractor

TylerBarnes commented Jun 29, 2026 •

edited

Loading

Uh oh!

changeset-bot Bot commented Jun 29, 2026 •

edited

Loading

Uh oh!

vercel Bot commented Jun 29, 2026 •

edited

Loading

Uh oh!

coderabbitai Bot commented Jun 29, 2026 •

edited

Loading

Review skipped

Uh oh!

dane-ai-mastra Bot commented Jun 29, 2026 •

edited

Loading

Uh oh!

TylerBarnes Jun 29, 2026

Uh oh!

TylerBarnes Jun 29, 2026

Uh oh!

TylerBarnes Jun 29, 2026

Uh oh!

TylerBarnes Jun 29, 2026

Uh oh!

TylerBarnes Jun 29, 2026

Uh oh!

TylerBarnes Jun 29, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

		Adds a built-in `WorkingMemoryExtractor` for the Observational Memory extractor pipeline. When included in observation or reflection config, the observer/reflector can update working memory through the normal extractor pipeline instead of requiring the main agent to call the working memory tool.

		Adds `workingMemory.agentManaged` to control whether the main agent receives working memory tool/instruction injection, and `observationalMemory.observation.manageWorkingMemory` to automatically add the working memory extractor, default `agentManaged` to false, and default `useStateSignals` to true when working memory is enabled.

Uh oh!

Conversation

TylerBarnes commented Jun 29, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Test plan

Stack

Uh oh!

changeset-bot Bot commented Jun 29, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🦋 Changeset detected

Uh oh!

vercel Bot commented Jun 29, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

coderabbitai Bot commented Jun 29, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Review skipped

Uh oh!

dane-ai-mastra Bot commented Jun 29, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

PR triage

PR complexity score

Changed test gate

Uh oh!

TylerBarnes Jun 29, 2026

Choose a reason for hiding this comment

Uh oh!

TylerBarnes Jun 29, 2026

Choose a reason for hiding this comment

Uh oh!

TylerBarnes Jun 29, 2026

Choose a reason for hiding this comment

Uh oh!

TylerBarnes Jun 29, 2026

Choose a reason for hiding this comment

Uh oh!

TylerBarnes Jun 29, 2026

Choose a reason for hiding this comment

Uh oh!

TylerBarnes Jun 29, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

TylerBarnes commented Jun 29, 2026 •

edited

Loading

changeset-bot Bot commented Jun 29, 2026 •

edited

Loading

vercel Bot commented Jun 29, 2026 •

edited

Loading

coderabbitai Bot commented Jun 29, 2026 •

edited

Loading

dane-ai-mastra Bot commented Jun 29, 2026 •

edited

Loading