@mastra/libsql 0.0.0-workflow-timeout-issue-20260220185702 → 0.0.0-workflow-graph-crash-20260527191009

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 (73) hide show
  1. package/CHANGELOG.md +1085 -3
  2. package/LICENSE.md +15 -0
  3. package/dist/docs/SKILL.md +18 -19
  4. package/dist/docs/assets/SOURCE_MAP.json +1 -1
  5. package/dist/docs/references/docs-agent-builder-deploying.md +121 -0
  6. package/dist/docs/references/docs-agent-builder-overview.md +97 -0
  7. package/dist/docs/references/docs-agents-agent-approval.md +336 -202
  8. package/dist/docs/references/docs-agents-networks.md +107 -215
  9. package/dist/docs/references/docs-memory-memory-processors.md +86 -88
  10. package/dist/docs/references/docs-memory-message-history.md +71 -63
  11. package/dist/docs/references/docs-memory-multi-user-threads.md +206 -0
  12. package/dist/docs/references/docs-memory-overview.md +221 -24
  13. package/dist/docs/references/docs-memory-semantic-recall.md +162 -75
  14. package/dist/docs/references/docs-memory-storage.md +72 -73
  15. package/dist/docs/references/docs-memory-working-memory.md +62 -62
  16. package/dist/docs/references/docs-rag-retrieval.md +132 -135
  17. package/dist/docs/references/docs-workflows-snapshots.md +31 -31
  18. package/dist/docs/references/guides-agent-frameworks-ai-sdk.md +36 -36
  19. package/dist/docs/references/reference-core-getMemory.md +15 -16
  20. package/dist/docs/references/reference-core-listMemory.md +17 -18
  21. package/dist/docs/references/reference-core-mastra-class.md +37 -27
  22. package/dist/docs/references/reference-memory-memory-class.md +41 -43
  23. package/dist/docs/references/reference-storage-composite.md +65 -55
  24. package/dist/docs/references/reference-storage-dynamodb.md +36 -36
  25. package/dist/docs/references/reference-storage-libsql.md +27 -27
  26. package/dist/docs/references/reference-vectors-libsql.md +72 -72
  27. package/dist/index.cjs +7896 -3257
  28. package/dist/index.cjs.map +1 -1
  29. package/dist/index.js +7888 -3259
  30. package/dist/index.js.map +1 -1
  31. package/dist/storage/db/index.d.ts +14 -1
  32. package/dist/storage/db/index.d.ts.map +1 -1
  33. package/dist/storage/db/utils.d.ts +16 -0
  34. package/dist/storage/db/utils.d.ts.map +1 -1
  35. package/dist/storage/domains/agents/index.d.ts.map +1 -1
  36. package/dist/storage/domains/background-tasks/index.d.ts +18 -0
  37. package/dist/storage/domains/background-tasks/index.d.ts.map +1 -0
  38. package/dist/storage/domains/blobs/index.d.ts +17 -0
  39. package/dist/storage/domains/blobs/index.d.ts.map +1 -0
  40. package/dist/storage/domains/channels/index.d.ts +20 -0
  41. package/dist/storage/domains/channels/index.d.ts.map +1 -0
  42. package/dist/storage/domains/datasets/index.d.ts +43 -0
  43. package/dist/storage/domains/datasets/index.d.ts.map +1 -0
  44. package/dist/storage/domains/experiments/index.d.ts +31 -0
  45. package/dist/storage/domains/experiments/index.d.ts.map +1 -0
  46. package/dist/storage/domains/favorites/index.d.ts +17 -0
  47. package/dist/storage/domains/favorites/index.d.ts.map +1 -0
  48. package/dist/storage/domains/mcp-clients/index.d.ts.map +1 -1
  49. package/dist/storage/domains/mcp-servers/index.d.ts +26 -0
  50. package/dist/storage/domains/mcp-servers/index.d.ts.map +1 -0
  51. package/dist/storage/domains/memory/index.d.ts +7 -3
  52. package/dist/storage/domains/memory/index.d.ts.map +1 -1
  53. package/dist/storage/domains/observability/index.d.ts +2 -1
  54. package/dist/storage/domains/observability/index.d.ts.map +1 -1
  55. package/dist/storage/domains/prompt-blocks/index.d.ts.map +1 -1
  56. package/dist/storage/domains/schedules/index.d.ts +19 -0
  57. package/dist/storage/domains/schedules/index.d.ts.map +1 -0
  58. package/dist/storage/domains/scorer-definitions/index.d.ts.map +1 -1
  59. package/dist/storage/domains/skills/index.d.ts +26 -0
  60. package/dist/storage/domains/skills/index.d.ts.map +1 -0
  61. package/dist/storage/domains/workflows/index.d.ts +1 -0
  62. package/dist/storage/domains/workflows/index.d.ts.map +1 -1
  63. package/dist/storage/domains/workspaces/index.d.ts +26 -0
  64. package/dist/storage/domains/workspaces/index.d.ts.map +1 -0
  65. package/dist/storage/index.d.ts +38 -1
  66. package/dist/storage/index.d.ts.map +1 -1
  67. package/dist/vector/index.d.ts +14 -1
  68. package/dist/vector/index.d.ts.map +1 -1
  69. package/package.json +12 -12
  70. package/dist/docs/references/docs-agents-agent-memory.md +0 -212
  71. package/dist/docs/references/docs-agents-network-approval.md +0 -275
  72. package/dist/docs/references/docs-observability-overview.md +0 -70
  73. package/dist/docs/references/docs-observability-tracing-exporters-default.md +0 -211
@@ -1,4 +1,4 @@
1
- # libSQL Storage
1
+ # libSQL storage
2
2
 
3
3
  [libSQL](https://docs.turso.tech/libsql) is an open-source, SQLite-compatible database that supports both local and remote deployments. It can be used to store message history, workflow snapshots, traces, and eval scores.
4
4
 
@@ -35,33 +35,33 @@ bun add @mastra/libsql@latest
35
35
  ## Usage
36
36
 
37
37
  ```typescript
38
- import { LibSQLStore } from "@mastra/libsql";
39
- import { Mastra } from "@mastra/core";
38
+ import { LibSQLStore } from '@mastra/libsql'
39
+ import { Mastra } from '@mastra/core'
40
40
 
41
41
  const mastra = new Mastra({
42
42
  storage: new LibSQLStore({
43
43
  id: 'libsql-storage',
44
- url: "file:./storage.db",
44
+ url: 'file:./storage.db',
45
45
  }),
46
- });
46
+ })
47
47
  ```
48
48
 
49
49
  Agent-level file storage:
50
50
 
51
51
  ```typescript
52
- import { Memory } from "@mastra/memory";
53
- import { Agent } from "@mastra/core/agent";
54
- import { LibSQLStore } from "@mastra/libsql";
52
+ import { Memory } from '@mastra/memory'
53
+ import { Agent } from '@mastra/core/agent'
54
+ import { LibSQLStore } from '@mastra/libsql'
55
55
 
56
56
  export const agent = new Agent({
57
- id: "example-agent",
57
+ id: 'example-agent',
58
58
  memory: new Memory({
59
59
  storage: new LibSQLStore({
60
60
  id: 'libsql-storage',
61
- url: "file:./agent.db",
61
+ url: 'file:./agent.db',
62
62
  }),
63
63
  }),
64
- });
64
+ })
65
65
  ```
66
66
 
67
67
  > **Warning:** File storage doesn't work with serverless platforms that have ephemeral file systems. For serverless deployments, use [Turso](https://turso.tech) or a different database engine.
@@ -71,7 +71,7 @@ Production with remote database:
71
71
  ```typescript
72
72
  storage: new LibSQLStore({
73
73
  id: 'libsql-storage',
74
- url: "libsql://your-db-name.aws-ap-northeast-1.turso.io",
74
+ url: 'libsql://your-db-name.aws-ap-northeast-1.turso.io',
75
75
  authToken: process.env.TURSO_AUTH_TOKEN,
76
76
  })
77
77
  ```
@@ -81,7 +81,7 @@ For local development and testing, you can store data in memory:
81
81
  ```typescript
82
82
  storage: new LibSQLStore({
83
83
  id: 'libsql-storage',
84
- url: ":memory:",
84
+ url: ':memory:',
85
85
  })
86
86
  ```
87
87
 
@@ -89,47 +89,47 @@ storage: new LibSQLStore({
89
89
 
90
90
  ## Options
91
91
 
92
- **url:** (`string`): Database URL. Use \`:memory:\` for in-memory database, \`file:filename.db\` for a file database, or a libSQL connection string (e.g., \`libsql://your-database.turso.io\`) for remote storage.
92
+ **url** (`string`): Database URL. Use \`:memory:\` for in-memory database, \`file:filename.db\` for a file database, or a libSQL connection string (e.g., \`libsql://your-database.turso.io\`) for remote storage.
93
93
 
94
- **authToken?:** (`string`): Authentication token for remote libSQL databases.
94
+ **authToken** (`string`): Authentication token for remote libSQL databases.
95
95
 
96
96
  ## Initialization
97
97
 
98
98
  When you pass storage to the Mastra class, `init()` is called automatically to create the [core schema](https://mastra.ai/reference/storage/overview):
99
99
 
100
100
  ```typescript
101
- import { Mastra } from "@mastra/core";
102
- import { LibSQLStore } from "@mastra/libsql";
101
+ import { Mastra } from '@mastra/core'
102
+ import { LibSQLStore } from '@mastra/libsql'
103
103
 
104
104
  const storage = new LibSQLStore({
105
105
  id: 'libsql-storage',
106
- url: "file:./storage.db",
107
- });
106
+ url: 'file:./storage.db',
107
+ })
108
108
 
109
109
  const mastra = new Mastra({
110
110
  storage, // init() called automatically
111
- });
111
+ })
112
112
  ```
113
113
 
114
114
  If using storage directly without Mastra, call `init()` explicitly:
115
115
 
116
116
  ```typescript
117
- import { LibSQLStore } from "@mastra/libsql";
117
+ import { LibSQLStore } from '@mastra/libsql'
118
118
 
119
119
  const storage = new LibSQLStore({
120
120
  id: 'libsql-storage',
121
- url: "file:./storage.db",
122
- });
121
+ url: 'file:./storage.db',
122
+ })
123
123
 
124
- await storage.init();
124
+ await storage.init()
125
125
 
126
126
  // Access domain-specific stores via getStore()
127
- const memoryStore = await storage.getStore('memory');
128
- const thread = await memoryStore?.getThreadById({ threadId: "..." });
127
+ const memoryStore = await storage.getStore('memory')
128
+ const thread = await memoryStore?.getThreadById({ threadId: '...' })
129
129
  ```
130
130
 
131
131
  ## Observability
132
132
 
133
- libSQL supports observability and is ideal for local development. Use the `realtime` [tracing strategy](https://mastra.ai/docs/observability/tracing/exporters/default) for immediate visibility while debugging.
133
+ libSQL supports observability and is ideal for local development. Use the `realtime` [tracing strategy](https://mastra.ai/docs/observability/tracing/exporters/mastra-storage) for immediate visibility while debugging.
134
134
 
135
135
  For production environments with higher trace volumes, consider using [PostgreSQL](https://mastra.ai/reference/storage/postgresql) or [ClickHouse via composite storage](https://mastra.ai/reference/storage/composite).
@@ -1,4 +1,4 @@
1
- # libSQL Vector Store
1
+ # libSQL vector store
2
2
 
3
3
  The libSQL storage implementation provides a SQLite-compatible vector search [libSQL](https://github.com/tursodatabase/libsql), a fork of SQLite with vector extensions, and [Turso](https://turso.tech/) with vector extensions, offering a lightweight and efficient vector database solution. It's part of the `@mastra/libsql` package and offers efficient vector similarity search with metadata filtering.
4
4
 
@@ -69,157 +69,157 @@ const results = await store.query({
69
69
  });
70
70
  ```
71
71
 
72
- ## Constructor Options
72
+ ## Constructor options
73
73
 
74
- **url:** (`string`): libSQL database URL. Use ':memory:' for in-memory database, 'file:dbname.db' for local file, or a libSQL-compatible connection string like 'libsql://your-database.turso.io'.
74
+ **url** (`string`): libSQL database URL. Use ':memory:' for in-memory database, 'file:dbname.db' for local file, or a libSQL-compatible connection string like 'libsql://your-database.turso.io'.
75
75
 
76
- **authToken?:** (`string`): Authentication token for Turso cloud databases
76
+ **authToken** (`string`): Authentication token for Turso cloud databases
77
77
 
78
- **syncUrl?:** (`string`): URL for database replication (Turso specific)
78
+ **syncUrl** (`string`): URL for database replication (Turso specific)
79
79
 
80
- **syncInterval?:** (`number`): Interval in milliseconds for database sync (Turso specific)
80
+ **syncInterval** (`number`): Interval in milliseconds for database sync (Turso specific)
81
81
 
82
82
  ## Methods
83
83
 
84
- ### createIndex()
84
+ ### `createIndex()`
85
85
 
86
86
  Creates a new vector collection. The index name must start with a letter or underscore and can only contain letters, numbers, and underscores. The dimension must be a positive integer.
87
87
 
88
- **indexName:** (`string`): Name of the index to create
88
+ **indexName** (`string`): Name of the index to create
89
89
 
90
- **dimension:** (`number`): Vector dimension size (must match your embedding model)
90
+ **dimension** (`number`): Vector dimension size (must match your embedding model)
91
91
 
92
- **metric?:** (`'cosine' | 'euclidean' | 'dotproduct'`): Distance metric for similarity search. Note: Currently only cosine similarity is supported by libSQL. (Default: `cosine`)
92
+ **metric** (`'cosine' | 'euclidean' | 'dotproduct'`): Distance metric for similarity search. Note: Currently only cosine similarity is supported by libSQL. (Default: `cosine`)
93
93
 
94
- ### upsert()
94
+ ### `upsert()`
95
95
 
96
96
  Adds or updates vectors and their metadata in the index. Uses a transaction to ensure all vectors are inserted atomically - if any insert fails, the entire operation is rolled back.
97
97
 
98
- **indexName:** (`string`): Name of the index to insert into
98
+ **indexName** (`string`): Name of the index to insert into
99
99
 
100
- **vectors:** (`number[][]`): Array of embedding vectors
100
+ **vectors** (`number[][]`): Array of embedding vectors
101
101
 
102
- **metadata?:** (`Record<string, any>[]`): Metadata for each vector
102
+ **metadata** (`Record<string, any>[]`): Metadata for each vector
103
103
 
104
- **ids?:** (`string[]`): Optional vector IDs (auto-generated if not provided)
104
+ **ids** (`string[]`): Optional vector IDs (auto-generated if not provided)
105
105
 
106
- ### query()
106
+ ### `query()`
107
107
 
108
108
  Searches for similar vectors with optional metadata filtering.
109
109
 
110
- **indexName:** (`string`): Name of the index to search in
110
+ **indexName** (`string`): Name of the index to search in
111
111
 
112
- **queryVector:** (`number[]`): Query vector to find similar vectors for
112
+ **queryVector** (`number[]`): Query vector to find similar vectors for
113
113
 
114
- **topK?:** (`number`): Number of results to return (Default: `10`)
114
+ **topK** (`number`): Number of results to return (Default: `10`)
115
115
 
116
- **filter?:** (`Filter`): Metadata filters
116
+ **filter** (`Filter`): Metadata filters
117
117
 
118
- **includeVector?:** (`boolean`): Whether to include vector data in results (Default: `false`)
118
+ **includeVector** (`boolean`): Whether to include vector data in results (Default: `false`)
119
119
 
120
- **minScore?:** (`number`): Minimum similarity score threshold (Default: `0`)
120
+ **minScore** (`number`): Minimum similarity score threshold (Default: `0`)
121
121
 
122
- ### describeIndex()
122
+ ### `describeIndex()`
123
123
 
124
124
  Gets information about an index.
125
125
 
126
- **indexName:** (`string`): Name of the index to describe
126
+ **indexName** (`string`): Name of the index to describe
127
127
 
128
128
  Returns:
129
129
 
130
130
  ```typescript
131
131
  interface IndexStats {
132
- dimension: number;
133
- count: number;
134
- metric: "cosine" | "euclidean" | "dotproduct";
132
+ dimension: number
133
+ count: number
134
+ metric: 'cosine' | 'euclidean' | 'dotproduct'
135
135
  }
136
136
  ```
137
137
 
138
- ### deleteIndex()
138
+ ### `deleteIndex()`
139
139
 
140
140
  Deletes an index and all its data.
141
141
 
142
- **indexName:** (`string`): Name of the index to delete
142
+ **indexName** (`string`): Name of the index to delete
143
143
 
144
- ### listIndexes()
144
+ ### `listIndexes()`
145
145
 
146
146
  Lists all vector indexes in the database.
147
147
 
148
148
  Returns: `Promise<string[]>`
149
149
 
150
- ### truncateIndex()
150
+ ### `truncateIndex()`
151
151
 
152
152
  Removes all vectors from an index while keeping the index structure.
153
153
 
154
- **indexName:** (`string`): Name of the index to truncate
154
+ **indexName** (`string`): Name of the index to truncate
155
155
 
156
- ### updateVector()
156
+ ### `updateVector()`
157
157
 
158
158
  Update a single vector by ID or by metadata filter. Either `id` or `filter` must be provided, but not both.
159
159
 
160
- **indexName:** (`string`): Name of the index containing the vector
160
+ **indexName** (`string`): Name of the index containing the vector
161
161
 
162
- **id?:** (`string`): ID of the vector entry to update (mutually exclusive with filter)
162
+ **id** (`string`): ID of the vector entry to update (mutually exclusive with filter)
163
163
 
164
- **filter?:** (`Record<string, any>`): Metadata filter to identify vector(s) to update (mutually exclusive with id)
164
+ **filter** (`Record<string, any>`): Metadata filter to identify vector(s) to update (mutually exclusive with id)
165
165
 
166
- **update:** (`object`): Update data containing vector and/or metadata
166
+ **update** (`object`): Update data containing vector and/or metadata
167
167
 
168
- **update.vector?:** (`number[]`): New vector data to update
168
+ **update.vector** (`number[]`): New vector data to update
169
169
 
170
- **update.metadata?:** (`Record<string, any>`): New metadata to update
170
+ **update.metadata** (`Record<string, any>`): New metadata to update
171
171
 
172
- ### deleteVector()
172
+ ### `deleteVector()`
173
173
 
174
174
  Deletes a specific vector entry from an index by its ID.
175
175
 
176
- **indexName:** (`string`): Name of the index containing the vector
176
+ **indexName** (`string`): Name of the index containing the vector
177
177
 
178
- **id:** (`string`): ID of the vector entry to delete
178
+ **id** (`string`): ID of the vector entry to delete
179
179
 
180
- ### deleteVectors()
180
+ ### `deleteVectors()`
181
181
 
182
182
  Delete multiple vectors by IDs or by metadata filter. Either `ids` or `filter` must be provided, but not both.
183
183
 
184
- **indexName:** (`string`): Name of the index containing the vectors to delete
184
+ **indexName** (`string`): Name of the index containing the vectors to delete
185
185
 
186
- **ids?:** (`string[]`): Array of vector IDs to delete (mutually exclusive with filter)
186
+ **ids** (`string[]`): Array of vector IDs to delete (mutually exclusive with filter)
187
187
 
188
- **filter?:** (`Record<string, any>`): Metadata filter to identify vectors to delete (mutually exclusive with ids)
188
+ **filter** (`Record<string, any>`): Metadata filter to identify vectors to delete (mutually exclusive with ids)
189
189
 
190
- ## Response Types
190
+ ## Response types
191
191
 
192
192
  Query results are returned in this format:
193
193
 
194
194
  ```typescript
195
195
  interface QueryResult {
196
- id: string;
197
- score: number;
198
- metadata: Record<string, any>;
199
- vector?: number[]; // Only included if includeVector is true
196
+ id: string
197
+ score: number
198
+ metadata: Record<string, any>
199
+ vector?: number[] // Only included if includeVector is true
200
200
  }
201
201
  ```
202
202
 
203
- ## Error Handling
203
+ ## Error handling
204
204
 
205
205
  The store throws specific errors for different failure cases:
206
206
 
207
207
  ```typescript
208
208
  try {
209
209
  await store.query({
210
- indexName: "my-collection",
210
+ indexName: 'my-collection',
211
211
  queryVector: queryVector,
212
- });
212
+ })
213
213
  } catch (error) {
214
214
  // Handle specific error cases
215
- if (error.message.includes("Invalid index name format")) {
215
+ if (error.message.includes('Invalid index name format')) {
216
216
  console.error(
217
- "Index name must start with a letter/underscore and contain only alphanumeric characters",
218
- );
219
- } else if (error.message.includes("Table not found")) {
220
- console.error("The specified index does not exist");
217
+ 'Index name must start with a letter/underscore and contain only alphanumeric characters',
218
+ )
219
+ } else if (error.message.includes('Table not found')) {
220
+ console.error('The specified index does not exist')
221
221
  } else {
222
- console.error("Vector store error:", error.message);
222
+ console.error('Vector store error:', error.message)
223
223
  }
224
224
  }
225
225
  ```
@@ -232,7 +232,7 @@ Common error cases include:
232
232
  - Database connection issues
233
233
  - Transaction failures during upsert
234
234
 
235
- ## Usage Example
235
+ ## Usage example
236
236
 
237
237
  ### Local embeddings with fastembed
238
238
 
@@ -267,25 +267,25 @@ bun add @mastra/fastembed@latest
267
267
  Add the following to your agent:
268
268
 
269
269
  ```typescript
270
- import { Memory } from "@mastra/memory";
271
- import { Agent } from "@mastra/core/agent";
272
- import { LibSQLStore, LibSQLVector } from "@mastra/libsql";
273
- import { fastembed } from "@mastra/fastembed";
270
+ import { Memory } from '@mastra/memory'
271
+ import { Agent } from '@mastra/core/agent'
272
+ import { LibSQLStore, LibSQLVector } from '@mastra/libsql'
273
+ import { fastembed } from '@mastra/fastembed'
274
274
 
275
275
  export const libsqlAgent = new Agent({
276
- id: "libsql-agent",
277
- name: "libSQL Agent",
276
+ id: 'libsql-agent',
277
+ name: 'libSQL Agent',
278
278
  instructions:
279
- "You are an AI agent with the ability to automatically recall memories from previous interactions.",
280
- model: "openai/gpt-5.1",
279
+ 'You are an AI agent with the ability to automatically recall memories from previous interactions.',
280
+ model: 'openai/gpt-5.4',
281
281
  memory: new Memory({
282
282
  storage: new LibSQLStore({
283
283
  id: 'libsql-agent-storage',
284
- url: "file:libsql-agent.db",
284
+ url: 'file:libsql-agent.db',
285
285
  }),
286
286
  vector: new LibSQLVector({
287
287
  id: 'libsql-agent-vector',
288
- url: "file:libsql-agent.db",
288
+ url: 'file:libsql-agent.db',
289
289
  }),
290
290
  embedder: fastembed,
291
291
  options: {
@@ -297,7 +297,7 @@ export const libsqlAgent = new Agent({
297
297
  generateTitle: true, // Explicitly enable automatic title generation
298
298
  },
299
299
  }),
300
- });
300
+ })
301
301
  ```
302
302
 
303
303
  ## Related