This PR was opened by the [Changesets
release](https://github.com/changesets/action) GitHub action. When
you're ready to do a release, you can merge this and publish to npm
yourself or [setup this action to publish
automatically](https://github.com/changesets/action#with-publishing). If
you're not ready to do a release yet, that's fine, whenever you add more
changesets to main, this PR will be updated.
⚠️⚠️⚠️⚠️⚠️⚠️
`main` is currently in **pre mode** so this branch has prereleases
rather than normal releases. If you want to exit prereleases, run
`changeset pre exit` on `main`.
⚠️⚠️⚠️⚠️⚠️⚠️
# Releases
> The changelog information of each package has been omitted from this
message, as the content exceeds the size limit.
## @mastra/factory@0.28.0-alpha.6
## @mastra/code-sdk@1.19.0-alpha.6
## @mastra/playground-ui@69.0.0-alpha.7
## @mastra/client-js@1.60.0-alpha.6
## @mastra/react@1.15.0-alpha.6
## @mastra/deployer-cloud@1.83.0-alpha.6
## @mastra/longmemeval@1.1.42-alpha.6
## @mastra/opencode@0.1.42-alpha.6
## create-factory@0.4.3-alpha.6
## mastracode@0.50.0-alpha.6
## @mastra/agent-builder@1.2.1-alpha.3
## mastra@1.39.0-alpha.6
## @mastra/core@1.83.0-alpha.6
## @mastra/deployer@1.83.0-alpha.6
## @mastra/editor@0.17.1-alpha.4
## @mastra/mcp@2.9.0-alpha.3
## @mastra/mcp-docs-server@1.3.13-alpha.9
## @mastra/memory@1.41.1-alpha.3
## @mastra/rag@2.7.3-alpha.2
## @mastra/schema-compat@1.3.18-alpha.0
## @mastra/server@1.83.0-alpha.6
## @mastra/elysia@0.1.23-alpha.6
## @mastra/express@1.5.27-alpha.6
## @mastra/fastify@1.5.27-alpha.6
## @mastra/hono@1.7.25-alpha.6
## @mastra/koa@1.7.27-alpha.6
## @mastra/nestjs@0.3.0-alpha.6
## @mastra/next@0.2.41-alpha.6
## @mastra/server-adapters-test-suite@0.3.0-alpha.3
## @mastra/tanstack-start@0.2.41-alpha.6
## @mastra/upstash@1.6.1-alpha.0
## @mastra/vectorize@1.1.5-alpha.0
## @mastra/voice-google-gemini-live@0.14.19-alpha.0
## @mastra/voice-openai-realtime@0.14.9-alpha.0
## @mastra/voice-xai-realtime@0.2.18-alpha.0
## @mastra/inngest@1.11.2-alpha.4
## @mastra/temporal@0.6.0-alpha.6
## create-mastra@1.39.0-alpha.6
## @internal/playground@1.39.0-alpha.6
Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
## Description
`semanticRecall.filter` worked in `Memory.recall()` but not during
`agent.generate()` or `agent.stream()`. During an agent run, recall
happens in the `SemanticRecall` processor, which never read `filter` and
queried the vector store with the scope filter only. So messages from
threads that didn't match the filter ended up in the prompt.
This PR changes
`packages/core/src/processors/memory/semantic-recall.ts`:
```diff
query filter
- scopeFilter
+ filter ? { $and: [scopeFilter, filter] } : scopeFilter // same as Memory.recall()
embedding metadata written during agent runs
- { message_id, thread_id, resource_id, ... }
+ { ...threadMetadata (only when filter is set), message_id, thread_id, resource_id, ... }
```
- The filter applies to both query paths: client-side embedder and
self-embedding stores.
- Embeddings written during agent runs had no thread metadata, so even
with the query fixed, a filter like `{ mode: { $eq: 'work' } }` could
never match messages that agents saved. When a filter is set, the
processor now reads the thread from storage and stores its metadata on
the embedding, as `Memory.saveMessages()` already does. It reads from
storage because durable and recovered runs put only the thread id in the
memory context.
- Without a filter, nothing about writes changes. Some vector stores
reject nested metadata values and this processor only logs a failed
upsert, so the metadata is written only when a filter needs it.
- Docs: added `filter` to the processor reference and a note on the
semantic recall page that messages agents saved before a filter was set
don't match it until they're saved or indexed again.
## Related issue(s)
Closes#29352
## Type of change
- [x] Bug fix (non-breaking change that fixes an issue)
- [ ] New feature (non-breaking change that adds functionality)
- [ ] Breaking change (fix or feature that would cause existing
functionality to change)
- [x] Documentation update
- [ ] Code refactoring
- [ ] Performance improvement
- [x] Test update
## Checklist
- [x] I have linked the related issue(s) in the description above
- [x] I have made corresponding changes to the documentation (if
applicable)
- [x] I have added tests that prove my fix is effective or that my
feature works
- [ ] I have addressed all Coderabbit comments on this PR
## Evidence
Before = `semantic-recall.ts` from `origin/main`, with the same tests.
After = this branch.
- **Core, real Agent + MockMemory + in-memory vector store that applies
filters**
(`packages/core/src/processors/memory/semantic-recall-filter.test.ts`,
new): generate and stream, filter vs no filter, self-embedding store,
thread scope, durable-shaped context (`thread: { id }` only), thread
metadata written only with a filter.
**Before:** `Tests 7 failed | 2 passed (9)` (the two no-filter cases
pass on both).
**After:** `Tests 9 passed (9)`.
- **Memory integration, real `Memory` + LibSQL store and vector +
Agent**
(`packages/memory/integration-tests/src/semantic-recall-metadata-filter.test.ts`):
generate and stream; messages saved with `saveMessages()`, by earlier
agent runs, and in a thread the run created with metadata. Also checks
`Memory.recall()` agrees with the agent run.
**Before:** `Tests 6 failed | 2 passed (8)` (the two existing `recall()`
cases pass on both).
**After:** `Tests 8 passed (8)`.
- **The issue's own repro script** (LibSQL, mock embedder and model),
run against local builds:
**Before:** `agent prompt contains personal message: true`
**After:** `agent prompt contains personal message: false`
- Neighbouring core suites (`semantic-recall.test.ts`,
`processor-caching.test.ts`, `memory-config.test.ts`,
`embedding-dimension.test.ts`): 69/69 pass. `@mastra/core` typecheck
passes; oxlint, oxfmt and lint-staged are clean on the changed files.
Not tested: a real DurableAgent run end to end. The durable context
shape is covered by calling the Memory-built processor with `thread: {
id }` only, as `durable-agent.ts` and `finalize-run.ts` set it.
## Merge Danger
**Door:** two-way. A revert restores the old behavior. Embeddings
already written with thread metadata stay in the vector store but are
harmless extra fields.
**Blast radius:** agents with `semanticRecall.filter` configured. They
now recall fewer messages (only matching threads), which is the
documented behavior. Messages saved by older versions have no thread
metadata, so they won't match a filter until re-saved or re-indexed; the
changeset and docs say so. Users without a filter see no change in
queries.
**After merging main (#29826):** main's shared embedding helper now
always stores thread metadata on agent-run embeddings, so this PR no
longer adds its own filter-only metadata read; docs, changeset and the
unit test were updated to match.
**Cloudflare Vectorize (`@mastra/vectorize`):** the scope and user
filter are combined as `{ $and: [...] }` (the same shape
`Memory.recall()` already sends on main), which the Vectorize translator
rejected, so recall with a filter returned nothing there. The translator
now merges a filter that is exactly `{ $and: [...] }` into one object.
Several conditions on one field merge only as one lower plus one upper
bound; other same-field combinations and non-object clauses throw. Not
run against a live Vectorize index; checked against Cloudflare's
metadata-filtering docs and 38 translator tests (Sol reviewed 3 rounds).
## Council review
Rounds: 4
| Seat | Round 1 | Round 2 | Round 3 | Round 4 |
| --- | --- | --- | --- | --- |
| Claude Opus 5.5 | not run | not run | 8.5/10 | 9/10 |
| GPT-6.1 Sol | 9/10 (Tests 8, Code quality 8) | 9.6/10 | 9.5/10 |
9.5/10 |
| Grok 4.7 | empty seat | empty seat | empty seat | empty seat |
Created with Claude Opus 5.5 in T3 Code.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
<!-- coderabbit-ai-generated:v1 -->
## ELI5
Agents now use the configured metadata filter when they search for
relevant messages. This keeps messages from unrelated threads out of the
agent’s prompt. Cloudflare Vectorize can also process the combined
filters used for these searches.
## Changes
- `SemanticRecall` combines the configured `VectorFilter` with the
thread or resource scope filter using `$and`.
- When a filter is configured, the processor reads thread metadata from
storage and writes it to message embeddings. Older embeddings may need
to be saved or indexed again.
- The Vectorize filter translator merges supported top-level `$and`
clauses, including repeated conditions with the same value. It rejects
unsupported combinations on the same field.
- Updated documentation and added tests for `generate()`, `stream()`,
self-embedding queries, and Vectorize filter translation.
## Verification
- Reported: 9/9 core filter tests, 8/8 integration tests, 69/69
neighboring core tests, 38 Vectorize translator tests, and the
`@mastra/core` typecheck passed.
- A real DurableAgent run was not tested end to end. A core test covers
a processor request context that contains only a thread ID.
- Live Cloudflare Vectorize testing: not available.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
---------
Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
**─────── TLDR ───────**
> The shared Oxlint config now errors on `!!x` inside a condition and on
a `catch` block that only rethrows.
A `catch (err) { throw err; }` reads like something is handled. Nothing
is. `!!x` inside an `if` reads like a deliberate coercion the `if`
already performs. Ten casts and twelve catches across 14 files go.
Nothing reaches a caller differently.
an error thrown inside one of the twelve removed `try` blocks
└─ **unchanged** — same object, same stack, same caller
receives it
| | | |
|---|---|---|
| **+** | `no-useless-catch` | a catch that only rethrows is dead code |
| **+** | `no-extra-boolean-cast` | `if` and `?:` already coerce |
### Decisions
- **no changeset** — no consumer can observe a difference, so no
release; `changeset add --empty` if the red status check bothers you
- **two monorepo e2e assertions for a no-op** — the gate requires
monorepo coverage for any `packages/deployer/` change; they pin the two
reads touched
### Not verified
- [ ] MSSQL, Spanner, Railway, Pinecone and Vectorize paths — their
suites need live services
---
> ██████████████████ **source** `+122 −169` — net −47
> █████ **tests** `+36 −11`
> █ **lint config** `+2`
## Summary
The `.map()` callback in `CloudflareVector.listIndexes()`
(`stores/vectorize/src/vector/index.ts`) had no type annotation on its
parameter. When the Cloudflare SDK's return type falls back to `any` in
the type environment, the callback parameter becomes an implicit `any`,
which fails the strict TypeScript build for `@mastra/vectorize`.
This adds a minimal inline type annotation (`{ name?: string }`) so the
build succeeds regardless of how the SDK's types resolve.
## Test plan
- [x] `pnpm --filter @mastra/vectorize run build:lib` succeeds
- [x] `tsc --noEmit` in `stores/vectorize` is clean
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## ELI5
This fixes a small TypeScript error by telling the code what each
Cloudflare index looks like. This helps strict builds succeed even when
Cloudflare’s types aren’t available.
## Changes
- Added an explicit `{ name?: string }` type to the `listIndexes()`
mapping callback.
- Added a patch Changesets entry for `@mastra/vectorize`.
- Verified the Vectorize build and `tsc --noEmit` checks pass.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
---------
Co-authored-by: Mastra Code (anthropic/claude-opus-4-7) <noreply@mastra.ai>
## Description
<!-- Required: Provide a brief description of the changes in this PR.
-->
## Related issue(s)
<!-- Required: Link to the issue(s) this PR addresses, e.g. with: Fixes
#123. PRs without linked issues may be closed. -->
## Type of change
- [ ] Bug fix (non-breaking change that fixes an issue)
- [ ] New feature (non-breaking change that adds functionality)
- [ ] Breaking change (fix or feature that would cause existing
functionality to change)
- [ ] Documentation update
- [ ] Code refactoring
- [ ] Performance improvement
- [ ] Test update
## Checklist
- [ ] I have linked the related issue(s) in the description above
- [ ] I have made corresponding changes to the documentation (if
applicable)
- [ ] I have added tests that prove my fix is effective or that my
feature works
- [ ] I have addressed all Coderabbit comments on this PR
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## ELI5
This PR upgrades the Turbo monorepo build tool from version 2.9.6 to
2.9.12 and updates all configuration files across the entire codebase to
use the newer schema version that corresponds to this updated tool
version. Think of it like updating a recipe book to the latest version
and making sure all your cookbook references point to the new edition.
## Changes Summary
### Turbo Version Upgrade
- Updated root `package.json` `devDependencies`: `turbo` upgraded from
`^2.9.6` to `^2.9.12`
### Turbo Configuration Schema Updates
Updated the `$schema` field in 73 `turbo.json` configuration files
throughout the repository from the legacy
`https://turbo.build/schema.json` to the newer
`https://v2-9-16.turborepo.dev/schema.json`:
**Auth modules** (9 files): auth0, better-auth, clerk, cloud, firebase,
okta, studio, supabase, workos
**Client SDKs** (3 files): ai-sdk, client-js, react
**Deployers** (2 files): cloud, vercel
**Integrations** (3 files): brightdata, opencode, perplexity, tavily
**Observability** (11 files): arize, braintrust, datadog, laminar,
langfuse, langsmith, mastra, otel-bridge, otel-exporter, posthog, sentry
**Package modules** (19 files): _external-types, _internal-core,
agent-builder, auth, cli, codemod, core, create-mastra, deployer, evals,
fastembed, loggers, mcp, mcp-docs-server, mcp-registry-registry, memory,
playground, rag, schema-compat, server
**Data stores** (21 files): astra, chroma, clickhouse, cloudflare,
cloudflare-d1, convex, couchbase, duckdb, dynamodb, elasticsearch,
lance, libsql, mongodb, mssql, mysql, opensearch, pg, pinecone, qdrant,
redis, s3vectors, spanner, turbopuffer, upstash, vectorize
**Root configuration**: turbo.json
All other configuration content (extends, tasks, inputs/outputs) remains
unchanged across all files.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
## Description
This PR enables metadata-only queries for vector stores that support
them.
- Makes `queryVector` optional in the `QueryVectorParams` interface.
- Implements full metadata-only query support in **PgVector**:
- Allows querying by `filter` without providing an embedding.
- Returns results with `score: 0` since no similarity is computed.
- Validates that at least one of `queryVector` or `filter` is provided.
- Keeps the existing similarity search path unchanged.
- Adds explicit guards in the other 15 vector stores to throw:
`"Metadata-only queries are not supported by this vector store"` when
`queryVector` is omitted.
- Fixes documentation bug where `query()` parameter was incorrectly
named `vector` instead of `queryVector` in `pg.mdx` and `pinecone.mdx`.
- Marks `queryVector` as optional in `pg.mdx`.
Includes 9 new PgVector integration tests covering:
- Simple and complex metadata filters
- `topK` handling
- `includeVector` behavior
- Proper error cases
- Regression check for combined `queryVector + filter`
## Related Issue(s)
Fixes#13188
## Type of Change
- [ ] Bug fix (non-breaking change that fixes an issue)
- [x] New feature (non-breaking change that adds functionality)
- [ ] Breaking change (fix or feature that would cause existing
functionality to change)
- [x] Documentation update
- [ ] Code refactoring
- [ ] Performance improvement
- [x] Test update
## Checklist
- [x] I have made corresponding changes to the documentation (if
applicable)
- [x] I have added tests that prove my fix is effective or that my
feature works
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit
* **New Features**
* PostgreSQL vector store: support metadata-only queries using filters
without a query vector.
* **Improvements**
* Docs: parameter renamed to "queryVector" and usage clarified.
* Many vector stores now return clear, consistent user-facing errors
when a query vector is required.
* **Tests**
* Added metadata-only query tests for the PostgreSQL vector store.
* **Chores**
* Package version bumps.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
---------
Signed-off-by: intojhanurag <aojharaj2004@gmail.com>
Co-authored-by: NikAiyer <nick.aiyer@gmail.com>
## Summary
- Moved docs generation from build-time to pack-time using npm's
`prepack` lifecycle hook across all 46 packages that embed documentation
into their dist
- Removed the `build:docs` turbo task and `build:package-docs` root
script entirely
- Made `generate-package-docs.ts` exit gracefully when the docs manifest
is missing
No changeset required
## Motivation
The `build:docs` task in each package depends on `mastra-docs#build` (a
full Docusaurus site build), which in turn runs `git log` for the
sitemap plugin. This meant:
1. Every `pnpm build` required a git repository — builds failed outside
of git repos (in sandboxes)
2. Every package depending on `@mastra/core` transitively triggered a
full docs site build — e.g., `build:observability` pulled in the entire
Docusaurus build via `@mastra/core#build` → `build:docs` →
`mastra-docs#build`
3. Dev builds were slower than necessary — compiling docs that are only
needed at publish time
### What changed
* **`package.json` (46 files across packages/, stores/, voice/,
client-sdks/)**
Replaced `build:docs` (or `postbuild` in voice packages) with `prepack`,
so docs generation only runs during `npm pack`/`npm publish` — never
during regular builds.
Before (packages/stores):
```
"build:docs": "pnpx tsx ../../scripts/generate-package-docs.ts"
```
Before (voice packages):
```
"postbuild": "pnpx tsx ../../scripts/generate-package-docs.ts"
```
Before (CLI — embedded in build:lib):
```
"build:lib": "tsup --silent --config tsup.config.ts && pnpx tsx
../../scripts/generate-package-docs.ts"
```
After (all packages):
```
"prepack": "pnpx tsx ../../scripts/generate-package-docs.ts"
```
* **`turbo.json` (34 files — root + 33 packages)**
Removed the `build:docs` task definition entirely. It's no longer a
turbo task — docs generation is handled by the npm `prepack` lifecycle
instead.
* **`package.json` (root)**
Removed:
```
"build:package-docs": "pnpm turbo run build:docs"
```
* **`.github/workflows/npm-publish.yml`**
Removed all `pnpm build:package-docs` steps from prerelease, stable, and
exit-prerelease-mode flows. No longer needed — `prepack` fires
automatically during `pnpm publish -r`.
* **`scripts/generate-package-docs.ts`**
Changed error handling to exit gracefully (warn instead of crash) when
`docs/build/llms-manifest.json` is missing. This ensures `prepack`
doesn't block packaging when the docs site hasn't been built (e.g.,
local development, snapshots).
## Test plan
- Verify `pnpm build` succeeds without triggering docs generation
- Verify `pnpm pack` in a package with the docs site built generates
embedded docs via `prepack`
- Verify `pnpm pack` without the docs site built warns but doesn't fail
- Verify CI publish workflows still produce packages with embedded docs
(prepack fires during `pnpm publish -r`)
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit
* **Chores**
* Docs generation now runs automatically during package preparation
(prepack) instead of as part of the main build.
* Removed separate docs build tasks to simplify and streamline build
dependency graphs across packages.
* **Bug Fixes**
* Improved docs generator error handling: failures fail CI but surface
as warnings locally to avoid blocking development.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
## Summary
This PR reorganizes the test infrastructure across the monorepo by
introducing namespaced Vitest projects, proper test classification, and
a dedicated e2e CI job.
### Vitest project namespacing
- Rename all vitest project names from generic `'unit'` to
`'unit:<package-path>'` (e.g. `'unit:packages/core'`,
`'unit:auth/auth0'`) across ~100 packages
- Enables targeted test filtering with `--project 'unit:*'` glob
patterns in CI and locally
- Update CI workflow to use `'unit:*'` and `'typecheck:*'` patterns
### Test classification
- **Store tests** → `e2e:stores/*` (require external services like
Postgres, Redis, etc.)
- **RAG tests** → `e2e:packages/rag` (require embeddings API)
- **Evals LLM scorer tests** → `e2e:packages/evals` (require LLM API
keys)
- **pubsub tests** → `e2e:pubsub/*` (require Google Cloud)
- Add `isolate: false` to unit test configs for faster execution
### Core test reorganization
Split `agent.test.ts` (~7.5k lines) into focused unit test modules:
- `callbacks.test.ts` — callback/hook behavior
- `input-processors.test.ts` — input processing logic
- `instructions.test.ts` — instruction/system prompt handling
- `memory-metadata.test.ts` — memory metadata tests
- `save-and-errors.test.ts` — save behavior and error handling
- `title-generation.test.ts` — title generation logic
Renamed integration tests to `*.e2e.test.ts` for clarity (e.g.
`azure.integration.test.ts` → `azure.e2e.test.ts`).
### CI changes
- Add dedicated `e2e-test` job in `vitest-changed.yml` with shard-based
matrix
- Normalize shard names (`/` → `-`) for GitHub artifact compatibility
- Wire e2e job into `merge-reports` dependency chain
### Test fixes
- `tsx` → `tsx@latest` in MCP spawn calls to fix version resolution
- Rewrite `deployers/cloud` mock patterns for test reliability
- Skip network-dependent `mcp-registry-registry` tests (apitracker,
mcprun)
- Fix codemod `typeParameters` compatibility check
- Add `cwd` to CLI execa call
### Test plan
- Verified `pnpm vitest run --project 'unit:*'` runs only unit tests
- Verified `pnpm vitest run --project 'e2e:*'` runs only e2e tests
- Verified all extracted agent test files pass independently
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit
* **Tests**
* Added comprehensive test suites for agent features including
callbacks, input processors, instructions, memory handling, and title
generation across v1 and v2 implementations
* Reorganized test infrastructure with dedicated end-to-end test
workflows separate from unit tests
* Enhanced test isolation and parallel execution with named test
projects
* **Chores**
* Restructured test configuration across all packages for improved
organization and execution
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
---------
Co-authored-by: Claude <noreply@anthropic.com>
Co-authored-by: Mastra Code <noreply@mastra.ai>
## Description
Improve the `generate-package-docs.ts` script by using the new
`llms-manifest.json` from docs to copy over llms.txt files to the
embedded docs (previously the raw MDX was parsed and assembled).
This PR also updates the script to be run without any cli args, it just
runs in the current `process.cwd()` context. This simplifies usage when
running via `npm` scripts. This PR also improves the performance of the
`SOURCE_MAP.json` generation by 2x.
Lastly, the `dist/docs` structure itself is updated to follow the agent
skills spec.
## Related Issue(s)
<!-- Link to the issue(s) this PR addresses, using hashtag notation:
Fixes#123 -->
## Type of Change
- [ ] Bug fix (non-breaking change that fixes an issue)
- [ ] New feature (non-breaking change that adds functionality)
- [ ] Breaking change (fix or feature that would cause existing
functionality to change)
- [ ] Documentation update
- [X] Code refactoring
- [ ] Performance improvement
- [ ] Test update
## Checklist
- [ ] I have made corresponding changes to the documentation (if
applicable)
- [ ] I have added tests that prove my fix is effective or that my
feature works
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit
* **Refactor**
* Docs generation moved to a centralized, manifest-driven workflow;
package-level doc scripts simplified to rely on contextual discovery and
a central docs build.
* Build tasks updated across packages to depend on the centralized docs
build step.
* **Documentation**
* Replaced a lengthy proposal with a concise Turbo-focused guide and
added optional description metadata for doc entries.
* **Bug Fix**
* Removed noisy console warnings during docs site initialization.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->