@mastra/pinecone 1.0.1 → 1.1.0-alpha.0
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/CHANGELOG.md +29 -0
- package/LICENSE.md +15 -0
- package/dist/docs/SKILL.md +6 -6
- package/dist/docs/assets/SOURCE_MAP.json +1 -1
- package/dist/docs/references/docs-memory-memory-processors.md +18 -18
- package/dist/docs/references/docs-memory-storage.md +16 -16
- package/dist/docs/references/docs-rag-retrieval.md +19 -16
- package/dist/docs/references/docs-rag-vector-databases.md +13 -13
- package/dist/docs/references/reference-vectors-pinecone.md +53 -53
- package/package.json +13 -12
package/CHANGELOG.md
CHANGED
|
@@ -1,5 +1,34 @@
|
|
|
1
1
|
# @mastra/pinecone
|
|
2
2
|
|
|
3
|
+
## 1.1.0-alpha.0
|
|
4
|
+
|
|
5
|
+
### Minor Changes
|
|
6
|
+
|
|
7
|
+
- Random bump ([#18178](https://github.com/mastra-ai/mastra/pull/18178))
|
|
8
|
+
|
|
9
|
+
### Patch Changes
|
|
10
|
+
|
|
11
|
+
- Updated dependencies [[`7c0d868`](https://github.com/mastra-ai/mastra/commit/7c0d868d97d0fdbc04c14d0166dbf44d4c5a4a62), [`d9d2273`](https://github.com/mastra-ai/mastra/commit/d9d2273c702690c9a26eab2aebea879701d4355a), [`b04369d`](https://github.com/mastra-ai/mastra/commit/b04369d6b167c698ef103981171a8bf92808e756), [`8f3c262`](https://github.com/mastra-ai/mastra/commit/8f3c262587b335588a02d96b17fd6aca34c885b3)]:
|
|
12
|
+
- @mastra/core@1.45.0-alpha.0
|
|
13
|
+
|
|
14
|
+
## 1.0.2
|
|
15
|
+
|
|
16
|
+
### Patch Changes
|
|
17
|
+
|
|
18
|
+
- Security remediation for the 2026-06-17 "easy-day-js" supply-chain incident. Patch bump to publish clean versions and move the `latest` dist-tag forward, superseding the compromised versions that declared the malicious `easy-day-js` dependency. ([#18056](https://github.com/mastra-ai/mastra/pull/18056))
|
|
19
|
+
|
|
20
|
+
- Updated dependencies [[`339c57c`](https://github.com/mastra-ai/mastra/commit/339c57c5b2c6dbe75a125e138228e0556528976f), [`1dd4117`](https://github.com/mastra-ai/mastra/commit/1dd4117dcbd8e031ede9f0489436bfbc6f0315b8), [`2b11d1f`](https://github.com/mastra-ai/mastra/commit/2b11d1f6ac7024c5dd2b2dd12a48a956ac9d63bd), [`77a2351`](https://github.com/mastra-ai/mastra/commit/77a2351ee79296e360bce822cb3391f7cfd6489d), [`b7dff0a`](https://github.com/mastra-ai/mastra/commit/b7dff0a3d1022eb6868f48dc40a2b1febd5c277f), [`02087e1`](https://github.com/mastra-ai/mastra/commit/02087e1fbc54aa07f3071f7a200df1bf5be601a8), [`49af8df`](https://github.com/mastra-ai/mastra/commit/49af8df589c4ff71a5015a4553b377b32704b691), [`30ce559`](https://github.com/mastra-ai/mastra/commit/30ce55902ecf819b8ab8697398dd68b108228063), [`c241b92`](https://github.com/mastra-ai/mastra/commit/c241b929dc8c8d6a7b7219c99ed13ac1f3124a77), [`7d6ff70`](https://github.com/mastra-ai/mastra/commit/7d6ff708727297a0526ca0e26e93eeb5bbaaa187), [`ab975d4`](https://github.com/mastra-ai/mastra/commit/ab975d4dd9488752f05bda7afa03166d207e3e2a), [`9d6aa1b`](https://github.com/mastra-ai/mastra/commit/9d6aa1bae407e2afa6a089abc2a6accbbcb287b8)]:
|
|
21
|
+
- @mastra/core@1.44.0
|
|
22
|
+
|
|
23
|
+
## 1.0.2-alpha.0
|
|
24
|
+
|
|
25
|
+
### Patch Changes
|
|
26
|
+
|
|
27
|
+
- Security remediation for the 2026-06-17 "easy-day-js" supply-chain incident. Patch bump to publish clean versions and move the `latest` dist-tag forward, superseding the compromised versions that declared the malicious `easy-day-js` dependency. ([#18056](https://github.com/mastra-ai/mastra/pull/18056))
|
|
28
|
+
|
|
29
|
+
- Updated dependencies [[`77a2351`](https://github.com/mastra-ai/mastra/commit/77a2351ee79296e360bce822cb3391f7cfd6489d)]:
|
|
30
|
+
- @mastra/core@1.43.1-alpha.0
|
|
31
|
+
|
|
3
32
|
## 1.0.1
|
|
4
33
|
|
|
5
34
|
### Patch Changes
|
package/LICENSE.md
CHANGED
|
@@ -1,3 +1,18 @@
|
|
|
1
|
+
Portions of this software are licensed as follows:
|
|
2
|
+
|
|
3
|
+
- All content that resides under any directory named "ee/" within this
|
|
4
|
+
repository, including but not limited to:
|
|
5
|
+
- `packages/core/src/auth/ee/`
|
|
6
|
+
- `packages/server/src/server/auth/ee/`
|
|
7
|
+
is licensed under the license defined in `ee/LICENSE`.
|
|
8
|
+
|
|
9
|
+
- All third-party components incorporated into the Mastra Software are
|
|
10
|
+
licensed under the original license provided by the owner of the
|
|
11
|
+
applicable component.
|
|
12
|
+
|
|
13
|
+
- Content outside of the above-mentioned directories or restrictions is
|
|
14
|
+
available under the "Apache License 2.0" as defined below.
|
|
15
|
+
|
|
1
16
|
# Apache License 2.0
|
|
2
17
|
|
|
3
18
|
Copyright (c) 2025 Kepler Software, Inc.
|
package/dist/docs/SKILL.md
CHANGED
|
@@ -3,7 +3,7 @@ name: mastra-pinecone
|
|
|
3
3
|
description: Documentation for @mastra/pinecone. Use when working with @mastra/pinecone APIs, configuration, or implementation.
|
|
4
4
|
metadata:
|
|
5
5
|
package: "@mastra/pinecone"
|
|
6
|
-
version: "1.0.
|
|
6
|
+
version: "1.1.0-alpha.0"
|
|
7
7
|
---
|
|
8
8
|
|
|
9
9
|
## When to use
|
|
@@ -16,14 +16,14 @@ Read the individual reference documents for detailed explanations and code examp
|
|
|
16
16
|
|
|
17
17
|
### Docs
|
|
18
18
|
|
|
19
|
-
- [Memory
|
|
20
|
-
- [Storage](references/docs-memory-storage.md) - Configure storage for Mastra
|
|
21
|
-
- [Retrieval,
|
|
22
|
-
- [Storing
|
|
19
|
+
- [Memory processors](references/docs-memory-memory-processors.md) - Learn how to use memory processors in Mastra to filter, trim, and transform messages before they're sent to the language model to manage context window limits.
|
|
20
|
+
- [Storage](references/docs-memory-storage.md) - Configure storage for Mastra to persist conversations and other runtime state.
|
|
21
|
+
- [Retrieval, semantic search, reranking](references/docs-rag-retrieval.md) - Guide on retrieval processes in Mastra's RAG systems, including semantic search, filtering, and re-ranking.
|
|
22
|
+
- [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.
|
|
23
23
|
|
|
24
24
|
### Reference
|
|
25
25
|
|
|
26
|
-
- [Reference: Pinecone
|
|
26
|
+
- [Reference: Pinecone vector store](references/reference-vectors-pinecone.md) - Documentation for the PineconeVector class in Mastra, which provides an interface to Pinecone's vector database.
|
|
27
27
|
|
|
28
28
|
|
|
29
29
|
Read [assets/SOURCE_MAP.json](assets/SOURCE_MAP.json) for source code references.
|
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
# Memory
|
|
1
|
+
# Memory processors
|
|
2
2
|
|
|
3
3
|
Memory processors transform and filter messages as they pass through an agent with memory enabled. They manage context window limits, remove unnecessary content, and optimize the information sent to the language model.
|
|
4
4
|
|
|
@@ -6,11 +6,11 @@ When memory is enabled on an agent, Mastra adds memory processors to the agent's
|
|
|
6
6
|
|
|
7
7
|
Memory processors are [processors](https://mastra.ai/docs/agents/processors) that operate specifically on memory-related messages and state.
|
|
8
8
|
|
|
9
|
-
## Built-in
|
|
9
|
+
## Built-in memory processors
|
|
10
10
|
|
|
11
11
|
Mastra automatically adds these processors when memory is enabled:
|
|
12
12
|
|
|
13
|
-
### MessageHistory
|
|
13
|
+
### `MessageHistory`
|
|
14
14
|
|
|
15
15
|
Retrieves message history and persists new messages.
|
|
16
16
|
|
|
@@ -45,7 +45,7 @@ const agent = new Agent({
|
|
|
45
45
|
id: 'test-agent',
|
|
46
46
|
name: 'Test Agent',
|
|
47
47
|
instructions: 'You are a helpful assistant',
|
|
48
|
-
model: 'openai/gpt-
|
|
48
|
+
model: 'openai/gpt-5.5',
|
|
49
49
|
memory: new Memory({
|
|
50
50
|
storage: new LibSQLStore({
|
|
51
51
|
id: 'memory-store',
|
|
@@ -56,7 +56,7 @@ const agent = new Agent({
|
|
|
56
56
|
})
|
|
57
57
|
```
|
|
58
58
|
|
|
59
|
-
### SemanticRecall
|
|
59
|
+
### `SemanticRecall`
|
|
60
60
|
|
|
61
61
|
Retrieves semantically relevant messages based on the current input and creates embeddings for new messages.
|
|
62
62
|
|
|
@@ -95,7 +95,7 @@ import { openai } from '@ai-sdk/openai'
|
|
|
95
95
|
const agent = new Agent({
|
|
96
96
|
name: 'semantic-agent',
|
|
97
97
|
instructions: 'You are a helpful assistant with semantic memory',
|
|
98
|
-
model: 'openai/gpt-
|
|
98
|
+
model: 'openai/gpt-5.5',
|
|
99
99
|
memory: new Memory({
|
|
100
100
|
storage: new LibSQLStore({
|
|
101
101
|
id: 'memory-store',
|
|
@@ -114,7 +114,7 @@ const agent = new Agent({
|
|
|
114
114
|
})
|
|
115
115
|
```
|
|
116
116
|
|
|
117
|
-
### WorkingMemory
|
|
117
|
+
### `WorkingMemory`
|
|
118
118
|
|
|
119
119
|
Manages working memory state across conversations.
|
|
120
120
|
|
|
@@ -148,7 +148,7 @@ import { openai } from '@ai-sdk/openai'
|
|
|
148
148
|
const agent = new Agent({
|
|
149
149
|
name: 'working-memory-agent',
|
|
150
150
|
instructions: 'You are an assistant with working memory',
|
|
151
|
-
model: 'openai/gpt-
|
|
151
|
+
model: 'openai/gpt-5.5',
|
|
152
152
|
memory: new Memory({
|
|
153
153
|
storage: new LibSQLStore({
|
|
154
154
|
id: 'memory-store',
|
|
@@ -159,9 +159,9 @@ const agent = new Agent({
|
|
|
159
159
|
})
|
|
160
160
|
```
|
|
161
161
|
|
|
162
|
-
## Manual
|
|
162
|
+
## Manual control and deduplication
|
|
163
163
|
|
|
164
|
-
If you manually add a memory processor to `inputProcessors` or `outputProcessors`, Mastra
|
|
164
|
+
If you manually add a memory processor to `inputProcessors` or `outputProcessors`, Mastra **won't** automatically add it. This gives you full control over processor ordering:
|
|
165
165
|
|
|
166
166
|
```typescript
|
|
167
167
|
import { Agent } from '@mastra/core/agent'
|
|
@@ -180,7 +180,7 @@ const customMessageHistory = new MessageHistory({
|
|
|
180
180
|
const agent = new Agent({
|
|
181
181
|
name: 'custom-memory-agent',
|
|
182
182
|
instructions: 'You are a helpful assistant',
|
|
183
|
-
model: 'openai/gpt-
|
|
183
|
+
model: 'openai/gpt-5.5',
|
|
184
184
|
memory: new Memory({
|
|
185
185
|
storage: new LibSQLStore({ id: 'memory-store', url: 'file:memory.db' }),
|
|
186
186
|
lastMessages: 10, // This would normally add MessageHistory(10)
|
|
@@ -192,7 +192,7 @@ const agent = new Agent({
|
|
|
192
192
|
})
|
|
193
193
|
```
|
|
194
194
|
|
|
195
|
-
## Processor
|
|
195
|
+
## Processor execution order
|
|
196
196
|
|
|
197
197
|
Understanding the execution order is important when combining guardrails with memory:
|
|
198
198
|
|
|
@@ -218,7 +218,7 @@ This means memory loads message history before your processors can validate or f
|
|
|
218
218
|
|
|
219
219
|
This ordering is designed to be **safe by default**: if your output guardrail calls `abort()`, the memory processors never run and **no messages are saved**.
|
|
220
220
|
|
|
221
|
-
## Guardrails and
|
|
221
|
+
## Guardrails and memory
|
|
222
222
|
|
|
223
223
|
The default execution order provides safe guardrail behavior:
|
|
224
224
|
|
|
@@ -250,7 +250,7 @@ const contentBlocker = {
|
|
|
250
250
|
const agent = new Agent({
|
|
251
251
|
name: 'safe-agent',
|
|
252
252
|
instructions: 'You are a helpful assistant',
|
|
253
|
-
model: 'openai/gpt-
|
|
253
|
+
model: 'openai/gpt-5.5',
|
|
254
254
|
memory: new Memory({ lastMessages: 10 }),
|
|
255
255
|
// Your guardrail runs BEFORE memory saves
|
|
256
256
|
outputProcessors: [contentBlocker],
|
|
@@ -289,7 +289,7 @@ const inputValidator = {
|
|
|
289
289
|
const agent = new Agent({
|
|
290
290
|
name: 'validated-agent',
|
|
291
291
|
instructions: 'You are a helpful assistant',
|
|
292
|
-
model: 'openai/gpt-
|
|
292
|
+
model: 'openai/gpt-5.5',
|
|
293
293
|
memory: new Memory({ lastMessages: 10 }),
|
|
294
294
|
// Your guardrail runs AFTER memory loads history
|
|
295
295
|
inputProcessors: [inputValidator],
|
|
@@ -307,8 +307,8 @@ Both scenarios are safe - guardrails prevent inappropriate content from being pe
|
|
|
307
307
|
|
|
308
308
|
## Related documentation
|
|
309
309
|
|
|
310
|
-
- [Processors](https://mastra.ai/docs/agents/processors)
|
|
311
|
-
- [Guardrails](https://mastra.ai/docs/agents/guardrails)
|
|
312
|
-
- [Memory Overview](https://mastra.ai/docs/memory/overview)
|
|
310
|
+
- [Processors](https://mastra.ai/docs/agents/processors): General processor concepts and custom processor creation
|
|
311
|
+
- [Guardrails](https://mastra.ai/docs/agents/guardrails): Security and validation processors
|
|
312
|
+
- [Memory Overview](https://mastra.ai/docs/memory/overview): Memory types and configuration
|
|
313
313
|
|
|
314
314
|
When creating custom processors avoid mutating the input `messages` array or its objects directly.
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# Storage
|
|
2
2
|
|
|
3
|
-
For agents to remember previous interactions, Mastra needs a
|
|
3
|
+
For agents to remember previous interactions, Mastra needs a storage adapter. Use one of the [supported providers](#supported-providers) and pass it to your Mastra instance.
|
|
4
4
|
|
|
5
5
|
```typescript
|
|
6
6
|
import { Mastra } from '@mastra/core'
|
|
@@ -14,7 +14,7 @@ export const mastra = new Mastra({
|
|
|
14
14
|
})
|
|
15
15
|
```
|
|
16
16
|
|
|
17
|
-
> **Sharing the database with
|
|
17
|
+
> **Sharing the database with Studio:** When running `mastra dev` alongside your application (e.g., Next.js), use an absolute path to ensure both processes access the same database:
|
|
18
18
|
>
|
|
19
19
|
> ```typescript
|
|
20
20
|
> url: 'file:/absolute/path/to/your/project/mastra.db'
|
|
@@ -24,7 +24,7 @@ export const mastra = new Mastra({
|
|
|
24
24
|
|
|
25
25
|
This configures instance-level storage, which all agents share by default. You can also configure [agent-level storage](#agent-level-storage) for isolated data boundaries.
|
|
26
26
|
|
|
27
|
-
Mastra automatically
|
|
27
|
+
Mastra automatically initializes the necessary storage structures on first interaction. See [Storage Overview](https://mastra.ai/reference/storage/overview) for domain coverage and the schema used by the built-in database-backed domains.
|
|
28
28
|
|
|
29
29
|
## Supported providers
|
|
30
30
|
|
|
@@ -34,12 +34,14 @@ Each provider page includes installation instructions, configuration parameters,
|
|
|
34
34
|
- [PostgreSQL](https://mastra.ai/reference/storage/postgresql)
|
|
35
35
|
- [MongoDB](https://mastra.ai/reference/storage/mongodb)
|
|
36
36
|
- [Upstash](https://mastra.ai/reference/storage/upstash)
|
|
37
|
+
- [Redis](https://mastra.ai/reference/storage/redis)
|
|
37
38
|
- [Cloudflare D1](https://mastra.ai/reference/storage/cloudflare-d1)
|
|
38
|
-
- [Cloudflare Durable Objects](https://mastra.ai/reference/storage/cloudflare)
|
|
39
|
+
- [Cloudflare KV & Durable Objects](https://mastra.ai/reference/storage/cloudflare)
|
|
39
40
|
- [Convex](https://mastra.ai/reference/storage/convex)
|
|
40
41
|
- [DynamoDB](https://mastra.ai/reference/storage/dynamodb)
|
|
41
42
|
- [LanceDB](https://mastra.ai/reference/storage/lance)
|
|
42
43
|
- [Microsoft SQL Server](https://mastra.ai/reference/storage/mssql)
|
|
44
|
+
- [Google Cloud Spanner](https://mastra.ai/reference/storage/spanner)
|
|
43
45
|
|
|
44
46
|
> **Tip:** libSQL is the easiest way to get started because it doesn’t require running a separate database server.
|
|
45
47
|
|
|
@@ -49,7 +51,7 @@ Storage can be configured at the instance level (shared by all agents) or at the
|
|
|
49
51
|
|
|
50
52
|
### Instance-level storage
|
|
51
53
|
|
|
52
|
-
Add storage to your Mastra instance so all agents, workflows, observability traces and scores share the same
|
|
54
|
+
Add storage to your Mastra instance so all agents, workflows, observability traces, and scores share the same storage backend:
|
|
53
55
|
|
|
54
56
|
```typescript
|
|
55
57
|
import { Mastra } from '@mastra/core'
|
|
@@ -71,7 +73,7 @@ This is useful when all primitives share the same storage backend and have simil
|
|
|
71
73
|
|
|
72
74
|
#### Composite storage
|
|
73
75
|
|
|
74
|
-
[Composite storage](https://mastra.ai/reference/storage/composite) is an alternative way to configure instance-level storage. Use `MastraCompositeStore` to
|
|
76
|
+
[Composite storage](https://mastra.ai/reference/storage/composite) is an alternative way to configure instance-level storage. Use `MastraCompositeStore` to route `memory` and any other [supported domains](https://mastra.ai/reference/storage/composite) to different storage providers.
|
|
75
77
|
|
|
76
78
|
```typescript
|
|
77
79
|
import { Mastra } from '@mastra/core'
|
|
@@ -100,7 +102,7 @@ This is useful when different types of data have different performance or operat
|
|
|
100
102
|
|
|
101
103
|
### Agent-level storage
|
|
102
104
|
|
|
103
|
-
Agent-level storage overrides storage configured at the instance level. Add storage to a specific agent when you need data
|
|
105
|
+
Agent-level storage overrides storage configured at the instance level. Add storage to a specific agent when you need to keep data separate or use different providers per agent.
|
|
104
106
|
|
|
105
107
|
```typescript
|
|
106
108
|
import { Agent } from '@mastra/core/agent'
|
|
@@ -118,18 +120,16 @@ export const agent = new Agent({
|
|
|
118
120
|
})
|
|
119
121
|
```
|
|
120
122
|
|
|
121
|
-
> **Warning:** [Mastra Cloud Store](https://mastra.ai/docs/mastra-cloud/deployment) doesn't support agent-level storage.
|
|
122
|
-
|
|
123
123
|
## Threads and resources
|
|
124
124
|
|
|
125
125
|
Mastra organizes conversations using two identifiers:
|
|
126
126
|
|
|
127
|
-
- **Thread
|
|
128
|
-
- **Resource
|
|
127
|
+
- **Thread**: A conversation session containing a sequence of messages.
|
|
128
|
+
- **Resource**: The entity that owns the thread, such as a user, organization, project, or any other domain entity in your application.
|
|
129
129
|
|
|
130
130
|
Both identifiers are required for agents to store information:
|
|
131
131
|
|
|
132
|
-
|
|
132
|
+
**.generate()**:
|
|
133
133
|
|
|
134
134
|
```typescript
|
|
135
135
|
const response = await agent.generate('hello', {
|
|
@@ -140,7 +140,7 @@ const response = await agent.generate('hello', {
|
|
|
140
140
|
})
|
|
141
141
|
```
|
|
142
142
|
|
|
143
|
-
|
|
143
|
+
**.stream()**:
|
|
144
144
|
|
|
145
145
|
```typescript
|
|
146
146
|
const stream = await agent.stream('hello', {
|
|
@@ -151,7 +151,7 @@ const stream = await agent.stream('hello', {
|
|
|
151
151
|
})
|
|
152
152
|
```
|
|
153
153
|
|
|
154
|
-
> **Note:** [Studio](https://mastra.ai/docs/
|
|
154
|
+
> **Note:** [Studio](https://mastra.ai/docs/studio/overview) automatically generates a thread and resource ID for you. When calling `stream()` or `generate()` yourself, remember to provide these identifiers explicitly.
|
|
155
155
|
|
|
156
156
|
### Thread title generation
|
|
157
157
|
|
|
@@ -170,7 +170,7 @@ export const agent = new Agent({
|
|
|
170
170
|
})
|
|
171
171
|
```
|
|
172
172
|
|
|
173
|
-
Title generation runs asynchronously after the agent responds and
|
|
173
|
+
Title generation runs asynchronously after the agent responds and doesn't affect response time.
|
|
174
174
|
|
|
175
175
|
To optimize cost or behavior, provide a smaller [`model`](https://mastra.ai/models) and custom `instructions`:
|
|
176
176
|
|
|
@@ -180,7 +180,7 @@ export const agent = new Agent({
|
|
|
180
180
|
memory: new Memory({
|
|
181
181
|
options: {
|
|
182
182
|
generateTitle: {
|
|
183
|
-
model: 'openai/gpt-
|
|
183
|
+
model: 'openai/gpt-5-mini',
|
|
184
184
|
instructions: 'Generate a 1 word title',
|
|
185
185
|
},
|
|
186
186
|
},
|
|
@@ -1,10 +1,10 @@
|
|
|
1
|
-
# Retrieval in RAG
|
|
1
|
+
# Retrieval in RAG systems
|
|
2
2
|
|
|
3
3
|
After storing embeddings, you need to retrieve relevant chunks to answer user queries.
|
|
4
4
|
|
|
5
5
|
Mastra provides flexible retrieval options with support for semantic search, filtering, and re-ranking.
|
|
6
6
|
|
|
7
|
-
## How
|
|
7
|
+
## How retrieval works
|
|
8
8
|
|
|
9
9
|
1. The user's query is converted to an embedding using the same model used for document embeddings
|
|
10
10
|
2. This embedding is compared to stored embeddings using vector similarity
|
|
@@ -14,7 +14,7 @@ Mastra provides flexible retrieval options with support for semantic search, fil
|
|
|
14
14
|
- Re-ranked for better relevance
|
|
15
15
|
- Processed through a knowledge graph
|
|
16
16
|
|
|
17
|
-
## Basic
|
|
17
|
+
## Basic retrieval
|
|
18
18
|
|
|
19
19
|
The simplest approach is direct semantic search. This method uses vector similarity to find chunks that are semantically similar to the query:
|
|
20
20
|
|
|
@@ -63,7 +63,7 @@ Results include both the text content and a similarity score:
|
|
|
63
63
|
]
|
|
64
64
|
```
|
|
65
65
|
|
|
66
|
-
## Advanced
|
|
66
|
+
## Advanced retrieval options
|
|
67
67
|
|
|
68
68
|
### Metadata Filtering
|
|
69
69
|
|
|
@@ -272,7 +272,7 @@ import { PGVECTOR_PROMPT } from '@mastra/pg'
|
|
|
272
272
|
export const ragAgent = new Agent({
|
|
273
273
|
id: 'rag-agent',
|
|
274
274
|
name: 'RAG Agent',
|
|
275
|
-
model: 'openai/gpt-5.
|
|
275
|
+
model: 'openai/gpt-5.5',
|
|
276
276
|
instructions: `
|
|
277
277
|
Process queries using the provided context. Structure responses to be concise and relevant.
|
|
278
278
|
${PGVECTOR_PROMPT}
|
|
@@ -289,7 +289,7 @@ import { PINECONE_PROMPT } from '@mastra/pinecone'
|
|
|
289
289
|
export const ragAgent = new Agent({
|
|
290
290
|
id: 'rag-agent',
|
|
291
291
|
name: 'RAG Agent',
|
|
292
|
-
model: 'openai/gpt-5.
|
|
292
|
+
model: 'openai/gpt-5.5',
|
|
293
293
|
instructions: `
|
|
294
294
|
Process queries using the provided context. Structure responses to be concise and relevant.
|
|
295
295
|
${PINECONE_PROMPT}
|
|
@@ -306,7 +306,7 @@ import { QDRANT_PROMPT } from '@mastra/qdrant'
|
|
|
306
306
|
export const ragAgent = new Agent({
|
|
307
307
|
id: 'rag-agent',
|
|
308
308
|
name: 'RAG Agent',
|
|
309
|
-
model: 'openai/gpt-5.
|
|
309
|
+
model: 'openai/gpt-5.5',
|
|
310
310
|
instructions: `
|
|
311
311
|
Process queries using the provided context. Structure responses to be concise and relevant.
|
|
312
312
|
${QDRANT_PROMPT}
|
|
@@ -323,7 +323,7 @@ import { CHROMA_PROMPT } from '@mastra/chroma'
|
|
|
323
323
|
export const ragAgent = new Agent({
|
|
324
324
|
id: 'rag-agent',
|
|
325
325
|
name: 'RAG Agent',
|
|
326
|
-
model: 'openai/gpt-5.
|
|
326
|
+
model: 'openai/gpt-5.5',
|
|
327
327
|
instructions: `
|
|
328
328
|
Process queries using the provided context. Structure responses to be concise and relevant.
|
|
329
329
|
${CHROMA_PROMPT}
|
|
@@ -340,7 +340,7 @@ import { ASTRA_PROMPT } from '@mastra/astra'
|
|
|
340
340
|
export const ragAgent = new Agent({
|
|
341
341
|
id: 'rag-agent',
|
|
342
342
|
name: 'RAG Agent',
|
|
343
|
-
model: 'openai/gpt-5.
|
|
343
|
+
model: 'openai/gpt-5.5',
|
|
344
344
|
instructions: `
|
|
345
345
|
Process queries using the provided context. Structure responses to be concise and relevant.
|
|
346
346
|
${ASTRA_PROMPT}
|
|
@@ -357,7 +357,7 @@ import { LIBSQL_PROMPT } from '@mastra/libsql'
|
|
|
357
357
|
export const ragAgent = new Agent({
|
|
358
358
|
id: 'rag-agent',
|
|
359
359
|
name: 'RAG Agent',
|
|
360
|
-
model: 'openai/gpt-5.
|
|
360
|
+
model: 'openai/gpt-5.5',
|
|
361
361
|
instructions: `
|
|
362
362
|
Process queries using the provided context. Structure responses to be concise and relevant.
|
|
363
363
|
${LIBSQL_PROMPT}
|
|
@@ -374,7 +374,7 @@ import { UPSTASH_PROMPT } from '@mastra/upstash'
|
|
|
374
374
|
export const ragAgent = new Agent({
|
|
375
375
|
id: 'rag-agent',
|
|
376
376
|
name: 'RAG Agent',
|
|
377
|
-
model: 'openai/gpt-5.
|
|
377
|
+
model: 'openai/gpt-5.5',
|
|
378
378
|
instructions: `
|
|
379
379
|
Process queries using the provided context. Structure responses to be concise and relevant.
|
|
380
380
|
${UPSTASH_PROMPT}
|
|
@@ -391,7 +391,7 @@ import { VECTORIZE_PROMPT } from '@mastra/vectorize'
|
|
|
391
391
|
export const ragAgent = new Agent({
|
|
392
392
|
id: 'rag-agent',
|
|
393
393
|
name: 'RAG Agent',
|
|
394
|
-
model: 'openai/gpt-5.
|
|
394
|
+
model: 'openai/gpt-5.5',
|
|
395
395
|
instructions: `
|
|
396
396
|
Process queries using the provided context. Structure responses to be concise and relevant.
|
|
397
397
|
${VECTORIZE_PROMPT}
|
|
@@ -408,7 +408,7 @@ import { MONGODB_PROMPT } from '@mastra/mongodb'
|
|
|
408
408
|
export const ragAgent = new Agent({
|
|
409
409
|
id: 'rag-agent',
|
|
410
410
|
name: 'RAG Agent',
|
|
411
|
-
model: 'openai/gpt-5.
|
|
411
|
+
model: 'openai/gpt-5.5',
|
|
412
412
|
instructions: `
|
|
413
413
|
Process queries using the provided context. Structure responses to be concise and relevant.
|
|
414
414
|
${MONGODB_PROMPT}
|
|
@@ -425,7 +425,7 @@ import { OPENSEARCH_PROMPT } from '@mastra/opensearch'
|
|
|
425
425
|
export const ragAgent = new Agent({
|
|
426
426
|
id: 'rag-agent',
|
|
427
427
|
name: 'RAG Agent',
|
|
428
|
-
model: 'openai/gpt-5.
|
|
428
|
+
model: 'openai/gpt-5.5',
|
|
429
429
|
instructions: `
|
|
430
430
|
Process queries using the provided context. Structure responses to be concise and relevant.
|
|
431
431
|
${OPENSEARCH_PROMPT}
|
|
@@ -442,7 +442,7 @@ import { S3VECTORS_PROMPT } from '@mastra/s3vectors'
|
|
|
442
442
|
export const ragAgent = new Agent({
|
|
443
443
|
id: 'rag-agent',
|
|
444
444
|
name: 'RAG Agent',
|
|
445
|
-
model: 'openai/gpt-5.
|
|
445
|
+
model: 'openai/gpt-5.5',
|
|
446
446
|
instructions: `
|
|
447
447
|
Process queries using the provided context. Structure responses to be concise and relevant.
|
|
448
448
|
${S3VECTORS_PROMPT}
|
|
@@ -472,7 +472,10 @@ const initialResults = await pgVector.query({
|
|
|
472
472
|
})
|
|
473
473
|
|
|
474
474
|
// Create a relevance scorer
|
|
475
|
-
const relevanceProvider = new MastraAgentRelevanceScorer(
|
|
475
|
+
const relevanceProvider = new MastraAgentRelevanceScorer(
|
|
476
|
+
'relevance-scorer',
|
|
477
|
+
'openai/gpt-5.5',
|
|
478
|
+
)
|
|
476
479
|
|
|
477
480
|
// Re-rank the results
|
|
478
481
|
const rerankedResults = await rerank({
|
|
@@ -1,8 +1,8 @@
|
|
|
1
|
-
# Storing
|
|
1
|
+
# Storing embeddings in a vector database
|
|
2
2
|
|
|
3
3
|
After generating embeddings, you need to store them in a database that supports vector similarity search. Mastra provides a consistent interface for storing and querying embeddings across various vector databases.
|
|
4
4
|
|
|
5
|
-
## Supported
|
|
5
|
+
## Supported databases
|
|
6
6
|
|
|
7
7
|
**MongoDB**:
|
|
8
8
|
|
|
@@ -234,7 +234,7 @@ await store.upsert({
|
|
|
234
234
|
})
|
|
235
235
|
```
|
|
236
236
|
|
|
237
|
-
**
|
|
237
|
+
**Elasticsearch**:
|
|
238
238
|
|
|
239
239
|
```ts
|
|
240
240
|
import { ElasticSearchVector } from '@mastra/elasticsearch'
|
|
@@ -337,7 +337,7 @@ await store.upsert({
|
|
|
337
337
|
})
|
|
338
338
|
```
|
|
339
339
|
|
|
340
|
-
## Using
|
|
340
|
+
## Using vector storage
|
|
341
341
|
|
|
342
342
|
Once initialized, all vector stores share the same interface for creating indexes, upserting embeddings, and querying.
|
|
343
343
|
|
|
@@ -355,11 +355,11 @@ await store.createIndex({
|
|
|
355
355
|
|
|
356
356
|
The dimension size must match the output dimension of your chosen embedding model. Common dimension sizes are:
|
|
357
357
|
|
|
358
|
-
- OpenAI text-embedding-3-small
|
|
359
|
-
- Cohere embed-multilingual-v3
|
|
360
|
-
- Google gemini-embedding-001
|
|
358
|
+
- `OpenAI text-embedding-3-small`: 1536 dimensions (or custom, e.g., 256)
|
|
359
|
+
- `Cohere embed-multilingual-v3`: 1024 dimensions
|
|
360
|
+
- `Google gemini-embedding-001`: 768 dimensions (or custom)
|
|
361
361
|
|
|
362
|
-
> **Warning:** Index dimensions
|
|
362
|
+
> **Warning:** Index dimensions can't be changed after creation. To use a different model, delete and recreate the index with the new dimension size.
|
|
363
363
|
|
|
364
364
|
### Naming Rules for Databases
|
|
365
365
|
|
|
@@ -490,7 +490,7 @@ Index names must:
|
|
|
490
490
|
- Example: `My_Index` is not valid (contains uppercase letters)
|
|
491
491
|
- Example: `_myindex` is not valid (begins with underscore)
|
|
492
492
|
|
|
493
|
-
**
|
|
493
|
+
**Elasticsearch**:
|
|
494
494
|
|
|
495
495
|
Index names must:
|
|
496
496
|
|
|
@@ -543,7 +543,7 @@ The upsert operation:
|
|
|
543
543
|
- Creates new vectors if they don't exist
|
|
544
544
|
- Automatically handles batching for large datasets
|
|
545
545
|
|
|
546
|
-
## Adding
|
|
546
|
+
## Adding metadata
|
|
547
547
|
|
|
548
548
|
Vector stores support rich metadata (any JSON-serializable fields) for filtering and organization. Since metadata is stored with no fixed schema, use consistent field naming to avoid unexpected query results.
|
|
549
549
|
|
|
@@ -581,9 +581,9 @@ Key metadata considerations:
|
|
|
581
581
|
- Only include fields you plan to filter or sort by - extra fields add overhead
|
|
582
582
|
- Add timestamps (e.g., 'createdAt', 'lastUpdated') to track content freshness
|
|
583
583
|
|
|
584
|
-
## Deleting
|
|
584
|
+
## Deleting vectors
|
|
585
585
|
|
|
586
|
-
When building RAG applications, you often need to clean up stale vectors when documents are deleted or updated. Mastra provides the `deleteVectors` method that supports deleting vectors by metadata filters, making it
|
|
586
|
+
When building RAG applications, you often need to clean up stale vectors when documents are deleted or updated. Mastra provides the `deleteVectors` method that supports deleting vectors by metadata filters, making it straightforward to remove all embeddings associated with a specific document.
|
|
587
587
|
|
|
588
588
|
### Delete by Metadata Filter
|
|
589
589
|
|
|
@@ -637,7 +637,7 @@ await store.deleteVectors({
|
|
|
637
637
|
})
|
|
638
638
|
```
|
|
639
639
|
|
|
640
|
-
## Best
|
|
640
|
+
## Best practices
|
|
641
641
|
|
|
642
642
|
- Create indexes before bulk insertions
|
|
643
643
|
- Use batch operations for large insertions (the upsert method handles batching automatically)
|
|
@@ -1,72 +1,72 @@
|
|
|
1
|
-
# Pinecone
|
|
1
|
+
# Pinecone vector store
|
|
2
2
|
|
|
3
3
|
The PineconeVector class provides an interface to [Pinecone](https://www.pinecone.io/)'s vector database. It provides real-time vector search, with features like hybrid search, metadata filtering, and namespace management.
|
|
4
4
|
|
|
5
|
-
## Constructor
|
|
5
|
+
## Constructor options
|
|
6
6
|
|
|
7
7
|
The constructor accepts all [Pinecone configuration options](https://docs.pinecone.io/reference/typescript-sdk) plus Mastra-specific fields.
|
|
8
8
|
|
|
9
|
-
**id
|
|
9
|
+
**id** (`string`): Unique identifier for this vector store instance
|
|
10
10
|
|
|
11
|
-
**apiKey
|
|
11
|
+
**apiKey** (`string`): Pinecone API key
|
|
12
12
|
|
|
13
|
-
**controllerHostUrl
|
|
13
|
+
**controllerHostUrl** (`string`): Custom Pinecone controller host URL
|
|
14
14
|
|
|
15
|
-
**additionalHeaders
|
|
15
|
+
**additionalHeaders** (`Record<string, string>`): Additional HTTP headers to include in requests
|
|
16
16
|
|
|
17
|
-
**sourceTag
|
|
17
|
+
**sourceTag** (`string`): Source tag for request tracking
|
|
18
18
|
|
|
19
|
-
**cloud
|
|
19
|
+
**cloud** (`'aws' | 'gcp' | 'azure'`): Cloud provider for new index creation (Default: `aws`)
|
|
20
20
|
|
|
21
|
-
**region
|
|
21
|
+
**region** (`string`): Region for new index creation (Default: `us-east-1`)
|
|
22
22
|
|
|
23
23
|
## Methods
|
|
24
24
|
|
|
25
|
-
### createIndex()
|
|
25
|
+
### `createIndex()`
|
|
26
26
|
|
|
27
|
-
**indexName
|
|
27
|
+
**indexName** (`string`): Name of the index to create
|
|
28
28
|
|
|
29
|
-
**dimension
|
|
29
|
+
**dimension** (`number`): Vector dimension (must match your embedding model)
|
|
30
30
|
|
|
31
|
-
**metric
|
|
31
|
+
**metric** (`'cosine' | 'euclidean' | 'dotproduct'`): Distance metric for similarity search. Use 'dotproduct' if you plan to use hybrid search. (Default: `cosine`)
|
|
32
32
|
|
|
33
|
-
### upsert()
|
|
33
|
+
### `upsert()`
|
|
34
34
|
|
|
35
|
-
**indexName
|
|
35
|
+
**indexName** (`string`): Name of your Pinecone index
|
|
36
36
|
|
|
37
|
-
**vectors
|
|
37
|
+
**vectors** (`number[][]`): Array of dense embedding vectors
|
|
38
38
|
|
|
39
|
-
**sparseVectors
|
|
39
|
+
**sparseVectors** (`{ indices: number[], values: number[] }[]`): Array of sparse vectors for hybrid search. Each vector must have matching indices and values arrays.
|
|
40
40
|
|
|
41
|
-
**metadata
|
|
41
|
+
**metadata** (`Record<string, any>[]`): Metadata for each vector
|
|
42
42
|
|
|
43
|
-
**ids
|
|
43
|
+
**ids** (`string[]`): Optional vector IDs (auto-generated if not provided)
|
|
44
44
|
|
|
45
|
-
**namespace
|
|
45
|
+
**namespace** (`string`): Optional namespace to store vectors in. Vectors in different namespaces are isolated from each other.
|
|
46
46
|
|
|
47
|
-
### query()
|
|
47
|
+
### `query()`
|
|
48
48
|
|
|
49
|
-
**indexName
|
|
49
|
+
**indexName** (`string`): Name of the index to query
|
|
50
50
|
|
|
51
|
-
**queryVector
|
|
51
|
+
**queryVector** (`number[]`): Dense query vector to find similar vectors
|
|
52
52
|
|
|
53
|
-
**sparseVector
|
|
53
|
+
**sparseVector** (`{ indices: number[], values: number[] }`): Optional sparse vector for hybrid search. Must have matching indices and values arrays.
|
|
54
54
|
|
|
55
|
-
**topK
|
|
55
|
+
**topK** (`number`): Number of results to return (Default: `10`)
|
|
56
56
|
|
|
57
|
-
**filter
|
|
57
|
+
**filter** (`Record<string, any>`): Metadata filters for the query
|
|
58
58
|
|
|
59
|
-
**includeVector
|
|
59
|
+
**includeVector** (`boolean`): Whether to include the vector in the result (Default: `false`)
|
|
60
60
|
|
|
61
|
-
**namespace
|
|
61
|
+
**namespace** (`string`): Optional namespace to query vectors from. Only returns results from the specified namespace.
|
|
62
62
|
|
|
63
|
-
### listIndexes()
|
|
63
|
+
### `listIndexes()`
|
|
64
64
|
|
|
65
65
|
Returns an array of index names as strings.
|
|
66
66
|
|
|
67
|
-
### describeIndex()
|
|
67
|
+
### `describeIndex()`
|
|
68
68
|
|
|
69
|
-
**indexName
|
|
69
|
+
**indexName** (`string`): Name of the index to describe
|
|
70
70
|
|
|
71
71
|
Returns:
|
|
72
72
|
|
|
@@ -78,47 +78,47 @@ interface IndexStats {
|
|
|
78
78
|
}
|
|
79
79
|
```
|
|
80
80
|
|
|
81
|
-
### deleteIndex()
|
|
81
|
+
### `deleteIndex()`
|
|
82
82
|
|
|
83
|
-
**indexName
|
|
83
|
+
**indexName** (`string`): Name of the index to delete
|
|
84
84
|
|
|
85
|
-
### updateVector()
|
|
85
|
+
### `updateVector()`
|
|
86
86
|
|
|
87
87
|
Update a single vector by ID or by metadata filter. Either `id` or `filter` must be provided, but not both.
|
|
88
88
|
|
|
89
|
-
**indexName
|
|
89
|
+
**indexName** (`string`): Name of the index containing the vector
|
|
90
90
|
|
|
91
|
-
**id
|
|
91
|
+
**id** (`string`): ID of the vector to update (mutually exclusive with filter)
|
|
92
92
|
|
|
93
|
-
**filter
|
|
93
|
+
**filter** (`Record<string, any>`): Metadata filter to identify vector(s) to update (mutually exclusive with id)
|
|
94
94
|
|
|
95
|
-
**namespace
|
|
95
|
+
**namespace** (`string`): Optional namespace for the update operation
|
|
96
96
|
|
|
97
|
-
**update
|
|
97
|
+
**update** (`object`): Update parameters
|
|
98
98
|
|
|
99
|
-
**update.vector
|
|
99
|
+
**update.vector** (`number[]`): New vector values to update
|
|
100
100
|
|
|
101
|
-
**update.metadata
|
|
101
|
+
**update.metadata** (`Record<string, any>`): New metadata to update
|
|
102
102
|
|
|
103
|
-
### deleteVector()
|
|
103
|
+
### `deleteVector()`
|
|
104
104
|
|
|
105
|
-
**indexName
|
|
105
|
+
**indexName** (`string`): Name of the index containing the vector
|
|
106
106
|
|
|
107
|
-
**id
|
|
107
|
+
**id** (`string`): ID of the vector to delete
|
|
108
108
|
|
|
109
|
-
### deleteVectors()
|
|
109
|
+
### `deleteVectors()`
|
|
110
110
|
|
|
111
111
|
Delete multiple vectors by IDs or by metadata filter. Either `ids` or `filter` must be provided, but not both.
|
|
112
112
|
|
|
113
|
-
**indexName
|
|
113
|
+
**indexName** (`string`): Name of the index containing the vectors to delete
|
|
114
114
|
|
|
115
|
-
**ids
|
|
115
|
+
**ids** (`string[]`): Array of vector IDs to delete (mutually exclusive with filter)
|
|
116
116
|
|
|
117
|
-
**filter
|
|
117
|
+
**filter** (`Record<string, any>`): Metadata filter to identify vectors to delete (mutually exclusive with ids)
|
|
118
118
|
|
|
119
|
-
**namespace
|
|
119
|
+
**namespace** (`string`): Optional namespace for the deletion operation
|
|
120
120
|
|
|
121
|
-
## Response
|
|
121
|
+
## Response types
|
|
122
122
|
|
|
123
123
|
Query results are returned in this format:
|
|
124
124
|
|
|
@@ -131,7 +131,7 @@ interface QueryResult {
|
|
|
131
131
|
}
|
|
132
132
|
```
|
|
133
133
|
|
|
134
|
-
## Error
|
|
134
|
+
## Error handling
|
|
135
135
|
|
|
136
136
|
The store throws typed errors that can be caught:
|
|
137
137
|
|
|
@@ -149,13 +149,13 @@ try {
|
|
|
149
149
|
}
|
|
150
150
|
```
|
|
151
151
|
|
|
152
|
-
### Environment
|
|
152
|
+
### Environment variables
|
|
153
153
|
|
|
154
154
|
Required environment variables:
|
|
155
155
|
|
|
156
156
|
- `PINECONE_API_KEY`: Your Pinecone API key
|
|
157
157
|
|
|
158
|
-
## Hybrid
|
|
158
|
+
## Hybrid search
|
|
159
159
|
|
|
160
160
|
Pinecone supports hybrid search by combining dense and sparse vectors. To use hybrid search:
|
|
161
161
|
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@mastra/pinecone",
|
|
3
|
-
"version": "1.0.
|
|
3
|
+
"version": "1.1.0-alpha.0",
|
|
4
4
|
"description": "Pinecone vector store provider for Mastra",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"main": "dist/index.js",
|
|
@@ -23,18 +23,19 @@
|
|
|
23
23
|
"@pinecone-database/pinecone": "^3.0.3"
|
|
24
24
|
},
|
|
25
25
|
"devDependencies": {
|
|
26
|
-
"@types/node": "22.19.
|
|
27
|
-
"@vitest/coverage-v8": "4.
|
|
28
|
-
"@vitest/ui": "4.
|
|
29
|
-
"dotenv": "^17.2
|
|
30
|
-
"eslint": "^
|
|
26
|
+
"@types/node": "22.19.21",
|
|
27
|
+
"@vitest/coverage-v8": "4.1.8",
|
|
28
|
+
"@vitest/ui": "4.1.8",
|
|
29
|
+
"dotenv": "^17.4.2",
|
|
30
|
+
"eslint": "^10.4.1",
|
|
31
31
|
"tsup": "^8.5.1",
|
|
32
|
-
"
|
|
33
|
-
"
|
|
34
|
-
"
|
|
35
|
-
"@internal/
|
|
36
|
-
"@internal/storage-test-utils": "0.0.
|
|
37
|
-
"@
|
|
32
|
+
"tsx": "^4.22.4",
|
|
33
|
+
"typescript": "^6.0.3",
|
|
34
|
+
"vitest": "4.1.8",
|
|
35
|
+
"@internal/lint": "0.0.106",
|
|
36
|
+
"@internal/storage-test-utils": "0.0.102",
|
|
37
|
+
"@internal/types-builder": "0.0.81",
|
|
38
|
+
"@mastra/core": "1.45.0-alpha.0"
|
|
38
39
|
},
|
|
39
40
|
"peerDependencies": {
|
|
40
41
|
"@mastra/core": ">=1.0.0-0 <2.0.0-0"
|