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

[sreedharsreeram]

No description provided.

[mintlify]

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]

Deploying with    Cloudflare Workers

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

Status	Name	Latest Commit	Updated (UTC)
✅ Deployment successful! View logs	supermemory-mcp	e32f66a	Apr 14 2026, 03:02 PM

[sreedharsreeram]

• 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]

Claude finished @sreedharsreeram's task in 1m 26s —— View job

---

Review Complete

• Fetch and analyze the full diff
• Review changed files for bugs, security issues, and logic errors
• Check existing review comments to avoid duplicates
• Submit review with findings

Result: No issues found — this PR is ready to ship.

This refactor cleanly migrates the Mastra integration to an object-based API with proper validation. The dead code issue in getEffectiveCustomId from earlier commits has been fixed, and the version bump to 2.0.0 is appropriate for this breaking change.

[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]

---

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]

---

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]

---

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]

is this guid only for mastra? @sreedharsreeram

[sreedharsreeram]

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

[MaheshtheDev]

do we need to update to version v2?

[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.