Summary: [Mastra] Assess and document BYOC: search existing application data without maintaining a separate copy

TL;DR

Bring your own collection (BYOC) lets Mastra search data already stored in MongoDB, without copying it into a separate Mastra-managed collection or maintaining a synchronization job. Assess the existing feature for security and data safety, then document this simpler workflow and its benefits.

Context

Mastra is a TypeScript framework for building AI agents. Its MongoDB integration supports vector search: finding documents by meaning using numeric representations called embeddings.

Without BYOC, an application can copy its records and embeddings into a Mastra-managed collection. That introduces another copy to maintain: application updates and deletions must also reach the retrieval collection.

BYOC lets Mastra query the existing application collection instead. For developers already using MongoDB, this means:

• Less infrastructure: no separate data-copy and synchronization pipeline just for Mastra retrieval.
• Fewer consistency problems: no additional Mastra-managed copy that can fall behind application updates.
• Original document context: results can include the source record's fields, rather than only metadata selected when copying the data.

The value is not simply that MongoDB supports vector search. It is that developers can add agent retrieval where their application data already lives.

This capability was implemented in PR #19805. This ticket covers assessment and documentation, not reimplementation.

Desired User Experience

These examples compare two existing workflows. Assume a configured store, transaction documents containing 1,024-dimensional embeddings, and a compatible query vector. BYOC alone does not generate or refresh embeddings.

Before: maintain a separate retrieval copy

await store.createIndex({ indexName: 'precedents', dimension: 1024 })
await store.upsert({
  indexName: 'precedents',
  ids: transactions.map(t => String(t._id)),
  vectors: transactions.map(t => t.embedding),
  metadata: transactions.map(t => ({ note: t.note, lane: t.lane })),
})
// Application updates and deletions must also reach this copy.

With BYOC: search the existing collection

await store.createIndex({
  indexName: 'precedents',
  dimension: 1024,
  collectionName: 'transactions', // Search existing data; no separate copy.
  allowWrites: false, // Default: block document writes through the store.
})
await store.waitForIndexReady({ indexName: 'precedents' })

const hits = await store.query({
  indexName: 'precedents',
  queryVector: embedding,
  topK: 5,
  metadataMode: 'document', // Source document in metadata; embedding omitted.
  filter: { lane: 'fraud' }, // Match the original document's root fields.
})

Task

Goal: Make it clear when BYOC removes unnecessary data duplication and how to use it safely.

• Assess read-only defaults, explicit write opt-in, source-document exposure, and whether index lifecycle operations preserve application data. Record findings and any required follow-up work.
• Update the documentation with the comparison above, prerequisites, and safe-use guidance. Explain the concrete benefit without making unverified claims about other database backends.

Where:

• Mastra MongoDB vector-store reference
• Documentation source

Acceptance Criteria

• [ ] Assessment verifies that default document writes are blocked and removing a BYOC index preserves the source collection and documents.
• [ ] Security findings, sensitive-field exposure considerations, and any promotion blockers are recorded.
• [ ] Documentation shows how to search and filter an existing collection and retrieve source-document context without a separate copy.
• [ ] Guidance distinguishes avoiding data synchronization from maintaining embeddings, and explains write opt-in and safe index removal.