@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 +1 -1
- package/dist/docs/SKILL.md +2 -2
- package/dist/docs/assets/SOURCE_MAP.json +1 -1
- package/dist/docs/references/docs-memory-observational-memory.md +27 -1
- package/dist/docs/references/docs-memory-semantic-recall.md +22 -20
- package/dist/docs/references/integrations-databases-oracledb.md +1 -1
- package/dist/docs/references/reference-rag-metadata-filters.md +11 -11
- package/dist/docs/references/reference-rag-retrieval.md +5 -1
- package/dist/docs/references/reference-rag-vector-databases.md +3 -3
- package/dist/index.cjs +10 -4
- package/dist/index.cjs.map +1 -1
- package/dist/index.js +10 -4
- package/dist/index.js.map +1 -1
- package/dist/storage/domains/agents/index.d.ts.map +1 -1
- package/dist/storage/domains/memory/index.d.ts +1 -1
- package/dist/storage/domains/memory/observational-buffering.d.ts +1 -1
- package/dist/storage/domains/memory/observational.d.ts +1 -1
- package/package.json +8 -8
- /package/dist/_types/{@internal_core → @internal_core@0.1.4}/dist/memory/index.d.ts +0 -0
- /package/dist/_types/{@internal_core → @internal_core@0.1.4}/package.json +0 -0
- /package/dist/docs/references/{reference-vectors-oracledb.md → integrations-vectors-oracledb.md} +0 -0
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/
|
|
62
|
+
- [Oracle Database vector reference](https://mastra.ai/integrations/vectors/oracledb)
|
|
63
63
|
|
|
64
64
|
## Changelog
|
|
65
65
|
|
package/dist/docs/SKILL.md
CHANGED
|
@@ -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.
|
|
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.
|
|
@@ -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
|
-
|
|
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/
|
|
145
|
-
- [Chroma](https://mastra.ai/
|
|
146
|
-
- [Cloudflare Vectorize](https://mastra.ai/
|
|
147
|
-
- [Convex](https://mastra.ai/
|
|
148
|
-
- [Couchbase](https://mastra.ai/
|
|
149
|
-
- [DuckDB](https://mastra.ai/
|
|
150
|
-
- [Elasticsearch](https://mastra.ai/
|
|
151
|
-
- [LanceDB](https://mastra.ai/
|
|
152
|
-
- [libSQL](https://mastra.ai/
|
|
153
|
-
- [MongoDB](https://mastra.ai/
|
|
154
|
-
- [OpenSearch](https://mastra.ai/
|
|
155
|
-
- [OracleDB](https://mastra.ai/
|
|
156
|
-
- [Pinecone](https://mastra.ai/
|
|
157
|
-
- [PostgreSQL](https://mastra.ai/
|
|
158
|
-
- [Qdrant](https://mastra.ai/
|
|
159
|
-
- [S3 Vectors](https://mastra.ai/
|
|
160
|
-
- [Turbopuffer](https://mastra.ai/
|
|
161
|
-
- [Upstash](https://mastra.ai/
|
|
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/
|
|
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/
|
|
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/
|
|
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/
|
|
229
|
-
- [Chroma](https://mastra.ai/
|
|
230
|
-
- [Cloudflare Vectorize](https://mastra.ai/
|
|
231
|
-
- [libSQL](https://mastra.ai/
|
|
232
|
-
- [MongoDB](https://mastra.ai/
|
|
233
|
-
- [OracleDB](https://mastra.ai/
|
|
234
|
-
- [PgVector](https://mastra.ai/
|
|
235
|
-
- [Pinecone](https://mastra.ai/
|
|
236
|
-
- [Qdrant](https://mastra.ai/
|
|
237
|
-
- [Upstash](https://mastra.ai/
|
|
238
|
-
- [Amazon S3 Vectors](https://mastra.ai/
|
|
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
|
-
|
|
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/
|
|
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/
|
|
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/
|
|
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) {
|