@mastra/pg 0.0.0-bundle-recursion-20251030002519 → 0.0.0-bundle-version-20260121091645

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.
Files changed (57) hide show
  1. package/CHANGELOG.md +2092 -4
  2. package/README.md +72 -20
  3. package/dist/docs/README.md +36 -0
  4. package/dist/docs/SKILL.md +37 -0
  5. package/dist/docs/SOURCE_MAP.json +6 -0
  6. package/dist/docs/memory/01-storage.md +233 -0
  7. package/dist/docs/memory/02-working-memory.md +390 -0
  8. package/dist/docs/memory/03-semantic-recall.md +233 -0
  9. package/dist/docs/memory/04-reference.md +133 -0
  10. package/dist/docs/processors/01-reference.md +297 -0
  11. package/dist/docs/rag/01-overview.md +74 -0
  12. package/dist/docs/rag/02-vector-databases.md +643 -0
  13. package/dist/docs/rag/03-retrieval.md +548 -0
  14. package/dist/docs/rag/04-reference.md +369 -0
  15. package/dist/docs/storage/01-reference.md +824 -0
  16. package/dist/docs/tools/01-reference.md +440 -0
  17. package/dist/docs/vectors/01-reference.md +307 -0
  18. package/dist/index.cjs +3834 -2284
  19. package/dist/index.cjs.map +1 -1
  20. package/dist/index.d.ts +1 -1
  21. package/dist/index.d.ts.map +1 -1
  22. package/dist/index.js +3817 -2272
  23. package/dist/index.js.map +1 -1
  24. package/dist/shared/config.d.ts +122 -31
  25. package/dist/shared/config.d.ts.map +1 -1
  26. package/dist/storage/client.d.ts +91 -0
  27. package/dist/storage/client.d.ts.map +1 -0
  28. package/dist/storage/db/index.d.ts +216 -0
  29. package/dist/storage/db/index.d.ts.map +1 -0
  30. package/dist/storage/domains/agents/index.d.ts +39 -0
  31. package/dist/storage/domains/agents/index.d.ts.map +1 -0
  32. package/dist/storage/domains/memory/index.d.ts +44 -55
  33. package/dist/storage/domains/memory/index.d.ts.map +1 -1
  34. package/dist/storage/domains/observability/index.d.ts +55 -39
  35. package/dist/storage/domains/observability/index.d.ts.map +1 -1
  36. package/dist/storage/domains/scores/index.d.ts +30 -33
  37. package/dist/storage/domains/scores/index.d.ts.map +1 -1
  38. package/dist/storage/domains/utils.d.ts +1 -5
  39. package/dist/storage/domains/utils.d.ts.map +1 -1
  40. package/dist/storage/domains/workflows/index.d.ts +34 -28
  41. package/dist/storage/domains/workflows/index.d.ts.map +1 -1
  42. package/dist/storage/index.d.ts +52 -244
  43. package/dist/storage/index.d.ts.map +1 -1
  44. package/dist/storage/performance-indexes/performance-test.d.ts +3 -1
  45. package/dist/storage/performance-indexes/performance-test.d.ts.map +1 -1
  46. package/dist/storage/test-utils.d.ts.map +1 -1
  47. package/dist/vector/index.d.ts +45 -7
  48. package/dist/vector/index.d.ts.map +1 -1
  49. package/dist/vector/sql-builder.d.ts +4 -0
  50. package/dist/vector/sql-builder.d.ts.map +1 -1
  51. package/dist/vector/types.d.ts +10 -0
  52. package/dist/vector/types.d.ts.map +1 -1
  53. package/package.json +18 -14
  54. package/dist/storage/domains/legacy-evals/index.d.ts +0 -20
  55. package/dist/storage/domains/legacy-evals/index.d.ts.map +0 -1
  56. package/dist/storage/domains/operations/index.d.ts +0 -119
  57. package/dist/storage/domains/operations/index.d.ts.map +0 -1
package/README.md CHANGED
@@ -115,26 +115,32 @@ const store = new PostgresStore({
115
115
 
116
116
  // Create a thread
117
117
  await store.saveThread({
118
- id: 'thread-123',
119
- resourceId: 'resource-456',
120
- title: 'My Thread',
121
- metadata: { key: 'value' },
118
+ thread: {
119
+ id: 'thread-123',
120
+ resourceId: 'resource-456',
121
+ title: 'My Thread',
122
+ metadata: { key: 'value' },
123
+ createdAt: new Date(),
124
+ },
122
125
  });
123
126
 
124
127
  // Add messages to thread
125
- await store.saveMessages([
126
- {
127
- id: 'msg-789',
128
- threadId: 'thread-123',
129
- role: 'user',
130
- type: 'text',
131
- content: [{ type: 'text', text: 'Hello' }],
132
- },
133
- ]);
128
+ await store.saveMessages({
129
+ messages: [
130
+ {
131
+ id: 'msg-789',
132
+ threadId: 'thread-123',
133
+ role: 'user',
134
+ content: { content: 'Hello' },
135
+ resourceId: 'resource-456',
136
+ createdAt: new Date(),
137
+ },
138
+ ],
139
+ });
134
140
 
135
141
  // Query threads and messages
136
- const savedThread = await store.getThread('thread-123');
137
- const messages = await store.getMessages('thread-123');
142
+ const savedThread = await store.getThreadById({ threadId: 'thread-123' });
143
+ const messages = await store.listMessages({ threadId: 'thread-123' });
138
144
  ```
139
145
 
140
146
  ## Configuration
@@ -321,6 +327,9 @@ The system automatically detects configuration changes and only rebuilds indexes
321
327
  - `buildIndex({indexName, metric?, indexConfig?})`: Build or rebuild vector index
322
328
  - `upsert({indexName, vectors, metadata?, ids?})`: Add or update vectors
323
329
  - `query({indexName, queryVector, topK?, filter?, includeVector?, minScore?})`: Search for similar vectors
330
+ - `updateVector({ indexName, id?, filter?, update })`: Update a single vector by ID or metadata filter
331
+ - `deleteVector({ indexName, id })`: Delete a single vector by ID
332
+ - `deleteVectors({ indexName, ids?, filter? })`: Delete multiple vectors by IDs or metadata filter
324
333
  - `listIndexes()`: List all vector-enabled tables
325
334
  - `describeIndex(indexName)`: Get table statistics and index configuration
326
335
  - `deleteIndex(indexName)`: Delete a table
@@ -329,13 +338,56 @@ The system automatically detects configuration changes and only rebuilds indexes
329
338
 
330
339
  ## Storage Methods
331
340
 
332
- - `saveThread(thread)`: Create or update a thread
333
- - `getThread(threadId)`: Get a thread by ID
334
- - `deleteThread(threadId)`: Delete a thread and its messages
335
- - `saveMessages(messages)`: Save multiple messages in a transaction
336
- - `getMessages(threadId)`: Get all messages for a thread
341
+ ### Thread Operations
342
+
343
+ - `saveThread({ thread })`: Create or update a thread
344
+ - `getThreadById({ threadId })`: Get a thread by ID
345
+ - `updateThread({ id, title, metadata })`: Update thread title and/or metadata
346
+ - `deleteThread({ threadId })`: Delete a thread and its messages
347
+ - `listThreadsByResourceId({ resourceId, offset, limit, orderBy? })`: List paginated threads for a resource
348
+
349
+ ### Message Operations
350
+
351
+ - `saveMessages({ messages })`: Save multiple messages in a transaction
352
+ - `listMessages({ threadId, resourceId?, perPage?, page?, orderBy?, filter? })`: Get messages for a thread with pagination
353
+ - `listMessagesById({ messageIds })`: Get specific messages by their IDs
354
+ - `updateMessages({ messages })`: Update existing messages
337
355
  - `deleteMessages(messageIds)`: Delete specific messages
338
356
 
357
+ ### Resource Operations
358
+
359
+ - `getResourceById({ resourceId })`: Get a resource by ID
360
+ - `saveResource({ resource })`: Create or save a resource
361
+ - `updateResource({ resourceId, workingMemory })`: Update resource working memory
362
+
363
+ ### Workflow Operations
364
+
365
+ - `persistWorkflowSnapshot({ workflowName, runId, snapshot })`: Save workflow state
366
+ - `loadWorkflowSnapshot({ workflowName, runId })`: Load workflow state
367
+ - `listWorkflowRuns({ workflowName, pagination })`: List workflow runs with pagination
368
+ - `getWorkflowRunById({ workflowName, runId })`: Get a specific workflow run
369
+ - `updateWorkflowState({ workflowName, runId, state })`: Update workflow state
370
+ - `updateWorkflowResults({ workflowName, runId, results })`: Update workflow results
371
+
372
+ ### AI Observability Operations
373
+
374
+ - `createSpan(span)`: Create a single AI span
375
+ - `batchCreateSpans({ records })`: Create multiple AI spans
376
+ - `updateSpan({ traceId, spanId, updates })`: Update an AI span
377
+ - `batchUpdateSpans({ updates })`: Update multiple AI spans
378
+ - `getTrace(traceId)`: Get an trace by ID
379
+ - `getTracesPaginated({ ...filters, pagination })`: Get paginated traces with filtering
380
+ - `batchDeleteTraces({ traceIds })`: Delete multiple traces
381
+
382
+ ### Evaluation/Scoring Operations
383
+
384
+ - `getScoreById({ id })`: Get a score by ID
385
+ - `saveScore(score)`: Save an evaluation score
386
+ - `listScoresByScorerId({ scorerId, pagination })`: List scores by scorer with pagination
387
+ - `listScoresByRunId({ runId, pagination })`: List scores by run with pagination
388
+ - `listScoresByEntityId({ entityId, entityType, pagination })`: List scores by entity with pagination
389
+ - `listScoresBySpan({ traceId, spanId, pagination })`: List scores by span with pagination
390
+
339
391
  ## Index Management
340
392
 
341
393
  The PostgreSQL store provides comprehensive index management capabilities to optimize query performance.
@@ -0,0 +1,36 @@
1
+ # @mastra/pg Documentation
2
+
3
+ > Embedded documentation for coding agents
4
+
5
+ ## Quick Start
6
+
7
+ ```bash
8
+ # Read the skill overview
9
+ cat docs/SKILL.md
10
+
11
+ # Get the source map
12
+ cat docs/SOURCE_MAP.json
13
+
14
+ # Read topic documentation
15
+ cat docs/<topic>/01-overview.md
16
+ ```
17
+
18
+ ## Structure
19
+
20
+ ```
21
+ docs/
22
+ ├── SKILL.md # Entry point
23
+ ├── README.md # This file
24
+ ├── SOURCE_MAP.json # Export index
25
+ ├── memory/ (4 files)
26
+ ├── processors/ (3 files)
27
+ ├── rag/ (4 files)
28
+ ├── storage/ (3 files)
29
+ ├── tools/ (1 files)
30
+ ├── vectors/ (1 files)
31
+ ```
32
+
33
+ ## Version
34
+
35
+ Package: @mastra/pg
36
+ Version: 1.0.0
@@ -0,0 +1,37 @@
1
+ ---
2
+ name: mastra-pg-docs
3
+ description: Documentation for @mastra/pg. Includes links to type definitions and readable implementation code in dist/.
4
+ ---
5
+
6
+ # @mastra/pg Documentation
7
+
8
+ > **Version**: 1.0.0
9
+ > **Package**: @mastra/pg
10
+
11
+ ## Quick Navigation
12
+
13
+ Use SOURCE_MAP.json to find any export:
14
+
15
+ ```bash
16
+ cat docs/SOURCE_MAP.json
17
+ ```
18
+
19
+ Each export maps to:
20
+ - **types**: `.d.ts` file with JSDoc and API signatures
21
+ - **implementation**: `.js` chunk file with readable source
22
+ - **docs**: Conceptual documentation in `docs/`
23
+
24
+ ## Top Exports
25
+
26
+
27
+
28
+ See SOURCE_MAP.json for the complete list.
29
+
30
+ ## Available Topics
31
+
32
+ - [Memory](memory/) - 4 file(s)
33
+ - [Processors](processors/) - 3 file(s)
34
+ - [Rag](rag/) - 4 file(s)
35
+ - [Storage](storage/) - 3 file(s)
36
+ - [Tools](tools/) - 1 file(s)
37
+ - [Vectors](vectors/) - 1 file(s)
@@ -0,0 +1,6 @@
1
+ {
2
+ "version": "1.0.0",
3
+ "package": "@mastra/pg",
4
+ "exports": {},
5
+ "modules": {}
6
+ }
@@ -0,0 +1,233 @@
1
+ > Configure storage for Mastra
2
+
3
+ # Storage
4
+
5
+ For Mastra to remember previous interactions, you must configure a storage adapter. Mastra is designed to work with your preferred database provider - choose from the [supported providers](#supported-providers) and pass it to your Mastra instance.
6
+
7
+ ```typescript title="src/mastra/index.ts"
8
+ import { Mastra } from "@mastra/core";
9
+ import { LibSQLStore } from "@mastra/libsql";
10
+
11
+ export const mastra = new Mastra({
12
+ storage: new LibSQLStore({
13
+ id: 'mastra-storage',
14
+ url: "file:./mastra.db",
15
+ }),
16
+ });
17
+ ```
18
+ On first interaction, Mastra automatically creates the necessary tables following the [core schema](https://mastra.ai/reference/storage/overview#core-schema). This includes tables for messages, threads, resources, workflows, traces, and evaluation datasets.
19
+
20
+ ## Supported providers
21
+
22
+ Each provider page includes installation instructions, configuration parameters, and usage examples:
23
+
24
+ - [libSQL Storage](https://mastra.ai/reference/storage/libsql)
25
+ - [PostgreSQL Storage](https://mastra.ai/reference/storage/postgresql)
26
+ - [MongoDB Storage](https://mastra.ai/reference/storage/mongodb)
27
+ - [Upstash Storage](https://mastra.ai/reference/storage/upstash)
28
+ - [Cloudflare D1](https://mastra.ai/reference/storage/cloudflare-d1)
29
+ - [Cloudflare Durable Objects](https://mastra.ai/reference/storage/cloudflare)
30
+ - [Convex](https://mastra.ai/reference/storage/convex)
31
+ - [DynamoDB](https://mastra.ai/reference/storage/dynamodb)
32
+ - [LanceDB](https://mastra.ai/reference/storage/lance)
33
+ - [Microsoft SQL Server](https://mastra.ai/reference/storage/mssql)
34
+
35
+ > **Note:**
36
+ libSQL is the easiest way to get started because it doesn’t require running a separate database server
37
+
38
+ ## Configuration scope
39
+
40
+ You can configure storage at two different scopes:
41
+
42
+ ### Instance-level storage
43
+
44
+ Add storage to your Mastra instance so all agents, workflows, observability traces and scores share the same memory provider:
45
+
46
+ ```typescript
47
+ import { Mastra } from "@mastra/core";
48
+ import { PostgresStore } from "@mastra/pg";
49
+
50
+ export const mastra = new Mastra({
51
+ storage: new PostgresStore({
52
+ id: 'mastra-storage',
53
+ connectionString: process.env.DATABASE_URL,
54
+ }),
55
+ });
56
+
57
+ // All agents automatically use this storage
58
+ const agent1 = new Agent({ id: "agent-1", memory: new Memory() });
59
+ const agent2 = new Agent({ id: "agent-2", memory: new Memory() });
60
+ ```
61
+
62
+ This is useful when all primitives share the same storage backend and have similar performance, scaling, and operational requirements.
63
+
64
+ #### Composite storage
65
+
66
+ Add storage to your Mastra instance using `MastraCompositeStore` and configure individual storage domains to use different storage providers.
67
+
68
+ ```typescript title="src/mastra/index.ts"
69
+ import { Mastra } from "@mastra/core";
70
+ import { MastraCompositeStore } from "@mastra/core/storage";
71
+ import { MemoryLibSQL } from "@mastra/libsql";
72
+ import { WorkflowsPG } from "@mastra/pg";
73
+ import { ObservabilityStorageClickhouse } from "@mastra/clickhouse";
74
+
75
+ export const mastra = new Mastra({
76
+ storage: new MastraCompositeStore({
77
+ id: "composite",
78
+ domains: {
79
+ memory: new MemoryLibSQL({ url: "file:./memory.db" }),
80
+ workflows: new WorkflowsPG({ connectionString: process.env.DATABASE_URL }),
81
+ observability: new ObservabilityStorageClickhouse({
82
+ url: process.env.CLICKHOUSE_URL,
83
+ username: process.env.CLICKHOUSE_USERNAME,
84
+ password: process.env.CLICKHOUSE_PASSWORD,
85
+ }),
86
+ },
87
+ }),
88
+ });
89
+ ```
90
+
91
+ This is useful when different types of data have different performance or operational requirements, such as low-latency storage for memory, durable storage for workflows, and high-throughput storage for observability.
92
+
93
+ > **Note:**
94
+ See [Storage Domains](https://mastra.ai/reference/storage/composite#storage-domains) for more information.
95
+
96
+ ### Agent-level storage
97
+
98
+ Agent-level storage overrides storage configured at the instance-level. Add storage to a specific agent when you need data boundaries or compliance requirements:
99
+
100
+ ```typescript title="src/mastra/agents/memory-agent.ts"
101
+ import { Agent } from "@mastra/core/agent";
102
+ import { Memory } from "@mastra/memory";
103
+ import { PostgresStore } from "@mastra/pg";
104
+
105
+ export const agent = new Agent({
106
+ id: "agent",
107
+ memory: new Memory({
108
+ storage: new PostgresStore({
109
+ id: 'agent-storage',
110
+ connectionString: process.env.AGENT_DATABASE_URL,
111
+ }),
112
+ }),
113
+ });
114
+ ```
115
+
116
+ This is useful when different agents need to store data in separate databases for security, compliance, or organizational reasons.
117
+
118
+ > **Mastra Cloud Store limitation**
119
+ Agent-level storage is not supported when using [Mastra Cloud Store](https://mastra.ai/docs/mastra-cloud/deployment#using-mastra-cloud-store). If you use Mastra Cloud Store, configure storage on the Mastra instance instead. This limitation does not apply if you bring your own database.
120
+
121
+ ## Threads and resources
122
+
123
+ Mastra organizes memory into threads using two identifiers:
124
+
125
+ - **Thread**: A conversation session containing a sequence of messages (e.g., `convo_123`)
126
+ - **Resource**: An identifier for the entity the thread belongs to, typically a user (e.g., `user_123`)
127
+
128
+ Both identifiers are required for agents to store and recall information:
129
+
130
+ ```typescript
131
+ const stream = await agent.stream("message for agent", {
132
+ memory: {
133
+ thread: "convo_123",
134
+ resource: "user_123",
135
+ },
136
+ });
137
+ ```
138
+
139
+ > **Note:**
140
+ [Studio](https://mastra.ai/docs/getting-started/studio) automatically generates a thread and resource ID for you. Remember to to pass these explicitly when calling `stream` or `generate` yourself.
141
+
142
+ ### Thread and resource relationship
143
+
144
+ Each thread has an owner (its `resourceId`) that is set when the thread is created and cannot be changed. When you query a thread, you must use the correct owner's resource ID. Attempting to query a thread with a different resource ID will result in an error:
145
+
146
+ ```text
147
+ Thread with id <thread_id> is for resource with id <resource_a>
148
+ but resource <resource_b> was queried
149
+ ```
150
+
151
+ Note that while each thread has one owner, messages within that thread can have different `resourceId` values. This is used for message attribution and filtering (e.g., distinguishing between different agents in a multi-agent system, or filtering messages for analytics).
152
+
153
+ **Security:** Memory is a storage layer, not an authorization layer. Your application must implement access control before calling memory APIs. The `resourceId` parameter controls both validation and filtering - provide it to validate ownership and filter messages, or omit it for server-side access without validation.
154
+
155
+ To avoid accidentally reusing thread IDs across different owners, use UUIDs: `crypto.randomUUID()`
156
+
157
+ ### Thread title generation
158
+
159
+ Mastra can automatically generate descriptive thread titles based on the user's first message.
160
+
161
+ Use this option when implementing a ChatGPT-style chat interface to render a title alongside each thread in the conversation list (for example, in a sidebar) derived from the thread’s initial user message.
162
+
163
+ ```typescript
164
+ export const testAgent = new Agent({
165
+ id: "test-agent",
166
+ memory: new Memory({
167
+ options: {
168
+ generateTitle: true,
169
+ },
170
+ }),
171
+ });
172
+ ```
173
+
174
+ Title generation runs asynchronously after the agent responds and does not affect response time.
175
+
176
+ To optimize cost or behavior, provide a smaller `model` and custom `instructions`:
177
+
178
+ ```typescript
179
+ export const testAgent = new Agent({
180
+ id: "test-agent",
181
+ memory: new Memory({
182
+ options: {
183
+ generateTitle: {
184
+ model: "openai/gpt-4o-mini",
185
+ instructions: "Generate a concise title based on the user's first message",
186
+ },
187
+ },
188
+ }),
189
+ });
190
+ ```
191
+
192
+ ## Semantic recall
193
+
194
+ Semantic recall uses vector embeddings to retrieve relevant past messages based on meaning rather than recency. This requires a vector database instance, which can be configured at the instance or agent level.
195
+
196
+ The vector database doesn't have to be the same as your storage provider. For example, you might use PostgreSQL for storage and Pinecone for vectors:
197
+
198
+ ```typescript
199
+ import { Mastra } from "@mastra/core";
200
+ import { Agent } from "@mastra/core/agent";
201
+ import { Memory } from "@mastra/memory";
202
+ import { PostgresStore } from "@mastra/pg";
203
+ import { PineconeVector } from "@mastra/pinecone";
204
+
205
+ // Instance-level vector configuration
206
+ export const mastra = new Mastra({
207
+ storage: new PostgresStore({
208
+ id: 'mastra-storage',
209
+ connectionString: process.env.DATABASE_URL,
210
+ }),
211
+ });
212
+
213
+ // Agent-level vector configuration
214
+ export const agent = new Agent({
215
+ id: "agent",
216
+ memory: new Memory({
217
+ vector: new PineconeVector({
218
+ id: 'agent-vector',
219
+ apiKey: process.env.PINECONE_API_KEY,
220
+ }),
221
+ options: {
222
+ semanticRecall: {
223
+ topK: 5,
224
+ messageRange: 2,
225
+ },
226
+ },
227
+ }),
228
+ });
229
+ ```
230
+
231
+ We support all popular vector providers including [Pinecone](https://mastra.ai/reference/vectors/pinecone), [Chroma](https://mastra.ai/reference/vectors/chroma), [Qdrant](https://mastra.ai/reference/vectors/qdrant), and many more.
232
+
233
+ For more information on configuring semantic recall, see the [Semantic Recall](./semantic-recall) documentation.