{"_id":"@caleblawson/mongodb","name":"@caleblawson/mongodb","dist-tags":{"latest":"0.11.1-alpha.0"},"versions":{"0.11.1-alpha.0":{"name":"@caleblawson/mongodb","version":"0.11.1-alpha.0","description":"MongoDB provider for Mastra - includes vector store capabilities","type":"module","main":"dist/index.js","types":"dist/index.d.ts","exports":{".":{"import":{"types":"./dist/index.d.ts","default":"./dist/index.js"},"require":{"types":"./dist/index.d.cts","default":"./dist/index.cjs"}},"./package.json":"./package.json"},"dependencies":{"@types/mongodb":"^4.0.7","cloudflare":"^4.3.0","mongodb":"^6.17.0","uuid":"^11.1.0"},"devDependencies":{"@microsoft/api-extractor":"^7.52.8","@types/node":"^20.19.0","eslint":"^9.28.0","tsup":"^8.5.0","typescript":"^5.8.3","vitest":"^3.2.3","@mastra/core":"npm:@caleblawson/core@0.10.7-alpha.0","@internal/lint":"0.0.13","@internal/storage-test-utils":"0.0.9"},"peerDependencies":{"@mastra/core":">=0.10.4-0 <0.11.0"},"scripts":{"build":"tsup src/index.ts --format esm,cjs --experimental-dts --clean --treeshake=smallest --splitting","build:watch":"pnpm build --watch","pretest":"docker compose up -d --wait","test":"vitest run","posttest":"docker compose down -v","pretest:watch":"docker compose up -d","test:watch":"vitest watch","posttest:watch":"docker compose down -v","lint":"eslint ."},"gitHead":"c31e90130a5c9765c23f688ecea70adc6164543d","_id":"@caleblawson/mongodb@0.11.1-alpha.0","_integrity":"sha512-gocVinswALjqNS+3rJ3GMWP5Vq07niR/G0d2XS4ytl/kSMJA6J37PomDHCUtbPNe0zKqkdmQZ2QYrjK5TzWHuA==","_resolved":"C:\\Users\\caleb\\AppData\\Local\\Temp\\c22bb8548e926ff7138921e0d2bff435\\caleblawson-mongodb-0.11.1-alpha.0.tgz","_from":"file:caleblawson-mongodb-0.11.1-alpha.0.tgz","_nodeVersion":"21.2.0","_npmVersion":"10.2.3","dist":{"integrity":"sha512-gocVinswALjqNS+3rJ3GMWP5Vq07niR/G0d2XS4ytl/kSMJA6J37PomDHCUtbPNe0zKqkdmQZ2QYrjK5TzWHuA==","shasum":"7b7419742ec4a0e92a72810a6f7f07f12eb70e6f","tarball":"https://registry.npmjs.org/@caleblawson/mongodb/-/mongodb-0.11.1-alpha.0.tgz","fileCount":23,"unpackedSize":243288,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQDUOEiT73Rf1EtSvcVfGg4KM9ot1gmxqYddyw+/bNsndQIhAK4oh+p2T7JMKmhEXEabv811IDkfUtA6xdDRHk75FuLN"}]},"_npmUser":{"name":"caleblawson","email":"caleb.lawson@dynapt.com","actor":{"name":"caleblawson","email":"caleb.lawson@dynapt.com","type":"user"}},"directories":{},"maintainers":[{"name":"caleblawson","email":"caleb.lawson@dynapt.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/mongodb_0.11.1-alpha.0_1750619817981_0.4605456774777734"},"_hasShrinkwrap":false}},"time":{"created":"2025-06-22T19:16:57.888Z","0.11.1-alpha.0":"2025-06-22T19:16:58.165Z","modified":"2025-06-22T19:16:58.422Z"},"maintainers":[{"name":"caleblawson","email":"caleb.lawson@dynapt.com"}],"description":"MongoDB provider for Mastra - includes vector store capabilities","readme":"# @mastra/mongodb\r\n\r\nMongoDB Atlas Search implementation for Mastra, providing vector similarity search and index management using MongoDB Atlas Local or Atlas Cloud.\r\n\r\n## Installation\r\n\r\n```bash\r\nnpm install @mastra/mongodb\r\n```\r\n\r\n## Prerequisites\r\n\r\n- MongoDB Atlas Local (via Docker) or MongoDB Atlas Cloud instance with Atlas Search enabled\r\n- MongoDB 7.0+ recommended\r\n\r\n## Usage\r\n\r\n### Vector Store\r\n\r\n```typescript\r\nimport { MongoDBVector } from '@mastra/mongodb';\r\n\r\nconst vectorDB = new MongoDBVector({\r\n  uri: 'mongodb://mongodb:mongodb@localhost:27018/?authSource=admin&directConnection=true',\r\n  dbName: 'vector_db',\r\n});\r\n\r\n// Connect to MongoDB\r\nawait vectorDB.connect();\r\n\r\n// Create a new vector index (collection)\r\nawait vectorDB.createIndex({\r\n  indexName: 'my_vectors',\r\n  dimension: 1536,\r\n  metric: 'cosine', // or 'euclidean', 'dotproduct'\r\n});\r\n\r\n// Upsert vectors\r\nconst ids = await vectorDB.upsert({\r\n  indexName: 'my_vectors',\r\n  vectors: [[0.1, 0.2, ...], [0.3, 0.4, ...]],\r\n  metadata: [{ text: 'doc1' }, { text: 'doc2' }],\r\n});\r\n\r\n// Query vectors\r\nconst results = await vectorDB.query({\r\n  indexName: 'my_vectors',\r\n  queryVector: [0.1, 0.2, ...],\r\n  topK: 10,\r\n  filter: { text: 'doc1' },\r\n  includeVector: false,\r\n  minScore: 0.5,\r\n});\r\n\r\n// Clean up\r\nawait vectorDB.disconnect();\r\n```\r\n\r\n### Storage\r\n\r\n```typescript\r\nimport { MongoDBStore } from '@mastra/mongodb';\r\n\r\nconst store = new MongoDBStore({\r\n  uri: 'mongodb://mongodb:mongodb@localhost:27018/?authSource=admin&directConnection=true',\r\n  dbName: 'mastra',\r\n});\r\n\r\n// Create a thread\r\nawait store.saveThread({\r\n  id: 'thread-123',\r\n  resourceId: 'resource-456',\r\n  title: 'My Thread',\r\n  metadata: { key: 'value' },\r\n});\r\n\r\n// Add messages to thread\r\nawait store.saveMessages([\r\n  {\r\n    id: 'msg-789',\r\n    threadId: 'thread-123',\r\n    role: 'user',\r\n    type: 'text',\r\n    content: [{ type: 'text', text: 'Hello' }],\r\n  },\r\n]);\r\n\r\n// Query threads and messages\r\nconst savedThread = await store.getThread('thread-123');\r\nconst messages = await store.getMessages('thread-123');\r\n```\r\n\r\n## Configuration\r\n\r\nThe MongoDB vector store is initialized with:\r\n\r\n- `uri`: MongoDB connection string (with credentials and options)\r\n- `dbName`: Name of the database to use\r\n\r\nExample:\r\n\r\n```typescript\r\nconst vectorDB = new MongoDBVector({\r\n  uri: 'mongodb://mongodb:mongodb@localhost:27018/?authSource=admin&directConnection=true',\r\n  dbName: 'vector_db',\r\n});\r\n```\r\n\r\n## Features\r\n\r\n### Vector Store Features\r\n\r\n- Vector similarity search with cosine, euclidean, and dotproduct metrics (Atlas Search)\r\n- Metadata filtering with MongoDB-style query syntax\r\n- Minimum score threshold for queries\r\n- Automatic UUID generation for vectors\r\n- Collection (index) management: create, list, describe, delete\r\n- Atlas Search readiness checks for reliable testing\r\n\r\n### Storage Features\r\n\r\n- Thread and message storage with JSON support\r\n- Efficient batch operations\r\n- Rich metadata support\r\n- Timestamp tracking\r\n\r\n## Supported Filter Operators\r\n\r\n- Comparison: `$eq`, `$ne`, `$gt`, `$gte`, `$lt`, `$lte`\r\n- Logical: `$and`, `$or`\r\n- Array: `$in`, `$nin`\r\n- Text: `$regex`, `$like`\r\n\r\nExample filter:\r\n\r\n```typescript\r\n{\r\n  $and: [{ age: { $gt: 25 } }, { tags: { $in: ['tag1', 'tag2'] } }];\r\n}\r\n```\r\n\r\n## Distance Metrics\r\n\r\nThe following distance metrics are supported:\r\n\r\n- `cosine` → Cosine similarity (default)\r\n- `euclidean` → Euclidean distance\r\n- `dotproduct` → Dot product\r\n\r\n## Vector Store Methods\r\n\r\n- `createIndex({indexName, dimension, metric})`: Create a new collection with vector search support\r\n- `upsert({indexName, vectors, metadata?, ids?})`: Add or update vectors\r\n- `query({indexName, queryVector, topK?, filter?, includeVector?, minScore?, documentFilter?})`: Search for similar vectors (optionally filter by document content)\r\n\r\n> **Note:** `documentFilter` allows filtering results based on the content of the `document` field. Example: `{ $contains: 'specific text' }` will return only vectors whose associated document contains the specified text.\r\n\r\n- `listIndexes()`: List all vector-enabled collections\r\n- `describeIndex(indexName)`: Get collection statistics (dimension, count, metric)\r\n- `updateIndexById(indexName, id, { vector?, metadata? })`: Update a vector and/or its metadata by ID\r\n- `deleteIndexById(indexName, id)`: Delete a vector by ID\r\n- `deleteIndex(indexName)`: Delete a collection\r\n- `disconnect()`: Close the MongoDB connection\r\n\r\n## Storage Methods\r\n\r\n- `saveThread(thread)`: Create or update a thread\r\n- `getThread(threadId)`: Get a thread by ID\r\n- `deleteThread(threadId)`: Delete a thread and its messages\r\n- `saveMessages(messages)`: Save multiple messages in a transaction\r\n- `getMessages(threadId)`: Get all messages for a thread\r\n- `deleteMessages(messageIds)`: Delete specific messages\r\n\r\n## Query Response Format\r\n\r\nEach query result includes:\r\n\r\n- `id`: Vector ID\r\n- `score`: Similarity score (higher is more similar)\r\n- `metadata`: Associated metadata\r\n- `vector`: Original vector (if `includeVector` is true)\r\n\r\n## Testing\r\n\r\nIntegration tests use MongoDB Atlas Local via Docker. See `docker-compose.yml` for setup. The test suite includes readiness checks for Atlas Search before running vector operations.\r\n\r\n## Related Links\r\n\r\n- [MongoDB Atlas Search Documentation](https://www.mongodb.com/docs/atlas/atlas-search/)\r\n- [MongoDB Node.js Driver](https://mongodb.github.io/node-mongodb-native/)\r\n","readmeFilename":"README.md","_rev":"1-ba17bfa93fc837c411ff0d22a8706511"}