@mastra/elasticsearch 1.3.1 → 1.4.0

package/CHANGELOG.md

@@ -1,5 +1,27 @@
 # @mastra/elasticsearch
 
+## 1.4.0
+
+### Minor Changes
+
+- Added ElasticSearchStore, an Elasticsearch storage adapter that implements the memory, workflows, and scores storage domains. It shares the same connection config as ElasticSearchVector ({ id, client } or { id, url, auth }), so one Elasticsearch cluster can now power agent memory, workflow snapshots, scores, and semantic recall. See https://github.com/mastra-ai/mastra/issues/21757 ([#22269](https://github.com/mastra-ai/mastra/pull/22269))
+
+### Patch Changes
+
+- Updated dependencies [[`79f04a7`](https://github.com/mastra-ai/mastra/commit/79f04a7f6c6829da541139f638f2f1d267916e08), [`65edab1`](https://github.com/mastra-ai/mastra/commit/65edab1c233d17b8f163bad12fca410d0e6f16b1), [`1e47b75`](https://github.com/mastra-ai/mastra/commit/1e47b7520cab4cfaa8daed52f17e2e6d14ff7539), [`ab20a38`](https://github.com/mastra-ai/mastra/commit/ab20a38d0275f8d85e0f3833bd87ef487bcc609f), [`fd4d5fe`](https://github.com/mastra-ai/mastra/commit/fd4d5fe4f943699b85db5e74404f190d5a6b8c2a), [`ae8790c`](https://github.com/mastra-ai/mastra/commit/ae8790c4bfaa088d2ab279d1dcc06f326b9fd109), [`2c85f42`](https://github.com/mastra-ai/mastra/commit/2c85f428e04ccd63ea31a7ec80b5b327afdad555), [`11bbeb9`](https://github.com/mastra-ai/mastra/commit/11bbeb9b108ef2264e05acefc6dafb9cbb342921), [`48ef1f1`](https://github.com/mastra-ai/mastra/commit/48ef1f1d24eedafbb07f64e659a81b52b67b8bf6), [`aa3a85d`](https://github.com/mastra-ai/mastra/commit/aa3a85daf094c683bb97efdf4b6a696d2e474af5), [`d29d06f`](https://github.com/mastra-ai/mastra/commit/d29d06fe00bbd35b4571150ea04c59d2ed783c71), [`e6516df`](https://github.com/mastra-ai/mastra/commit/e6516dfcdae4f4ac0e7971d84359a81385ee602f), [`1a485f3`](https://github.com/mastra-ai/mastra/commit/1a485f3538f5ec64d58bd8b5e1e99de0c695c87b), [`0d37487`](https://github.com/mastra-ai/mastra/commit/0d37487d9f349388a3f1cef6a536cf9dcc4b6273), [`8661d7d`](https://github.com/mastra-ai/mastra/commit/8661d7d7179f0a024456aabdd8679bcecd09ac28), [`dbbfeb8`](https://github.com/mastra-ai/mastra/commit/dbbfeb85ec949dc9ebc0755e1ad262e4f5eba8db), [`575e343`](https://github.com/mastra-ai/mastra/commit/575e343900451021d96110916497d334af7bc252), [`0b2a3d1`](https://github.com/mastra-ai/mastra/commit/0b2a3d1783875c5b97b7b36ab3d03d7360e0dde7), [`6bb5d71`](https://github.com/mastra-ai/mastra/commit/6bb5d7193fe9166b219f0fccae17db7a5ae86e65), [`3cc9d00`](https://github.com/mastra-ai/mastra/commit/3cc9d00b2b4333e0377a5e9df5eff92c17ce7630), [`cacb839`](https://github.com/mastra-ai/mastra/commit/cacb8392d9e74189b56d857290b0615f98a2683d), [`57de7d6`](https://github.com/mastra-ai/mastra/commit/57de7d644ba7146edb4e9e6111ec4fa98c3a59e9), [`c8e4cea`](https://github.com/mastra-ai/mastra/commit/c8e4ceac9a390d78c8327dff3cdb2861dd71957f), [`ed01e9a`](https://github.com/mastra-ai/mastra/commit/ed01e9a807514a904374bf687a7b8f18750f6f78), [`b47b26e`](https://github.com/mastra-ai/mastra/commit/b47b26e6fe95cb8a3482be2c5e52de157fe59d0b), [`0d37487`](https://github.com/mastra-ai/mastra/commit/0d37487d9f349388a3f1cef6a536cf9dcc4b6273), [`733a537`](https://github.com/mastra-ai/mastra/commit/733a537489a858b5880b2e98809334fba895a221), [`e8e299c`](https://github.com/mastra-ai/mastra/commit/e8e299cc6abdfc39947e2fec25803493015d3882), [`edfc548`](https://github.com/mastra-ai/mastra/commit/edfc548886bc7bae17b681f8b6b41a47eb32bcd2), [`b05f486`](https://github.com/mastra-ai/mastra/commit/b05f48612984d5fe2447ea2d6cdd5c604d285b97), [`a8a4871`](https://github.com/mastra-ai/mastra/commit/a8a4871215f51da95c47129602157ce5372f634a), [`eb9ecaa`](https://github.com/mastra-ai/mastra/commit/eb9ecaa89c36e889749e3b825cfc507ce7f7980b), [`4ff3ee2`](https://github.com/mastra-ai/mastra/commit/4ff3ee2bff7ed07528b4817f8f49639031c72a4d), [`9207dfa`](https://github.com/mastra-ai/mastra/commit/9207dfab8062e5fc68b751684797ff86fe0b4e70), [`5165cdc`](https://github.com/mastra-ai/mastra/commit/5165cdcdcf50e144bb8113278535196cc9b07065), [`e737014`](https://github.com/mastra-ai/mastra/commit/e737014e0fc7035759762bb5b48baef1d6c0f6a7), [`6bb5d71`](https://github.com/mastra-ai/mastra/commit/6bb5d7193fe9166b219f0fccae17db7a5ae86e65), [`f591643`](https://github.com/mastra-ai/mastra/commit/f591643becdf0be9bddce6ba1748e64bc30d77f1), [`63796ba`](https://github.com/mastra-ai/mastra/commit/63796ba0fda60253be17535e68f6bbbf1e6ffa09), [`b1ad324`](https://github.com/mastra-ai/mastra/commit/b1ad324d657f3544b0701332aef7eb10e9a36258), [`61c566d`](https://github.com/mastra-ai/mastra/commit/61c566dd2f2cde2b23ed8f139924e530d4202214), [`c24754c`](https://github.com/mastra-ai/mastra/commit/c24754c1fb6fe144e5051e536e98c8a18b0214ac), [`12c61d2`](https://github.com/mastra-ai/mastra/commit/12c61d280c8cb208bc3c8dbcbe5dcc60cf9d1cd0), [`c46eb09`](https://github.com/mastra-ai/mastra/commit/c46eb09ce4987509af57a0ac582c61241a6dd2f1), [`9ee8120`](https://github.com/mastra-ai/mastra/commit/9ee8120ce17f76b9f617489e05a283353742690a), [`d975e92`](https://github.com/mastra-ai/mastra/commit/d975e924d4936f46c386bd3dee39c671720289f6), [`45dd6ee`](https://github.com/mastra-ai/mastra/commit/45dd6ee089bd7df0d0c98a10098e483fd388e04a), [`4e9a228`](https://github.com/mastra-ai/mastra/commit/4e9a2283d5fd6ed1b70a2751eb3dc2cbf82ada20), [`d6ce34a`](https://github.com/mastra-ai/mastra/commit/d6ce34aeceb06ddf3d595a1eed5cc74f481a46a1), [`f95f468`](https://github.com/mastra-ai/mastra/commit/f95f468cf1e7c2b924a13826494f98b8f2ccd581), [`30ed33e`](https://github.com/mastra-ai/mastra/commit/30ed33ee14084a26019aba15fceadda6d6ddefaf), [`04a815f`](https://github.com/mastra-ai/mastra/commit/04a815fc8971d29e97fcdcc5008a1eb472fc00ff), [`1cfa878`](https://github.com/mastra-ai/mastra/commit/1cfa8784d8da0dfaa0317e5048bc48b6084a5ea5), [`9a12ef3`](https://github.com/mastra-ai/mastra/commit/9a12ef3fccf3f4186db0f294f4ee1f02cf4d8db2), [`32d3583`](https://github.com/mastra-ai/mastra/commit/32d358332cb8ac2306b83b73cf3536e74dbd435e), [`7960688`](https://github.com/mastra-ai/mastra/commit/7960688828e04eaf3106e34f7758fa580257eef6), [`91ad69d`](https://github.com/mastra-ai/mastra/commit/91ad69d64994c89199b0c55399e64ed91c61df2f), [`8dc408d`](https://github.com/mastra-ai/mastra/commit/8dc408d34438f9e13297f792c11a5cfd6cf952e1), [`c92def1`](https://github.com/mastra-ai/mastra/commit/c92def10a13c822972c96f0a4ca6ffc1f4258aed), [`63041eb`](https://github.com/mastra-ai/mastra/commit/63041eb4c50b520a0a80e03d4cd6ea99f67715a0), [`c118318`](https://github.com/mastra-ai/mastra/commit/c1183181c9804303db4b511c2e2648f8b714712b), [`c5eaec5`](https://github.com/mastra-ai/mastra/commit/c5eaec5a860d80d0e3805e67db0414b87ac8cbed), [`fc07c64`](https://github.com/mastra-ai/mastra/commit/fc07c6465043e08e99193a6751a01c56ffc2e7a1), [`cced745`](https://github.com/mastra-ai/mastra/commit/cced745a056ec2225c5bc702e32d848847aa8b65), [`542dee2`](https://github.com/mastra-ai/mastra/commit/542dee254167f974ff8cbbbfc0ce10f9a2616a7b), [`3c19dce`](https://github.com/mastra-ai/mastra/commit/3c19dcef8e73062a80627a4927eae3ec11145afd), [`aca2869`](https://github.com/mastra-ai/mastra/commit/aca2869b2031982f3c4a2f52525c9be7cf123ef8), [`a58483c`](https://github.com/mastra-ai/mastra/commit/a58483cff1a9d41fce7c931843f48cb0ac450f64), [`a58483c`](https://github.com/mastra-ai/mastra/commit/a58483cff1a9d41fce7c931843f48cb0ac450f64), [`e6f8450`](https://github.com/mastra-ai/mastra/commit/e6f845074d478527026b18d85031b23353e1d0a4), [`895e9df`](https://github.com/mastra-ai/mastra/commit/895e9dfc17d6f34299eca64e317ded9e5f5e5ef8), [`e66b2ba`](https://github.com/mastra-ai/mastra/commit/e66b2ba100db63eaeab6e21e1ea34b113f2ec781), [`3e8727e`](https://github.com/mastra-ai/mastra/commit/3e8727e11ec1a5d733acedb5c872896394be18c1)]:
+  - @mastra/core@1.62.0
+
+## 1.4.0-alpha.0
+
+### Minor Changes
+
+- Added ElasticSearchStore, an Elasticsearch storage adapter that implements the memory, workflows, and scores storage domains. It shares the same connection config as ElasticSearchVector ({ id, client } or { id, url, auth }), so one Elasticsearch cluster can now power agent memory, workflow snapshots, scores, and semantic recall. See https://github.com/mastra-ai/mastra/issues/21757 ([#22269](https://github.com/mastra-ai/mastra/pull/22269))
+
+### Patch Changes
+
+- Updated dependencies [[`aa3a85d`](https://github.com/mastra-ai/mastra/commit/aa3a85daf094c683bb97efdf4b6a696d2e474af5), [`d29d06f`](https://github.com/mastra-ai/mastra/commit/d29d06fe00bbd35b4571150ea04c59d2ed783c71), [`e6516df`](https://github.com/mastra-ai/mastra/commit/e6516dfcdae4f4ac0e7971d84359a81385ee602f), [`0b2a3d1`](https://github.com/mastra-ai/mastra/commit/0b2a3d1783875c5b97b7b36ab3d03d7360e0dde7), [`6bb5d71`](https://github.com/mastra-ai/mastra/commit/6bb5d7193fe9166b219f0fccae17db7a5ae86e65), [`57de7d6`](https://github.com/mastra-ai/mastra/commit/57de7d644ba7146edb4e9e6111ec4fa98c3a59e9), [`e8e299c`](https://github.com/mastra-ai/mastra/commit/e8e299cc6abdfc39947e2fec25803493015d3882), [`edfc548`](https://github.com/mastra-ai/mastra/commit/edfc548886bc7bae17b681f8b6b41a47eb32bcd2), [`a8a4871`](https://github.com/mastra-ai/mastra/commit/a8a4871215f51da95c47129602157ce5372f634a), [`5165cdc`](https://github.com/mastra-ai/mastra/commit/5165cdcdcf50e144bb8113278535196cc9b07065), [`6bb5d71`](https://github.com/mastra-ai/mastra/commit/6bb5d7193fe9166b219f0fccae17db7a5ae86e65), [`9ee8120`](https://github.com/mastra-ai/mastra/commit/9ee8120ce17f76b9f617489e05a283353742690a), [`d975e92`](https://github.com/mastra-ai/mastra/commit/d975e924d4936f46c386bd3dee39c671720289f6), [`1cfa878`](https://github.com/mastra-ai/mastra/commit/1cfa8784d8da0dfaa0317e5048bc48b6084a5ea5), [`c118318`](https://github.com/mastra-ai/mastra/commit/c1183181c9804303db4b511c2e2648f8b714712b), [`fc07c64`](https://github.com/mastra-ai/mastra/commit/fc07c6465043e08e99193a6751a01c56ffc2e7a1), [`542dee2`](https://github.com/mastra-ai/mastra/commit/542dee254167f974ff8cbbbfc0ce10f9a2616a7b), [`a58483c`](https://github.com/mastra-ai/mastra/commit/a58483cff1a9d41fce7c931843f48cb0ac450f64), [`a58483c`](https://github.com/mastra-ai/mastra/commit/a58483cff1a9d41fce7c931843f48cb0ac450f64), [`895e9df`](https://github.com/mastra-ai/mastra/commit/895e9dfc17d6f34299eca64e317ded9e5f5e5ef8)]:
+  - @mastra/core@1.62.0-alpha.8
+
 ## 1.3.1
 
 ### Patch Changes

package/dist/docs/SKILL.md

@@ -3,7 +3,7 @@ name: mastra-elasticsearch
 description: Documentation for @mastra/elasticsearch. Use when working with @mastra/elasticsearch APIs, configuration, or implementation.
 metadata:
   package: "@mastra/elasticsearch"
-  version: "1.3.1"
+  version: "1.4.0"
 ---
 
 ## When to use
@@ -14,12 +14,13 @@ Use this skill whenever you are working with @mastra/elasticsearch to obtain the
 
 Read the individual reference documents for detailed explanations and code examples.
 
-### Docs
+### Integrations
 
-- [Storing embeddings in a vector database](references/docs-rag-vector-databases.md) - Guide on vector storage options in Mastra, including embedded and dedicated vector databases for similarity search.
+- [Elasticsearch](references/integrations-databases-elasticsearch.md) - Documentation for the Elasticsearch storage implementation in Mastra.
 
 ### Reference
 
+- [Storing embeddings in a vector database](references/reference-rag-vector-databases.md) - Guide on vector storage options in Mastra, including embedded and dedicated vector databases for similarity search.
 - [Reference: Elasticsearch vector store](references/reference-vectors-elasticsearch.md) - Documentation for the ElasticSearchVector class in Mastra, which provides vector search using Elasticsearch.
 
 

package/dist/docs/assets/SOURCE_MAP.json

@@ -1,5 +1,5 @@
 {
-  "version": "1.3.1",
+  "version": "1.4.0",
   "package": "@mastra/elasticsearch",
   "exports": {},
   "modules": {}

package/dist/docs/references/integrations-databases-elasticsearch.md

@@ -0,0 +1,156 @@
+> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
+
+# Elasticsearch
+
+The Elasticsearch storage implementation provides agent memory, workflow snapshot, and score storage on top of an Elasticsearch cluster using the official [`@elastic/elasticsearch`](https://github.com/elastic/elasticsearch-js) client. It shares the same connection configuration as `ElasticSearchVector`, so a single cluster (and even a single client instance) can serve both agent memory and semantic recall.
+
+`ElasticSearchStore` currently implements the `memory`, `workflows`, and `scores` storage domains.
+
+## Installation
+
+```bash
+npm install @mastra/elasticsearch
+```
+
+## Usage
+
+### Using a URL
+
+```typescript
+import { ElasticSearchStore } from '@mastra/elasticsearch'
+
+const storage = new ElasticSearchStore({
+  id: 'elasticsearch-storage',
+  url: 'http://localhost:9200',
+})
+
+await storage.init()
+```
+
+### Using authentication
+
+```typescript
+import { ElasticSearchStore } from '@mastra/elasticsearch'
+
+const storage = new ElasticSearchStore({
+  id: 'elasticsearch-storage',
+  url: 'https://my-cluster.example.com:9200',
+  auth: { apiKey: process.env.ELASTICSEARCH_API_KEY! },
+})
+```
+
+`auth` also accepts `{ username, password }` or `{ bearer }`.
+
+### Using a pre-configured client
+
+For advanced configurations (cloud IDs, TLS options, custom transport), pass a pre-configured client. The same client can be shared with `ElasticSearchVector`:
+
+```typescript
+import { Client } from '@elastic/elasticsearch'
+import { ElasticSearchStore, ElasticSearchVector } from '@mastra/elasticsearch'
+
+const client = new Client({
+  node: 'https://my-cluster.example.com:9200',
+  auth: { apiKey: process.env.ELASTICSEARCH_API_KEY! },
+})
+
+const storage = new ElasticSearchStore({ id: 'elasticsearch-storage', client })
+const vector = new ElasticSearchVector({ id: 'elasticsearch-vector', client })
+```
+
+When you provide your own client, `storage.close()` does not close it — you remain responsible for its lifecycle.
+
+## Parameters
+
+**id** (`string`): Unique identifier for the storage instance
+
+**url** (`string`): Elasticsearch node URL (e.g., http\://localhost:9200)
+
+**auth** (`ElasticSearchAuth`): Authentication options: { apiKey }, { username, password }, or { bearer }
+
+**client** (`Client`): Pre-configured Elasticsearch client (from @elastic/elasticsearch) for advanced setups
+
+**disableInit** (`boolean`): Disable automatic initialization; call storage.init() explicitly before use
+
+> **Note:** You must provide either `url` or `client`. These options are mutually exclusive.
+
+## Additional Notes
+
+### Index Structure
+
+Each Mastra storage table maps to one Elasticsearch index of the same name (for example `mastra_threads`, `mastra_messages`, `mastra_workflow_snapshot`, `mastra_scorers`). Records are stored as opaque JSON documents with a keyword `key` field, so no index mappings need to be managed manually — indexes are created on first use.
+
+### Consistency
+
+Elasticsearch search is near-real-time. All writes are performed with an immediate refresh so subsequent reads and searches observe them, and point reads use real-time get-by-ID lookups.
+
+### Closing Connections
+
+When shutting down your application, close the connection:
+
+```typescript
+await storage.close()
+```
+
+This only closes clients created by `ElasticSearchStore` from a `url`; user-provided clients are left open.
+
+## Usage Example
+
+### Adding memory to an agent
+
+```typescript
+import { Memory } from '@mastra/memory'
+import { Agent } from '@mastra/core/agent'
+import { ElasticSearchStore } from '@mastra/elasticsearch'
+
+export const elasticsearchAgent = new Agent({
+  id: 'elasticsearch-agent',
+  name: 'Elasticsearch Agent',
+  instructions:
+    'You are an AI agent with the ability to automatically recall memories from previous interactions.',
+  model: 'openai/gpt-5.6-sol',
+  memory: new Memory({
+    storage: new ElasticSearchStore({
+      id: 'elasticsearch-agent-storage',
+      url: process.env.ELASTICSEARCH_URL!,
+      auth: { apiKey: process.env.ELASTICSEARCH_API_KEY! },
+    }),
+    options: {
+      lastMessages: 10,
+    },
+  }),
+})
+```
+
+### Using with Mastra instance
+
+```typescript
+import { Mastra } from '@mastra/core'
+import { ElasticSearchStore } from '@mastra/elasticsearch'
+
+const storage = new ElasticSearchStore({
+  id: 'mastra-storage',
+  url: 'http://localhost:9200',
+})
+
+const mastra = new Mastra({
+  storage, // init() called automatically
+})
+```
+
+If using storage directly without Mastra, call `init()` explicitly:
+
+```typescript
+import { ElasticSearchStore } from '@mastra/elasticsearch'
+
+const storage = new ElasticSearchStore({
+  id: 'elasticsearch-storage',
+  url: 'http://localhost:9200',
+})
+
+await storage.init()
+
+// Access domain-specific stores via getStore()
+const memoryStore = await storage.getStore('memory')
+const thread = await memoryStore?.getThreadById({ threadId: '...' })
+```

package/dist/docs/references/{docs-rag-vector-databases.md → reference-rag-vector-databases.md}

@@ -27,9 +27,9 @@ await store.upsert({
 })
 ```
 
-### Using MongoDB Atlas Vector Search
+### Using MongoDB Vector Search
 
-For detailed setup instructions and best practices, see the [official MongoDB Atlas Vector Search documentation](https://www.mongodb.com/docs/atlas/atlas-vector-search/vector-search-overview/?utm_campaign=devrel\&utm_source=third-party-content\&utm_medium=cta\&utm_content=mastra-docs).
+MongoDB Vector Search is a good solution for teams who want to consolidate vector search, full-text search, and operational data in a single database to minimize infrastructure complexity and maintain production-grade performance. For detailed setup instructions and best practices, see the [official MongoDB Vector Search documentation](https://www.mongodb.com/docs/atlas/atlas-vector-search/vector-search-overview/?utm_campaign=devrel\&utm_source=third-party-content\&utm_medium=cta\&utm_content=mastra-docs).
 
 ### Using VoyageAI with MongoDB
 
@@ -37,7 +37,7 @@ MongoDB works seamlessly with VoyageAI's embedding models, which are optimized f
 
 ### Hybrid Search (Vector + Full-Text)
 
-MongoDB supports hybrid search that fuses vector similarity with BM25 full-text search using server-side `$rankFusion` (requires MongoDB >= 8.0; generally available from 8.1, and enabled on Atlas 8.0.x). This is useful when you want to combine semantic and keyword-based retrieval:
+MongoDB supports hybrid search that fuses vector similarity with BM25 full-text search using server-side `$rankFusion` (requires MongoDB >= 8.0; generally available from 8.1, and enabled on MongoDB Atlas 8.0.x). This is useful when you want to combine semantic and keyword-based retrieval:
 
 ```ts
 await store.createSearchIndex({ indexName: 'myCollection', fields: ['text'] })
@@ -78,6 +78,35 @@ await store.upsert({
 
 PostgreSQL with the pgvector extension is a good solution for teams already using PostgreSQL who want to minimize infrastructure complexity. For detailed setup instructions and best practices, see the [official pgvector repository](https://github.com/pgvector/pgvector).
 
+**OracleDB**:
+
+```ts
+import { OracleVector } from '@mastra/oracledb'
+
+const store = new OracleVector({
+  id: 'oracle-vector',
+  user: process.env.ORACLE_DATABASE_USER,
+  password: process.env.ORACLE_DATABASE_PASSWORD,
+  connectString: process.env.ORACLE_DATABASE_CONNECT_STRING,
+})
+
+await store.createIndex({
+  indexName: 'myCollection',
+  dimension: 1536,
+  indexConfig: { type: 'none' },
+})
+
+await store.upsert({
+  indexName: 'myCollection',
+  vectors: embeddings,
+  metadata: chunks.map(chunk => ({ text: chunk.text })),
+})
+```
+
+### Using Oracle Database Vector Search
+
+OracleDB stores embeddings in native `VECTOR` columns and metadata in Oracle JSON. Exact search is the default; HNSW and IVF indexes can be configured for tuned deployments.
+
 **Pinecone**:
 
 ```ts
@@ -378,7 +407,7 @@ await store.createIndex({
 
 The dimension size must match the output dimension of your chosen embedding model. Common dimension sizes are:
 
-- `OpenAI text-embedding-3-small`: 1536 dimensions (or custom, e.g., 256)
+- OpenAI `text-embedding-3-small`: 1536 dimensions (or custom, e.g., 256)
 - `Cohere embed-multilingual-v3`: 1024 dimensions
 - `VoyageAI voyage-3.5`: 1024 dimensions (or custom: 256, 512, 1024, 2048)
 - `Google gemini-embedding-001`: 768 dimensions (or custom)
@@ -391,7 +420,7 @@ Each vector database enforces specific naming conventions for indexes and collec
 
 **MongoDB**:
 
-Collection (index) names must:
+Collection and index names must:
 
 - Start with a letter or underscore
 - Be up to 120 bytes long
@@ -410,6 +439,18 @@ Index names must:
 - Example: `my_index_123` is valid
 - Example: `my-index` is not valid (contains hyphen)
 
+**OracleDB**:
+
+Index names are logical Mastra names. OracleDB maps each logical index to a physical Oracle table internally.
+
+Logical index names must:
+
+- Be non-empty
+- Be 512 characters or fewer
+- Be stable for the lifetime of the vector index
+- Example: `my_collection_123` is valid
+- Example: `customer-support/docs:v1` is valid and is mapped to a safe Oracle table name
+
 **Pinecone**:
 
 Index names must: