@mastra/oracledb 0.5.5 → 0.5.6

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -59,7 +59,7 @@ const { messages } = await memory.listMessages({ threadId: 'thread-123' });
59
59
  ## Documentation
60
60
 
61
61
  - [Oracle Database integration guide](https://mastra.ai/integrations/databases/oracledb)
62
- - [Oracle Database vector reference](https://mastra.ai/reference/vectors/oracledb)
62
+ - [Oracle Database vector reference](https://mastra.ai/integrations/vectors/oracledb)
63
63
 
64
64
  ## Changelog
65
65
 
@@ -3,7 +3,7 @@ name: mastra-oracledb
3
3
  description: Documentation for @mastra/oracledb. Use when working with @mastra/oracledb APIs, configuration, or implementation.
4
4
  metadata:
5
5
  package: "@mastra/oracledb"
6
- version: "0.5.5"
6
+ version: "0.5.6"
7
7
  ---
8
8
 
9
9
  ## When to use
@@ -24,6 +24,7 @@ Read the individual reference documents for detailed explanations and code examp
24
24
  ### Integrations
25
25
 
26
26
  - [OracleDB](references/integrations-databases-oracledb.md) - Persist Mastra memory, workflows, observability, scores, MCP metadata, and agent registry data in Oracle Database with OracleStore.
27
+ - [OracleDB](references/integrations-vectors-oracledb.md) - Store embeddings in Oracle Database VECTOR columns and filter by JSON metadata from Mastra, with each vector index mapped to a registered table.
27
28
 
28
29
  ### Reference
29
30
 
@@ -32,7 +33,6 @@ Read the individual reference documents for detailed explanations and code examp
32
33
  - [Retrieval, semantic search, reranking](references/reference-rag-retrieval.md) - After storing embeddings, you need to retrieve relevant chunks to answer user queries.
33
34
  - [Storing embeddings in a vector database](references/reference-rag-vector-databases.md) - After generating embeddings, you need to store them in a database that supports vector similarity search.
34
35
  - [Reference: Storage retention (prune)](references/reference-storage-retention.md) - prune() deletes rows. It caps growth and is safe to run against large tables (batched, bounded, resumable, cancellable).
35
- - [Reference: OracleDB vector store](references/reference-vectors-oracledb.md) - OracleVector stores embeddings in Oracle Database VECTOR columns and exposes them through Mastra's vector interface.
36
36
 
37
37
 
38
38
  Read [assets/SOURCE_MAP.json](assets/SOURCE_MAP.json) for source code references.
@@ -1,5 +1,5 @@
1
1
  {
2
- "version": "0.5.5",
2
+ "version": "0.5.6",
3
3
  "package": "@mastra/oracledb",
4
4
  "exports": {},
5
5
  "modules": {}
@@ -10,7 +10,33 @@ Observational Memory (OM) is Mastra's memory system for long-context agentic mem
10
10
 
11
11
  ## Quickstart
12
12
 
13
- Ensure you have `@mastra/memory` installed in your project. Set `observationalMemory: true` in your Memory config to enable Observational Memory.
13
+ Install `@mastra/memory` and a [storage adapter](https://mastra.ai/docs/storage). The examples below use `@mastra/libsql`, which stores data locally in a `memory.db` file.
14
+
15
+ **npm**:
16
+
17
+ ```bash
18
+ npm install @mastra/memory@latest @mastra/libsql@latest
19
+ ```
20
+
21
+ **pnpm**:
22
+
23
+ ```bash
24
+ pnpm add @mastra/memory@latest @mastra/libsql@latest
25
+ ```
26
+
27
+ **Yarn**:
28
+
29
+ ```bash
30
+ yarn add @mastra/memory@latest @mastra/libsql@latest
31
+ ```
32
+
33
+ **Bun**:
34
+
35
+ ```bash
36
+ bun add @mastra/memory@latest @mastra/libsql@latest
37
+ ```
38
+
39
+ Then set `observationalMemory: true` in your Memory config to enable Observational Memory.
14
40
 
15
41
  ```typescript
16
42
  import { Memory } from '@mastra/memory'
@@ -141,24 +141,24 @@ const agent = new Agent({
141
141
 
142
142
  Each vector store page below includes installation instructions, configuration parameters, and usage examples:
143
143
 
144
- - [Astra](https://mastra.ai/reference/vectors/astra)
145
- - [Chroma](https://mastra.ai/reference/vectors/chroma)
146
- - [Cloudflare Vectorize](https://mastra.ai/reference/vectors/vectorize)
147
- - [Convex](https://mastra.ai/reference/vectors/convex)
148
- - [Couchbase](https://mastra.ai/reference/vectors/couchbase)
149
- - [DuckDB](https://mastra.ai/reference/vectors/duckdb)
150
- - [Elasticsearch](https://mastra.ai/reference/vectors/elasticsearch)
151
- - [LanceDB](https://mastra.ai/reference/vectors/lance)
152
- - [libSQL](https://mastra.ai/reference/vectors/libsql)
153
- - [MongoDB](https://mastra.ai/reference/vectors/mongodb)
154
- - [OpenSearch](https://mastra.ai/reference/vectors/opensearch)
155
- - [OracleDB](https://mastra.ai/reference/vectors/oracledb)
156
- - [Pinecone](https://mastra.ai/reference/vectors/pinecone)
157
- - [PostgreSQL](https://mastra.ai/reference/vectors/pg)
158
- - [Qdrant](https://mastra.ai/reference/vectors/qdrant)
159
- - [S3 Vectors](https://mastra.ai/reference/vectors/s3vectors)
160
- - [Turbopuffer](https://mastra.ai/reference/vectors/turbopuffer)
161
- - [Upstash](https://mastra.ai/reference/vectors/upstash)
144
+ - [Astra](https://mastra.ai/integrations/vectors/astra)
145
+ - [Chroma](https://mastra.ai/integrations/vectors/chroma)
146
+ - [Cloudflare Vectorize](https://mastra.ai/integrations/vectors/vectorize)
147
+ - [Convex](https://mastra.ai/integrations/vectors/convex)
148
+ - [Couchbase](https://mastra.ai/integrations/vectors/couchbase)
149
+ - [DuckDB](https://mastra.ai/integrations/vectors/duckdb)
150
+ - [Elasticsearch](https://mastra.ai/integrations/vectors/elasticsearch)
151
+ - [LanceDB](https://mastra.ai/integrations/vectors/lance)
152
+ - [libSQL](https://mastra.ai/integrations/vectors/libsql)
153
+ - [MongoDB](https://mastra.ai/integrations/vectors/mongodb)
154
+ - [OpenSearch](https://mastra.ai/integrations/vectors/opensearch)
155
+ - [OracleDB](https://mastra.ai/integrations/vectors/oracledb)
156
+ - [Pinecone](https://mastra.ai/integrations/vectors/pinecone)
157
+ - [PostgreSQL](https://mastra.ai/integrations/vectors/pg)
158
+ - [Qdrant](https://mastra.ai/integrations/vectors/qdrant)
159
+ - [S3 Vectors](https://mastra.ai/integrations/vectors/s3vectors)
160
+ - [Turbopuffer](https://mastra.ai/integrations/vectors/turbopuffer)
161
+ - [Upstash](https://mastra.ai/integrations/vectors/upstash)
162
162
 
163
163
  ## Recall configuration
164
164
 
@@ -250,7 +250,7 @@ const options = {
250
250
 
251
251
  Some vector stores generate the embeddings themselves. With one of those, semantic recall runs without an `embedder`: the database embeds each message on write and the search string on arrival. The embedding provider stays out of your application entirely.
252
252
 
253
- MongoDB does this through [Automated Embedding](https://mastra.ai/reference/vectors/mongodb): name a Voyage AI model on the vector store and leave the `embedder` out.
253
+ MongoDB does this through [Automated Embedding](https://mastra.ai/integrations/vectors/mongodb): name a Voyage AI model on the vector store and leave the `embedder` out.
254
254
 
255
255
  ```typescript
256
256
  import { Memory } from '@mastra/memory'
@@ -435,6 +435,8 @@ When using PostgreSQL as your vector store, you can optimize semantic recall per
435
435
 
436
436
  PostgreSQL supports both IVFFlat and HNSW indexes. By default, Mastra creates an IVFFlat index, but HNSW indexes typically provide better performance, especially with OpenAI embeddings which use inner product distance.
437
437
 
438
+ Semantic recall always filters by thread or resource. PgVector uses the vector index for these searches only with HNSW on pgvector 0.8.0 or newer. With IVFFlat, each search compares the query against every message in the thread or resource.
439
+
438
440
  ```typescript
439
441
  import { Memory } from '@mastra/memory'
440
442
  import { PostgresStore, PgVector } from '@mastra/pg'
@@ -467,7 +469,7 @@ const agent = new Agent({
467
469
  })
468
470
  ```
469
471
 
470
- For detailed information about index configuration options and performance tuning, see the [PgVector configuration guide](https://mastra.ai/reference/vectors/pg).
472
+ For detailed information about index configuration options and performance tuning, see the [PgVector configuration guide](https://mastra.ai/integrations/vectors/pg).
471
473
 
472
474
  ## Disable semantic recall
473
475
 
@@ -235,7 +235,7 @@ export const oracleAgent = new Agent({
235
235
 
236
236
  ## Related
237
237
 
238
- - [OracleDB vector store](https://mastra.ai/reference/vectors/oracledb)
238
+ - [OracleDB vector store](https://mastra.ai/integrations/vectors/oracledb)
239
239
  - [Storage overview](https://mastra.ai/reference/storage/overview)
240
240
  - [Working memory](https://mastra.ai/docs/memory/working-memory)
241
241
  - [Workflow snapshots](https://mastra.ai/docs/workflows/snapshots)
@@ -225,14 +225,14 @@ await store.createIndex({
225
225
 
226
226
  ## Related
227
227
 
228
- - [Astra](https://mastra.ai/reference/vectors/astra)
229
- - [Chroma](https://mastra.ai/reference/vectors/chroma)
230
- - [Cloudflare Vectorize](https://mastra.ai/reference/vectors/vectorize)
231
- - [libSQL](https://mastra.ai/reference/vectors/libsql)
232
- - [MongoDB](https://mastra.ai/reference/vectors/mongodb)
233
- - [OracleDB](https://mastra.ai/reference/vectors/oracledb)
234
- - [PgVector](https://mastra.ai/reference/vectors/pg)
235
- - [Pinecone](https://mastra.ai/reference/vectors/pinecone)
236
- - [Qdrant](https://mastra.ai/reference/vectors/qdrant)
237
- - [Upstash](https://mastra.ai/reference/vectors/upstash)
238
- - [Amazon S3 Vectors](https://mastra.ai/reference/vectors/s3vectors)
228
+ - [Astra](https://mastra.ai/integrations/vectors/astra)
229
+ - [Chroma](https://mastra.ai/integrations/vectors/chroma)
230
+ - [Cloudflare Vectorize](https://mastra.ai/integrations/vectors/vectorize)
231
+ - [libSQL](https://mastra.ai/integrations/vectors/libsql)
232
+ - [MongoDB](https://mastra.ai/integrations/vectors/mongodb)
233
+ - [OracleDB](https://mastra.ai/integrations/vectors/oracledb)
234
+ - [PgVector](https://mastra.ai/integrations/vectors/pg)
235
+ - [Pinecone](https://mastra.ai/integrations/vectors/pinecone)
236
+ - [Qdrant](https://mastra.ai/integrations/vectors/qdrant)
237
+ - [Upstash](https://mastra.ai/integrations/vectors/upstash)
238
+ - [Amazon S3 Vectors](https://mastra.ai/integrations/vectors/s3vectors)
@@ -251,7 +251,11 @@ const results = await pgVector.query({
251
251
  })
252
252
  ```
253
253
 
254
- Postgres vector indexes (HNSW and IVFFlat) can't restrict that search to rows matching a condition. When a filter is present, pgVector instead compares the query vector against every matching row and returns the closest `topK`. Results are exact, but the work grows with the number of rows the filter matches. Indexing the metadata column speeds up row retrieval. The distance comparisons still happen per row.
254
+ With an HNSW index on pgvector 0.8.0 or newer, PostgreSQL searches the index and skips rows that don't match the filter. When the index search can't fill `topK`, pgVector reruns the query as an exact search.
255
+
256
+ With IVFFlat, or HNSW on older pgvector versions, pgVector compares the query vector against every matching row. Results are exact, but the work grows with the number of matching rows.
257
+
258
+ Indexing the metadata fields you filter on speeds up both cases and gives PostgreSQL the row counts it needs to choose between them.
255
259
 
256
260
  ### Vector Query Tool
257
261
 
@@ -35,7 +35,7 @@ MongoDB Vector Search is a good solution for teams who want to consolidate vecto
35
35
 
36
36
  ### Using VoyageAI with MongoDB
37
37
 
38
- MongoDB works directly with VoyageAI's embedding models, which are optimized for retrieval tasks. For complete examples and specialized models, see the [VoyageAI embeddings documentation](https://mastra.ai/models/embeddings) and [MongoDB vector reference](https://mastra.ai/reference/vectors/mongodb).
38
+ MongoDB works directly with VoyageAI's embedding models, which are optimized for retrieval tasks. For complete examples and specialized models, see the [VoyageAI embeddings documentation](https://mastra.ai/models/embeddings) and [MongoDB vector reference](https://mastra.ai/integrations/vectors/mongodb).
39
39
 
40
40
  ### Hybrid Search (Vector + Full-Text)
41
41
 
@@ -52,7 +52,7 @@ const results = await store.hybridQuery({
52
52
  })
53
53
  ```
54
54
 
55
- See the [MongoDB vector reference](https://mastra.ai/reference/vectors/mongodb) for details on `createSearchIndex()`, `textQuery()`, and `hybridQuery()`.
55
+ See the [MongoDB vector reference](https://mastra.ai/integrations/vectors/mongodb) for details on `createSearchIndex()`, `textQuery()`, and `hybridQuery()`.
56
56
 
57
57
  ### Automated Embedding
58
58
 
@@ -75,7 +75,7 @@ const results = await store.query({
75
75
  })
76
76
  ```
77
77
 
78
- Automated Embedding is a MongoDB Preview feature and needs a deployment where it's available. See the [MongoDB vector reference](https://mastra.ai/reference/vectors/mongodb) for the supported options and requirements.
78
+ Automated Embedding is a MongoDB Preview feature and needs a deployment where it's available. See the [MongoDB vector reference](https://mastra.ai/integrations/vectors/mongodb) for the supported options and requirements.
79
79
 
80
80
  **PgVector**:
81
81
 
package/dist/index.cjs CHANGED
@@ -2244,6 +2244,7 @@ var AgentsOracle = class AgentsOracle extends _mastra_core_storage.AgentsStorage
2244
2244
  tableName: _mastra_core_storage.TABLE_AGENT_VERSIONS,
2245
2245
  schema: ORACLE_AGENT_VERSIONS_SCHEMA,
2246
2246
  ifNotExists: [
2247
+ "modelList",
2247
2248
  "tools",
2248
2249
  "mcpClients",
2249
2250
  "requestContextSchema",
@@ -2579,6 +2580,7 @@ var AgentsOracle = class AgentsOracle extends _mastra_core_storage.AgentsStorage
2579
2580
  description: input.description,
2580
2581
  instructions: input.instructions,
2581
2582
  model: input.model,
2583
+ modelList: input.modelList,
2582
2584
  tools: normalizeLegacyTools(input.tools),
2583
2585
  defaultOptions: input.defaultOptions,
2584
2586
  workflows: input.workflows,
@@ -2613,14 +2615,14 @@ var AgentsOracle = class AgentsOracle extends _mastra_core_storage.AgentsStorage
2613
2615
  async insertVersion(client, input, createdAt = /* @__PURE__ */ new Date()) {
2614
2616
  await client.none(`INSERT INTO ${this.table(_mastra_core_storage.TABLE_AGENT_VERSIONS)} (
2615
2617
  id, ${VERSION_AGENT_ID}, ${VERSION_VERSION_NUMBER$2},
2616
- name, description, instructions, model, tools,
2618
+ name, description, instructions, model, "modelList", tools,
2617
2619
  ${VERSION_DEFAULT_OPTIONS}, workflows, agents, ${VERSION_INTEGRATION_TOOLS},
2618
2620
  ${VERSION_INPUT_PROCESSORS}, ${VERSION_OUTPUT_PROCESSORS}, memory, scorers,
2619
2621
  ${VERSION_MCP_CLIENTS}, ${VERSION_REQUEST_CONTEXT_SCHEMA},
2620
2622
  browser, ${VERSION_CHANGED_FIELDS$2}, ${VERSION_CHANGE_MESSAGE$2}, ${VERSION_CREATED_AT$2}
2621
2623
  ) VALUES (
2622
2624
  :id, :agentId, :versionNumber,
2623
- :name, :description, :instructions, :model, :tools,
2625
+ :name, :description, :instructions, :model, :modelList, :tools,
2624
2626
  :defaultOptions, :workflows, :agents, :integrationTools,
2625
2627
  :inputProcessors, :outputProcessors, :memory, :scorers,
2626
2628
  :mcpClients, :requestContextSchema,
@@ -2631,8 +2633,9 @@ var AgentsOracle = class AgentsOracle extends _mastra_core_storage.AgentsStorage
2631
2633
  versionNumber: input.versionNumber,
2632
2634
  name: input.name,
2633
2635
  description: nullableClobBind(input.description),
2634
- instructions: clobBind(this.serializeInstructions(input.instructions)),
2635
- model: jsonBind(input.model),
2636
+ instructions: clobBind(this.serializeInstructions(input.instructions ?? "")),
2637
+ model: jsonBind(input.model ?? {}),
2638
+ modelList: nullableJsonBind(input.modelList),
2636
2639
  tools: nullableJsonBind(normalizeLegacyTools(input.tools)),
2637
2640
  defaultOptions: nullableJsonBind(input.defaultOptions),
2638
2641
  workflows: nullableJsonBind(input.workflows),
@@ -2710,6 +2713,7 @@ var AgentsOracle = class AgentsOracle extends _mastra_core_storage.AgentsStorage
2710
2713
  `description AS "description"`,
2711
2714
  `instructions AS "instructions"`,
2712
2715
  `model AS "model"`,
2716
+ `"modelList" AS "modelList"`,
2713
2717
  `tools AS "tools"`,
2714
2718
  `${VERSION_DEFAULT_OPTIONS} AS "defaultOptions"`,
2715
2719
  `workflows AS "workflows"`,
@@ -2749,6 +2753,7 @@ var AgentsOracle = class AgentsOracle extends _mastra_core_storage.AgentsStorage
2749
2753
  description: optionalString$3(row.description),
2750
2754
  instructions: this.deserializeInstructions(row.instructions),
2751
2755
  model: parseOracleJson(row.model),
2756
+ modelList: parseOptionalJson(row.modelList),
2752
2757
  tools: normalizeLegacyTools(parseOptionalJson(row.tools)),
2753
2758
  defaultOptions: parseOptionalJson(row.defaultOptions),
2754
2759
  workflows: parseOptionalJson(row.workflows),
@@ -2767,6 +2772,7 @@ var AgentsOracle = class AgentsOracle extends _mastra_core_storage.AgentsStorage
2767
2772
  };
2768
2773
  }
2769
2774
  serializeInstructions(instructions) {
2775
+ if (instructions === void 0) return "";
2770
2776
  return Array.isArray(instructions) ? JSON.stringify(instructions) : instructions;
2771
2777
  }
2772
2778
  deserializeInstructions(raw) {