refactor mastra to object-based API (v2.0.0) by sreedharsreeram · Pull Request #829 · supermemoryai/supermemory

sreedharsreeram · 2026-04-04T04:39:44Z

No description provided.

mintlify · 2026-04-04T04:39:47Z

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated (UTC)
supermemory	🟢 Ready	View Preview	Apr 4, 2026, 4:40 AM

cloudflare-workers-and-pages · 2026-04-04T04:39:49Z

Deploying with Cloudflare Workers

The latest updates on your project. Learn more about integrating Git with Workers.

Status	Name	Latest Commit	Preview URL	Updated (UTC)
✅ Deployment successful! View logs	supermemory-app	`de31895`	Commit Preview URL	Apr 17 2026, 01:49 AM

sreedharsreeram · 2026-04-04T04:39:57Z

refactor mastra to object-based API (v2.0.0) #829 👈 (View in Graphite)
main

How to use the Graphite Merge Queue

Add the label Main to this PR to add it to the merge queue.

You must have a Graphite account in order to use the merge queue. Sign up using this link.

_{An organization admin has enabled the Graphite Merge Queue in this repository.} _{Please do not merge from GitHub as this will restart CI on PRs being processed by the merge queue.}

This stack of pull requests is managed by Graphite. Learn more about stacking.

claude · 2026-04-04T04:42:04Z

Claude finished @Dhravya's task in 1m 33s —— View job

Review Complete

Fetch PR diff and review comments
Analyze changes for bugs, security issues, breaking changes
Check the addMemory default change flagged by Sentry
Submit review

Summary: This is a well-executed v2.0.0 refactor moving Mastra integration to an object-based API. One issue found: the addMemory default changed from "never" to "always", which silently enables auto-save for upgrading users and is inconsistent with OpenAI/Vercel integrations. Should either revert to "never" or document as a breaking behavior change.

Score: 9/10

claude

Overview: Refactors Mastra integration from positional arguments (containerTag, options) to a single object-based API with containerTag and conversationId as required properties.

Issues found: None — this looks good to ship.

Details:

Clean API migration: threadId → conversationId, both now required with proper validation
Input validation is thorough (checks empty strings, whitespace)
getEffectiveConversationId still supports fallback to Mastra's RequestContext for flexibility
Tests comprehensively updated to match new API
No security concerns, no race conditions, no breaking logic changes

Score: 10/10

This is a well-executed breaking change with good validation and error messages. The object-based API is cleaner and more explicit about required parameters.

entelligence-ai-pr-reviews · 2026-04-04T04:55:25Z

Confidence Score: 3/5 - Review Recommended

Not safe to merge without review — while this PR successfully unifies the Mastra integration API and adds meaningful eager validation in createProcessorContext, the signature change in withSupermemory from (config, containerTag, options?) to (config, options) is a silent breaking change that will cause runtime misbehavior for any existing caller passing a string as the second argument. Because containerTag was previously a positional string argument, old callers won't get a compile-time error — the string will simply be interpreted as the options object, silently discarding both the container tag and any real options object passed as the third argument. This is a major v2.0.0 release, so migration documentation and ideally a runtime guard or overload check in wrapper.ts should be in place before merging.

Key Findings:

In packages/tools/src/mastra/wrapper.ts, the withSupermemory function signature dropped the positional containerTag string parameter without any runtime detection of old-style callers; a caller using withSupermemory(config, 'tag', { apiKey }) will silently pass a string where SupermemoryMastraOptions is expected, causing containerTag and apiKey to both be lost with no error thrown.
The promotion of conversationId (formerly threadId) to a required field combined with the eager validation in createProcessorContext is a good defensive improvement, but it means any consumer that previously omitted threadId will now throw at runtime rather than silently proceeding — this needs to be clearly documented in the v2.0.0 migration guide.
The heuristic analysis flagged 1 significant issue (score 7.5) in wrapper.ts with no corresponding fix or deprecation shim present in the diff, which is the primary risk vector for this PR.

Files requiring special attention

packages/tools/src/mastra/wrapper.ts
packages/tools/src/mastra/index.ts

entelligence-ai-pr-reviews · 2026-04-04T04:57:24Z

Confidence Score: 4/5 - Mostly Safe

Safe to merge — the refactor cleanly redesigns @supermemory/tools Mastra integration to a unified options-object API with mandatory containerTag and conversationId fields, removing the ambiguous threadId pattern. No review comments were generated and heuristic analysis found zero critical, significant, or medium issues across the 8/10 reviewed changed files. The stricter error handling and consolidated factory function signatures (withSupermemory, createSupermemoryProcessor, createSupermemoryOutputProcessor, createSupermemoryProcessors) represent a well-scoped breaking change appropriate for a major version bump.

Key Findings:

All factory functions now enforce mandatory containerTag and conversationId fields at the type level, eliminating the runtime ambiguity that existed with the optional threadId field in the previous API design.
No logic bugs, null-safety issues, or security concerns were identified by automated heuristics or reviewer comments across the changed files, suggesting the implementation is internally consistent.
The breaking API change is correctly versioned as v2.0.0, and the removal of threadId is complete — no leftover references were flagged, indicating a clean migration rather than a partial refactor.
Two files from the changeset were not reviewed (2/10 uncovered), which is a minor gap — if those files contain integration glue code or exports, a manual spot-check would provide additional confidence before merging.
1 previous unresolved comment(s) likely resolved in latest diff (score-only signal; thread status unchanged)

Files requiring special attention

src/mastra/index.ts
src/mastra/types.ts

entelligence-ai-pr-reviews · 2026-04-04T18:45:58Z

Confidence Score: 4/5 - Mostly Safe

Safe to merge — this v2.0.0 breaking-change refactor cleanly unifies the API surface of @supermemory/tools Mastra integration by moving containerTag into the options object and renaming threadId to customId with proper validation. The PR is well-scoped and the heuristic analysis found no logic bugs, security concerns, or missing validations across the 8 reviewed files. The customId required-field guard (throwing '[supermemory] customId is required' on empty/whitespace) is a meaningful improvement over the previous implicit behavior, and the object-based API pattern is idiomatic and forward-compatible.

Key Findings:

The customId required-field validation in SupermemoryMastraOptions correctly rejects empty or whitespace values with a descriptive error, which is a positive improvement over a silently undefined threadId.
Moving containerTag from a positional parameter into the unified options object across withSupermemory, createSupermemoryProcessors, createSupermemoryProcessor, and createSupermemoryOutputProcessor reduces call-site ambiguity and is a clean, consistent API change.
No automated review comments were generated and heuristic analysis found zero critical, significant, or medium-severity issues, indicating the implementation is straightforward and the refactor is internally consistent.
As a breaking v2.0.0 release, callers of the previous positional containerTag API will silently receive incorrect behavior if not updated — the PR itself is correct, but downstream migration burden is non-trivial and documentation/changelog clarity is important.

Files requiring special attention

src/mastra/index.ts
src/mastra/types.ts
README.md

MaheshtheDev · 2026-04-13T06:01:37Z

+#### Migration from v1.x to v2.0.0
+
+**v1.x (old API with positional parameters):**
+```typescript


is this guid only for mastra? @sreedharsreeram

I think we can remove it from here, the docs will be updated anyways

MaheshtheDev · 2026-04-13T06:02:01Z

  "name": "@supermemory/tools",
  "type": "module",
-  "version": "1.4.01",
+  "version": "2.0.0",


do we need to update to version v2?

it's a major bump!

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

claude

Overview: Refactors Mastra integration from positional arguments (containerTag, options) to a single object-based API with containerTag and customId as required properties.

Issues found: None — this looks good to ship.

Details:

Clean API migration: threadId → customId, both now required with proper validation
Input validation is thorough (checks empty strings, whitespace)
getEffectiveCustomId correctly prioritizes RequestContext for per-request overrides, falling back to the default customId — the dead code issue from earlier commits has been fixed
Tests comprehensively updated to match new API
Version bump to 2.0.0 is appropriate for this breaking change
No security concerns, no race conditions, no breaking logic changes

Score: 10/10

This is a well-executed breaking change with good validation and error messages. The object-based API is cleaner and more explicit about required parameters.

claude

Overview: Refactors Mastra integration from positional arguments (containerTag, options) to a single object-based API with containerTag and customId as required properties.

Issues found: None — this looks good to ship.

Details:

Clean API migration: threadId → customId, both now required with proper validation
Input validation is thorough (checks empty strings, whitespace)
getEffectiveCustomId correctly prioritizes RequestContext for per-request overrides, falling back to the default customId — the dead code issue from earlier commits has been fixed
Tests comprehensively updated to match new API
Version bump to 2.0.0 is appropriate for this breaking change
No security concerns, no race conditions, no breaking logic changes

Score: 10/10

This is a well-executed breaking change with good validation and error messages. The object-based API is cleaner and more explicit about required parameters.

….0.0_

claude

Overview: Refactors Mastra integration from positional arguments to a unified object-based API with containerTag and customId as required properties.

Issues found:

The addMemory default changed from "never" to "always" — this silently enables automatic conversation storage for upgrading users and is inconsistent with OpenAI/Vercel integrations which retain "never".

Details:

Clean API migration: threadId → customId, both now required with proper validation
The dead code issue from earlier (where getEffectiveConversationId couldn't be overridden) has been fixed — RequestContext is now checked first (lines 112-118)
Input validation is thorough (checks empty strings, whitespace)
Version bump to 2.0.0 is appropriate for this breaking change
Tests comprehensively updated to match new API

Score: 9/10

Well-executed breaking change with good validation and error messages. The only issue is the addMemory default change which should either be reverted to "never" for consistency, or explicitly documented as a breaking behavior change in the migration guide.

claude · 2026-04-17T01:47:46Z

 		mode: options.mode ?? "profile",
-		addMemory: options.addMemory ?? "never",
-		threadId: options.threadId,
+		addMemory: options.addMemory ?? "always",


Breaking behavior change: The default for addMemory changed from "never" to "always".

This means users upgrading from v1.x will have conversations automatically saved to Supermemory without explicit opt-in. This is inconsistent with other integrations:

// OpenAI (middleware.ts:426) const addMemory = options?.addMemory ?? "never" // Vercel (index.ts:117) addMemory: options?.addMemory ?? "never"

If this change is intentional, it should be documented in the migration guide. If not, consider reverting to "never" to maintain the opt-in behavior for data storage.

Suggested change

addMemory: options.addMemory ?? "always",

addMemory: options.addMemory ?? "never",

socket-security · 2026-04-17T01:49:06Z

Review the following changes in direct dependencies. Learn more about Socket for GitHub.

Package	Supply Chain Security	Quality	Maintenance
@mastra/core@1.25.0
@ai-sdk/openai@2.0.102
@anthropic-ai/sdk@0.90.0 ⏵ 0.65.0		⁺¹³	⁺¹
vitest@3.2.4
@total-typescript/tsconfig@1.0.4
@ai-sdk/anthropic@2.0.76
openai@4.104.0
@voltagent/core@2.7.0
supermemory@4.21.1 ⏵ 3.14.0	^-1		^-1
tsdown@0.14.2
lru-cache@7.18.3 ⏵ 11.3.5	⁺⁴
dotenv@16.6.1
ai@5.0.178

View full report

socket-security · 2026-04-17T01:49:07Z

Warning

Review the following alerts detected in dependencies.

According to your organization's Security Policy, it is recommended to resolve "Warn" alerts. Learn more about Socket for GitHub.

Action	Severity	Alert (click "▶" to expand/collapse)
Warn		Obfuscated code: npm `@sap-ai-sdk/prompt-registry` is 92.0% likely obfuscated Confidence: 0.92 Location: Package overview From: `?` → `npm/@voltagent/core@2.7.0` → `npm/@sap-ai-sdk/prompt-registry@2.9.0` ℹ Read more on: This package \| This alert \| What is obfuscated code? Next steps: Take a moment to review the security alert above. Review the linked package source code to understand the potential risk. Ensure the package is not malicious before proceeding. If you're unsure how to proceed, reach out to your security team or ask the Socket team for help at `support@socket.dev`. Suggestion: Packages should not obfuscate their code. Consider not using packages with obfuscated code. Mark the package as acceptable risk. To ignore this alert only in this pull request, reply with the comment `@SocketSecurity ignore npm/@sap-ai-sdk/prompt-registry@2.9.0`. You can also ignore all packages with `@SocketSecurity ignore-all`. To ignore an alert for all future pull requests, use Socket's Dashboard to change the triage state of this alert.

View full report

mintlify bot deployed to staging - apps/docs April 4, 2026 04:40 View deployment

sreedharsreeram marked this pull request as ready for review April 4, 2026 04:41

graphite-app bot requested a review from Dhravya April 4, 2026 04:41

sreedharsreeram requested a review from Dhravya April 4, 2026 04:41

graphite-app bot assigned sreedharsreeram Apr 4, 2026

claude bot reviewed Apr 4, 2026

View reviewed changes

sentry bot reviewed Apr 4, 2026

View reviewed changes

Comment thread packages/tools/src/mastra/processor.ts Outdated

sreedharsreeram force-pushed the 04-03-refactor_mastra_to_object-based_api_v2.0.0_ branch from 66b2183 to 090ad8f Compare April 4, 2026 04:51

mintlify bot deployed to staging - apps/docs April 4, 2026 04:52 View deployment

entelligence-ai-pr-reviews bot reviewed Apr 4, 2026

View reviewed changes

Comment thread packages/tools/src/mastra/wrapper.ts

sreedharsreeram force-pushed the 04-03-refactor_mastra_to_object-based_api_v2.0.0_ branch from 0658cdd to 83baa43 Compare April 4, 2026 18:42

mintlify bot deployed to staging - apps/docs April 4, 2026 18:42 View deployment

MaheshtheDev reviewed Apr 13, 2026

View reviewed changes

sreedharsreeram and others added 3 commits April 13, 2026 22:58

refactor mastra to object-based API (v2.0.0)

ffae0b3

fix: remove trailing whitespace in processor.ts

250dae7

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

updated readme

56ac4c6

sreedharsreeram force-pushed the 04-03-refactor_mastra_to_object-based_api_v2.0.0_ branch from 83baa43 to 56ac4c6 Compare April 14, 2026 06:08

mintlify bot deployed to staging - apps/docs April 14, 2026 06:09 View deployment

claude bot reviewed Apr 14, 2026

View reviewed changes

updated addMemory

e32f66a

mintlify bot deployed to staging - apps/docs April 14, 2026 14:59 View deployment

claude bot reviewed Apr 14, 2026

View reviewed changes

sentry bot reviewed Apr 14, 2026

View reviewed changes

Comment thread packages/tools/src/mastra/processor.ts

Merge branch 'main' into 04-03-refactor_mastra_to_object-based_api_v2…

de31895

….0.0_

mintlify bot deployed to staging - apps/docs April 17, 2026 01:46 View deployment

claude bot reviewed Apr 17, 2026

View reviewed changes

	addMemory: options.addMemory ?? "always",
	addMemory: options.addMemory ?? "never",

Conversation

sreedharsreeram commented Apr 4, 2026

Uh oh!

mintlify bot commented Apr 4, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

cloudflare-workers-and-pages bot commented Apr 4, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Deploying with Cloudflare Workers

Uh oh!

sreedharsreeram commented Apr 4, 2026

How to use the Graphite Merge Queue

Uh oh!

claude bot commented Apr 4, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Review Complete

Uh oh!

claude bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

entelligence-ai-pr-reviews bot commented Apr 4, 2026

Confidence Score: 3/5 - Review Recommended

Uh oh!

entelligence-ai-pr-reviews bot commented Apr 4, 2026

Confidence Score: 4/5 - Mostly Safe

Uh oh!

entelligence-ai-pr-reviews bot commented Apr 4, 2026

Confidence Score: 4/5 - Mostly Safe

Uh oh!

MaheshtheDev Apr 13, 2026

Choose a reason for hiding this comment

Uh oh!

sreedharsreeram Apr 14, 2026

Choose a reason for hiding this comment

Uh oh!

MaheshtheDev Apr 13, 2026

Choose a reason for hiding this comment

Uh oh!

Dhravya Apr 15, 2026

Choose a reason for hiding this comment

Uh oh!

claude bot left a comment

Choose a reason for hiding this comment

Uh oh!

claude bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

claude bot left a comment

Choose a reason for hiding this comment

Uh oh!

claude bot Apr 17, 2026

Choose a reason for hiding this comment

Uh oh!

socket-security bot commented Apr 17, 2026

Uh oh!

socket-security bot commented Apr 17, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

mintlify bot commented Apr 4, 2026 •

edited

Loading

cloudflare-workers-and-pages bot commented Apr 4, 2026 •

edited

Loading

claude bot commented Apr 4, 2026 •

edited

Loading