@mastra/libsql 0.0.0-testing-cloud-studios-20260114234039 → 0.0.0-thread-replay-alpha-20261102163541

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 (137) hide show
  1. package/LICENSE.md +17 -0
  2. package/README.md +13 -107
  3. package/dist/_types/@internal_core/dist/knowledge-compat/index.d.ts +338 -0
  4. package/dist/_types/@internal_core/dist/memory/index.d.ts +101 -0
  5. package/dist/_types/@internal_core/package.json +1 -0
  6. package/dist/docs/SKILL.md +40 -26
  7. package/dist/docs/{SOURCE_MAP.json → assets/SOURCE_MAP.json} +1 -1
  8. package/dist/docs/references/docs-agents-human-in-the-loop.md +773 -0
  9. package/dist/docs/references/docs-agents-networks.md +186 -0
  10. package/dist/docs/references/docs-deployment-workers.md +404 -0
  11. package/dist/docs/references/docs-memory-memory-processors.md +442 -0
  12. package/dist/docs/references/docs-memory-message-history.md +424 -0
  13. package/dist/docs/references/docs-memory-multi-user-threads.md +210 -0
  14. package/dist/docs/references/docs-memory-overview.md +305 -0
  15. package/dist/docs/references/docs-memory-semantic-recall.md +485 -0
  16. package/dist/docs/references/docs-memory-working-memory.md +450 -0
  17. package/dist/docs/references/docs-signals-overview.md +94 -0
  18. package/dist/docs/references/docs-storage.md +224 -0
  19. package/dist/docs/references/docs-studio-editor.md +369 -0
  20. package/dist/docs/{workflows/01-snapshots.md → references/docs-workflows-snapshots.md} +56 -52
  21. package/dist/docs/references/integrations-channels-github.md +156 -0
  22. package/dist/docs/references/integrations-databases-dynamodb.md +286 -0
  23. package/dist/docs/references/integrations-databases-libsql.md +161 -0
  24. package/dist/docs/references/integrations-vectors-libsql.md +325 -0
  25. package/dist/docs/references/reference-ai-sdk-overview.md +144 -0
  26. package/dist/docs/references/reference-core-getMemory.md +53 -0
  27. package/dist/docs/references/reference-core-listMemory.md +59 -0
  28. package/dist/docs/references/reference-core-mastra-class.md +177 -0
  29. package/dist/docs/references/reference-file-based-agents-memory.md +60 -0
  30. package/dist/docs/references/reference-file-based-agents-storage.md +32 -0
  31. package/dist/docs/references/reference-memory-memory-class.md +237 -0
  32. package/dist/docs/references/reference-rag-retrieval.md +672 -0
  33. package/dist/docs/references/reference-storage-composite.md +433 -0
  34. package/dist/docs/references/reference-storage-retention.md +310 -0
  35. package/dist/index.cjs +16410 -3840
  36. package/dist/index.cjs.map +1 -1
  37. package/dist/index.js +16382 -3831
  38. package/dist/index.js.map +1 -1
  39. package/dist/shared/file-transaction-gate.d.ts +28 -0
  40. package/dist/shared/file-transaction-gate.d.ts.map +1 -0
  41. package/dist/shared/reset-after-busy-client.d.ts +34 -0
  42. package/dist/shared/reset-after-busy-client.d.ts.map +1 -0
  43. package/dist/shared/single-connection-client.d.ts +29 -0
  44. package/dist/shared/single-connection-client.d.ts.map +1 -0
  45. package/dist/storage/db/client.d.ts +33 -0
  46. package/dist/storage/db/client.d.ts.map +1 -0
  47. package/dist/storage/db/index.d.ts +157 -6
  48. package/dist/storage/db/index.d.ts.map +1 -1
  49. package/dist/storage/db/run-fencing.d.ts +41 -0
  50. package/dist/storage/db/run-fencing.d.ts.map +1 -0
  51. package/dist/storage/db/utils.d.ts +38 -2
  52. package/dist/storage/db/utils.d.ts.map +1 -1
  53. package/dist/storage/db/write-lock.d.ts +8 -0
  54. package/dist/storage/db/write-lock.d.ts.map +1 -0
  55. package/dist/storage/domains/agents/index.d.ts +18 -10
  56. package/dist/storage/domains/agents/index.d.ts.map +1 -1
  57. package/dist/storage/domains/background-tasks/index.d.ts +28 -0
  58. package/dist/storage/domains/background-tasks/index.d.ts.map +1 -0
  59. package/dist/storage/domains/blobs/index.d.ts +17 -0
  60. package/dist/storage/domains/blobs/index.d.ts.map +1 -0
  61. package/dist/storage/domains/channels/index.d.ts +20 -0
  62. package/dist/storage/domains/channels/index.d.ts.map +1 -0
  63. package/dist/storage/domains/datasets/index.d.ts +44 -0
  64. package/dist/storage/domains/datasets/index.d.ts.map +1 -0
  65. package/dist/storage/domains/experiments/index.d.ts +55 -0
  66. package/dist/storage/domains/experiments/index.d.ts.map +1 -0
  67. package/dist/storage/domains/favorites/index.d.ts +17 -0
  68. package/dist/storage/domains/favorites/index.d.ts.map +1 -0
  69. package/dist/storage/domains/harness/index.d.ts +17 -0
  70. package/dist/storage/domains/harness/index.d.ts.map +1 -0
  71. package/dist/storage/domains/knowledge/index.d.ts +53 -0
  72. package/dist/storage/domains/knowledge/index.d.ts.map +1 -0
  73. package/dist/storage/domains/knowledge/pages.d.ts +158 -0
  74. package/dist/storage/domains/knowledge/pages.d.ts.map +1 -0
  75. package/dist/storage/domains/mcp-clients/index.d.ts +26 -0
  76. package/dist/storage/domains/mcp-clients/index.d.ts.map +1 -0
  77. package/dist/storage/domains/mcp-servers/index.d.ts +26 -0
  78. package/dist/storage/domains/mcp-servers/index.d.ts.map +1 -0
  79. package/dist/storage/domains/memory/index.d.ts +86 -12
  80. package/dist/storage/domains/memory/index.d.ts.map +1 -1
  81. package/dist/storage/domains/notifications/index.d.ts +36 -0
  82. package/dist/storage/domains/notifications/index.d.ts.map +1 -0
  83. package/dist/storage/domains/observability/index.d.ts +34 -5
  84. package/dist/storage/domains/observability/index.d.ts.map +1 -1
  85. package/dist/storage/domains/prompt-blocks/index.d.ts +25 -0
  86. package/dist/storage/domains/prompt-blocks/index.d.ts.map +1 -0
  87. package/dist/storage/domains/schedules/index.d.ts +27 -0
  88. package/dist/storage/domains/schedules/index.d.ts.map +1 -0
  89. package/dist/storage/domains/scorer-definitions/index.d.ts +26 -0
  90. package/dist/storage/domains/scorer-definitions/index.d.ts.map +1 -0
  91. package/dist/storage/domains/scores/index.d.ts +15 -6
  92. package/dist/storage/domains/scores/index.d.ts.map +1 -1
  93. package/dist/storage/domains/skills/index.d.ts +27 -0
  94. package/dist/storage/domains/skills/index.d.ts.map +1 -0
  95. package/dist/storage/domains/thread-state/index.d.ts +38 -0
  96. package/dist/storage/domains/thread-state/index.d.ts.map +1 -0
  97. package/dist/storage/domains/tool-provider-connections/index.d.ts +14 -0
  98. package/dist/storage/domains/tool-provider-connections/index.d.ts.map +1 -0
  99. package/dist/storage/domains/utils.d.ts +34 -0
  100. package/dist/storage/domains/utils.d.ts.map +1 -0
  101. package/dist/storage/domains/workflow-definitions/index.d.ts +14 -0
  102. package/dist/storage/domains/workflow-definitions/index.d.ts.map +1 -0
  103. package/dist/storage/domains/workflows/index.d.ts +39 -8
  104. package/dist/storage/domains/workflows/index.d.ts.map +1 -1
  105. package/dist/storage/domains/workspaces/index.d.ts +26 -0
  106. package/dist/storage/domains/workspaces/index.d.ts.map +1 -0
  107. package/dist/storage/factory-storage.d.ts +28 -0
  108. package/dist/storage/factory-storage.d.ts.map +1 -0
  109. package/dist/storage/index.d.ts +97 -5
  110. package/dist/storage/index.d.ts.map +1 -1
  111. package/dist/storage/retention.d.ts +26 -0
  112. package/dist/storage/retention.d.ts.map +1 -0
  113. package/dist/vector/filter.d.ts.map +1 -1
  114. package/dist/vector/index.d.ts +31 -2
  115. package/dist/vector/index.d.ts.map +1 -1
  116. package/dist/vector/sql-builder.d.ts.map +1 -1
  117. package/dist/vector/write-lock.d.ts +7 -0
  118. package/dist/vector/write-lock.d.ts.map +1 -0
  119. package/package.json +24 -21
  120. package/CHANGELOG.md +0 -2716
  121. package/dist/docs/README.md +0 -39
  122. package/dist/docs/agents/01-agent-memory.md +0 -160
  123. package/dist/docs/agents/02-networks.md +0 -292
  124. package/dist/docs/agents/03-agent-approval.md +0 -317
  125. package/dist/docs/core/01-reference.md +0 -152
  126. package/dist/docs/guides/01-ai-sdk.md +0 -141
  127. package/dist/docs/memory/01-overview.md +0 -76
  128. package/dist/docs/memory/02-storage.md +0 -181
  129. package/dist/docs/memory/03-working-memory.md +0 -386
  130. package/dist/docs/memory/04-semantic-recall.md +0 -235
  131. package/dist/docs/memory/05-memory-processors.md +0 -319
  132. package/dist/docs/memory/06-reference.md +0 -135
  133. package/dist/docs/observability/01-overview.md +0 -64
  134. package/dist/docs/observability/02-default.md +0 -177
  135. package/dist/docs/rag/01-retrieval.md +0 -549
  136. package/dist/docs/storage/01-reference.md +0 -451
  137. package/dist/docs/vectors/01-reference.md +0 -215
package/LICENSE.md CHANGED
@@ -1,3 +1,20 @@
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
+ - `@mastra/core/auth/ee`
6
+ - `@mastra/core/agent-builder/ee`
7
+ - `@mastra/editor/ee`
8
+
9
+ is licensed under the license defined in [`ee/LICENSE`](https://github.com/mastra-ai/mastra/blob/main/ee/LICENSE).
10
+
11
+ - All third-party components incorporated into the Mastra Software are
12
+ licensed under the original license provided by the owner of the
13
+ applicable component.
14
+
15
+ - Content outside of the above-mentioned directories or restrictions is
16
+ available under the "Apache License 2.0" as defined below.
17
+
1
18
  # Apache License 2.0
2
19
 
3
20
  Copyright (c) 2025 Kepler Software, Inc.
package/README.md CHANGED
@@ -16,27 +16,30 @@ npm install @mastra/libsql
16
16
  import { LibSQLVector } from '@mastra/libsql';
17
17
 
18
18
  const vectorStore = new LibSQLVector({
19
- url: 'file:./my-db.db'
19
+ url: 'file:./my-db.db',
20
20
  });
21
21
 
22
22
  // Create a new table with vector support
23
23
  await vectorStore.createIndex({
24
24
  indexName: 'my_vectors',
25
- dimension: 1536,
25
+ dimension: 3,
26
26
  metric: 'cosine',
27
27
  });
28
28
 
29
29
  // Add vectors
30
30
  const ids = await vectorStore.upsert({
31
31
  indexName: 'my_vectors',
32
- vectors: [[0.1, 0.2, ...], [0.3, 0.4, ...]],
32
+ vectors: [
33
+ [0.1, 0.2, 0.3],
34
+ [0.3, 0.4, 0.5],
35
+ ],
33
36
  metadata: [{ text: 'doc1' }, { text: 'doc2' }],
34
37
  });
35
38
 
36
39
  // Query vectors
37
40
  const results = await vectorStore.query({
38
41
  indexName: 'my_vectors',
39
- queryVector: [0.1, 0.2, ...],
42
+ queryVector: [0.1, 0.2, 0.3],
40
43
  topK: 10, // topK
41
44
  filter: { text: 'doc1' }, // filter
42
45
  includeVector: false, // includeVector
@@ -44,111 +47,14 @@ const results = await vectorStore.query({
44
47
  });
45
48
  ```
46
49
 
47
- ### Storage
48
-
49
- ```typescript
50
- import { LibSQLStore } from '@mastra/libsql';
51
-
52
- const store = new LibSQLStore({
53
- id: 'libsql-storage',
54
- url: 'file:./my-db.db',
55
- });
56
-
57
- // Create a thread
58
- await store.saveThread({
59
- thread: {
60
- id: 'thread-123',
61
- resourceId: 'resource-456',
62
- title: 'My Thread',
63
- metadata: { key: 'value' },
64
- createdAt: new Date(),
65
- },
66
- });
67
-
68
- // Add messages to thread
69
- await store.saveMessages({
70
- messages: [
71
- {
72
- id: 'msg-789',
73
- threadId: 'thread-123',
74
- role: 'user',
75
- content: { content: 'Hello' },
76
- resourceId: 'resource-456',
77
- createdAt: new Date(),
78
- },
79
- ],
80
- });
81
-
82
- // Query threads and messages
83
- const savedThread = await store.getThreadById({ threadId: 'thread-123' });
84
- const messages = await store.listMessages({ threadId: 'thread-123' });
85
- ```
86
-
87
- ## Configuration
88
-
89
- The LibSQLStore store can be initialized with:
90
-
91
- - Configuration object with url and auth. Auth is only necessary when using a provider like [Turso](https://turso.tech/)
92
-
93
- ## Features
94
-
95
- ### Vector Store Features
96
-
97
- - Vector similarity search with cosine, euclidean, and dot product metrics
98
- - Advanced metadata filtering with MongoDB-like query syntax
99
- - Minimum score threshold for queries
100
- - Automatic UUID generation for vectors
101
- - Table management (create, list, describe, delete, truncate)
102
-
103
- ### Storage Features
104
-
105
- - Thread and message storage with JSON support
106
- - Atomic transactions for data consistency
107
- - Efficient batch operations
108
- - Rich metadata support
109
- - Timestamp tracking
110
- - Cascading deletes
111
-
112
- ## Supported Filter Operators
113
-
114
- The following filter operators are supported for metadata queries:
115
-
116
- - Comparison: `$eq`, `$ne`, `$gt`, `$gte`, `$lt`, `$lte`
117
- - Logical: `$and`, `$or`
118
- - Array: `$in`, `$nin`
119
- - Text: `$regex`, `$like`
120
-
121
- Example filter:
122
-
123
- ```typescript
124
- {
125
- $and: [{ age: { $gt: 25 } }, { tags: { $in: ['tag1', 'tag2'] } }];
126
- }
127
- ```
128
-
129
- ## Vector Store Methods
50
+ ## Documentation
130
51
 
131
- - `createIndex({indexName, dimension, metric?, indexConfig?, defineIndex?})`: Create a new table with vector support
132
- - `upsert({indexName, vectors, metadata?, ids?})`: Add or update vectors
133
- - `query({indexName, queryVector, topK?, filter?, includeVector?, minScore?})`: Search for similar vectors
134
- - `updateVector({ indexName, id?, filter?, update })`: Update a single vector by ID or metadata filter
135
- - `deleteVector({ indexName, id })`: Delete a single vector by ID
136
- - `deleteVectors({ indexName, ids?, filter? })`: Delete multiple vectors by IDs or metadata filter
137
- - `defineIndex({indexName, metric?, indexConfig?})`: Define an index
138
- - `listIndexes()`: List all vector-enabled tables
139
- - `describeIndex(indexName)`: Get table statistics
140
- - `deleteIndex(indexName)`: Delete a table
141
- - `truncateIndex(indexName)`: Remove all data from a table
52
+ - [@mastra/libsql documentation](https://mastra.ai/integrations/vectors/libsql)
142
53
 
143
- ## Storage Methods
54
+ ## Changelog
144
55
 
145
- - `saveThread({ thread })`: Create or update a thread
146
- - `getThreadById({ threadId })`: Get a thread by ID
147
- - `deleteThread({ threadId })`: Delete a thread and its messages
148
- - `saveMessages({ messages })`: Save multiple messages in a transaction
149
- - `listMessages({ threadId, perPage?, page? })`: Get messages for a thread with pagination
150
- - `deleteMessages(messageIds)`: Delete specific messages
56
+ See the [package changelog](https://github.com/mastra-ai/mastra/blob/main/stores/libsql/CHANGELOG.md) for version history and release notes.
151
57
 
152
- ## Related Links
58
+ ## Support
153
59
 
154
- - [LibSQL Documentation](https://docs.turso.tech/sdk/introductionh)
60
+ We have an [open community Discord](https://discord.gg/mastra-ai). Come and say hello and let us know if you have any questions or need any help getting things running.
@@ -0,0 +1,338 @@
1
+ export declare const KNOWLEDGE_STORAGE_CONTRACT_VERSION: 4;
2
+ export declare const KNOWLEDGE_STORAGE_SCHEMA_VERSION: 4;
3
+ export declare const TABLE_KNOWLEDGE_NODE_SCOPES = "mastra_knowledge_node_scopes";
4
+ export declare const TABLE_KNOWLEDGE_RECORD_SCOPES = "mastra_knowledge_record_scopes";
5
+ export declare const TABLE_KNOWLEDGE_SCOPE_GRANTS = "mastra_knowledge_scope_grants";
6
+ export declare const TABLE_KNOWLEDGE_ACCESS_STATE = "mastra_knowledge_access_state";
7
+ export declare const TABLE_KNOWLEDGE_SCOPE_ADDRESSES = "mastra_knowledge_scope_addresses";
8
+ export declare const TABLE_KNOWLEDGE_NODE_ADDRESSES = "mastra_knowledge_node_addresses";
9
+ export declare const TABLE_KNOWLEDGE_IMPORT_STATE = "mastra_knowledge_import_state";
10
+ export declare const TABLE_KNOWLEDGE_IMPORT_RUNS = "mastra_knowledge_import_runs";
11
+ export declare const TABLE_KNOWLEDGE_PROPOSALS = "mastra_knowledge_proposals";
12
+ export declare const KNOWLEDGE_TABLE_NAMES: readonly ["mastra_knowledge_nodes", "mastra_knowledge_records", "mastra_knowledge_mentions", "mastra_knowledge_activity", "mastra_knowledge_semantic_outbox", "mastra_knowledge_node_scopes", "mastra_knowledge_record_scopes", "mastra_knowledge_scope_grants", "mastra_knowledge_access_state", "mastra_knowledge_scope_addresses", "mastra_knowledge_node_addresses", "mastra_knowledge_import_state", "mastra_knowledge_import_runs", "mastra_knowledge_proposals"];
13
+ /** Knowledge v1 tables with no v2 equivalent; an explicit schema reset drops them. */
14
+ export declare const RETIRED_KNOWLEDGE_TABLE_NAMES: readonly ['mastra_knowledge_cursors'];
15
+ export declare const KNOWLEDGE_PAGES_CORE_FEATURE = "knowledge-pages";
16
+ export declare const KNOWLEDGE_PAGES_SCHEMA_VERSION: 4;
17
+ export declare const TABLE_KNOWLEDGE_PAGES = "mastra_knowledge_pages";
18
+ export declare const TABLE_KNOWLEDGE_NOTES = "mastra_knowledge_notes";
19
+ export declare const TABLE_KNOWLEDGE_NOTE_STAMPS = "mastra_knowledge_note_stamps";
20
+ /** Same name as the schema-2 table; schema 4 re-keys it to note → page. */
21
+ export declare const TABLE_KNOWLEDGE_PAGE_MENTIONS = "mastra_knowledge_mentions";
22
+ export declare const TABLE_KNOWLEDGE_PINS = "mastra_knowledge_pins";
23
+ /** Same name as schema 2; schema 4 re-keys it to scope/page/note. */
24
+ export declare const TABLE_KNOWLEDGE_PAGE_ACTIVITY = "mastra_knowledge_activity";
25
+ /** Holds `{ id: 'knowledge', schemaVersion: 4 }`, written when the schema-4 tables are created. */
26
+ export declare const TABLE_KNOWLEDGE_PAGES_STATE = "mastra_knowledge_access_state";
27
+ export declare const KNOWLEDGE_PAGES_TABLE_NAMES: readonly ["mastra_knowledge_pages", "mastra_knowledge_notes", "mastra_knowledge_note_stamps", "mastra_knowledge_mentions", "mastra_knowledge_pins", "mastra_knowledge_activity", "mastra_knowledge_access_state"];
28
+ /** Every Knowledge table any schema version created. Reset drops these and nothing else. */
29
+ export declare const KNOWLEDGE_RESETTABLE_TABLE_NAMES: readonly string[];
30
+ /** Schema-1/2 tables whose presence means the store needs a reset before schema 4 can run. */
31
+ export declare const LEGACY_KNOWLEDGE_TABLE_NAMES: ReadonlySet<string>;
32
+ /** Pages and scope pages. `scopeId` equals `id` on scope pages; `address`/`declaration` only on scope pages. */
33
+ export declare const KNOWLEDGE_PAGES_SCHEMA: {
34
+ readonly id: {
35
+ readonly type: 'text';
36
+ readonly nullable: false;
37
+ readonly primaryKey: true;
38
+ };
39
+ readonly scopeId: {
40
+ readonly type: 'text';
41
+ readonly nullable: false;
42
+ };
43
+ readonly parentId: {
44
+ readonly type: 'text';
45
+ readonly nullable: true;
46
+ };
47
+ readonly isScope: {
48
+ readonly type: 'boolean';
49
+ readonly nullable: false;
50
+ };
51
+ readonly address: {
52
+ readonly type: 'text';
53
+ readonly nullable: true;
54
+ };
55
+ readonly declaration: {
56
+ readonly type: 'text';
57
+ readonly nullable: true;
58
+ };
59
+ readonly key: {
60
+ readonly type: 'text';
61
+ readonly nullable: true;
62
+ };
63
+ readonly position: {
64
+ readonly type: 'text';
65
+ readonly nullable: false;
66
+ };
67
+ readonly name: {
68
+ readonly type: 'text';
69
+ readonly nullable: false;
70
+ };
71
+ readonly canonicalName: {
72
+ readonly type: 'text';
73
+ readonly nullable: false;
74
+ };
75
+ readonly description: {
76
+ readonly type: 'text';
77
+ readonly nullable: true;
78
+ };
79
+ readonly body: {
80
+ readonly type: 'text';
81
+ readonly nullable: true;
82
+ };
83
+ readonly version: {
84
+ readonly type: 'integer';
85
+ readonly nullable: false;
86
+ };
87
+ readonly mergedInto: {
88
+ readonly type: 'text';
89
+ readonly nullable: true;
90
+ };
91
+ readonly createdBy: {
92
+ readonly type: 'jsonb';
93
+ readonly nullable: false;
94
+ };
95
+ readonly updatedBy: {
96
+ readonly type: 'jsonb';
97
+ readonly nullable: false;
98
+ };
99
+ readonly createdAt: {
100
+ readonly type: 'timestamp';
101
+ readonly nullable: false;
102
+ };
103
+ readonly updatedAt: {
104
+ readonly type: 'timestamp';
105
+ readonly nullable: false;
106
+ };
107
+ readonly deletedAt: {
108
+ readonly type: 'timestamp';
109
+ readonly nullable: true;
110
+ };
111
+ readonly deletedBy: {
112
+ readonly type: 'text';
113
+ readonly nullable: true;
114
+ };
115
+ };
116
+ export declare const KNOWLEDGE_NOTES_SCHEMA: {
117
+ readonly id: {
118
+ readonly type: 'text';
119
+ readonly nullable: false;
120
+ readonly primaryKey: true;
121
+ };
122
+ readonly pageId: {
123
+ readonly type: 'text';
124
+ readonly nullable: false;
125
+ readonly references: {
126
+ readonly table: "mastra_knowledge_pages";
127
+ readonly column: 'id';
128
+ };
129
+ };
130
+ readonly text: {
131
+ readonly type: 'text';
132
+ readonly nullable: false;
133
+ };
134
+ readonly when: {
135
+ readonly type: 'timestamp';
136
+ readonly nullable: true;
137
+ };
138
+ readonly provenance: {
139
+ readonly type: 'jsonb';
140
+ readonly nullable: false;
141
+ };
142
+ readonly version: {
143
+ readonly type: 'integer';
144
+ readonly nullable: false;
145
+ };
146
+ readonly createdAt: {
147
+ readonly type: 'timestamp';
148
+ readonly nullable: false;
149
+ };
150
+ readonly updatedAt: {
151
+ readonly type: 'timestamp';
152
+ readonly nullable: false;
153
+ };
154
+ readonly deletedAt: {
155
+ readonly type: 'timestamp';
156
+ readonly nullable: true;
157
+ };
158
+ readonly deletedBy: {
159
+ readonly type: 'text';
160
+ readonly nullable: true;
161
+ };
162
+ };
163
+ /** One row per (note, stamp scope). Primary key is the pair. */
164
+ export declare const KNOWLEDGE_NOTE_STAMPS_SCHEMA: {
165
+ readonly noteId: {
166
+ readonly type: 'text';
167
+ readonly nullable: false;
168
+ readonly references: {
169
+ readonly table: "mastra_knowledge_notes";
170
+ readonly column: 'id';
171
+ };
172
+ };
173
+ readonly scopeId: {
174
+ readonly type: 'text';
175
+ readonly nullable: false;
176
+ readonly references: {
177
+ readonly table: "mastra_knowledge_pages";
178
+ readonly column: 'id';
179
+ };
180
+ };
181
+ };
182
+ /** One row per (note, mentioned page). Primary key is the pair. */
183
+ export declare const KNOWLEDGE_PAGE_MENTIONS_SCHEMA: {
184
+ readonly noteId: {
185
+ readonly type: 'text';
186
+ readonly nullable: false;
187
+ readonly references: {
188
+ readonly table: "mastra_knowledge_notes";
189
+ readonly column: 'id';
190
+ };
191
+ };
192
+ readonly pageId: {
193
+ readonly type: 'text';
194
+ readonly nullable: false;
195
+ readonly references: {
196
+ readonly table: "mastra_knowledge_pages";
197
+ readonly column: 'id';
198
+ };
199
+ };
200
+ };
201
+ /** `audience` is a JSON array of scope addresses (PG may store it as `text[]`, Mongo as an array). */
202
+ export declare const KNOWLEDGE_PINS_SCHEMA: {
203
+ readonly id: {
204
+ readonly type: 'text';
205
+ readonly nullable: false;
206
+ readonly primaryKey: true;
207
+ };
208
+ readonly pageId: {
209
+ readonly type: 'text';
210
+ readonly nullable: false;
211
+ readonly references: {
212
+ readonly table: "mastra_knowledge_pages";
213
+ readonly column: 'id';
214
+ };
215
+ };
216
+ readonly audience: {
217
+ readonly type: 'jsonb';
218
+ readonly nullable: false;
219
+ };
220
+ readonly createdBy: {
221
+ readonly type: 'text';
222
+ readonly nullable: false;
223
+ };
224
+ readonly createdAt: {
225
+ readonly type: 'timestamp';
226
+ readonly nullable: false;
227
+ };
228
+ readonly updatedAt: {
229
+ readonly type: 'timestamp';
230
+ readonly nullable: false;
231
+ };
232
+ };
233
+ export declare const KNOWLEDGE_PAGE_ACTIVITY_SCHEMA: {
234
+ readonly id: {
235
+ readonly type: 'text';
236
+ readonly nullable: false;
237
+ readonly primaryKey: true;
238
+ };
239
+ readonly action: {
240
+ readonly type: 'text';
241
+ readonly nullable: false;
242
+ };
243
+ readonly scopeId: {
244
+ readonly type: 'text';
245
+ readonly nullable: false;
246
+ };
247
+ readonly pageId: {
248
+ readonly type: 'text';
249
+ readonly nullable: false;
250
+ };
251
+ readonly noteId: {
252
+ readonly type: 'text';
253
+ readonly nullable: true;
254
+ };
255
+ readonly provenance: {
256
+ readonly type: 'jsonb';
257
+ readonly nullable: false;
258
+ };
259
+ readonly createdAt: {
260
+ readonly type: 'timestamp';
261
+ readonly nullable: false;
262
+ };
263
+ };
264
+ export declare const KNOWLEDGE_PAGES_STATE_SCHEMA: {
265
+ readonly id: {
266
+ readonly type: 'text';
267
+ readonly nullable: false;
268
+ readonly primaryKey: true;
269
+ };
270
+ readonly schemaVersion: {
271
+ readonly type: 'integer';
272
+ readonly nullable: false;
273
+ };
274
+ };
275
+ export type KnowledgePagesSchemaInspection = {
276
+ status: 'compatible';
277
+ schemaVersion: typeof KNOWLEDGE_PAGES_SCHEMA_VERSION;
278
+ } | {
279
+ status: 'uninitialized';
280
+ schemaVersion: null;
281
+ } | {
282
+ status: 'incompatible-reset-required';
283
+ schemaVersion: number | null;
284
+ reason: string;
285
+ };
286
+ /**
287
+ * Classifies what an adapter found before creating schema-4 tables. `tableNames` is every
288
+ * `mastra_knowledge_*` table present; `schemaVersion` is the state row's version, if any.
289
+ */
290
+ export declare function inspectKnowledgePagesSchema(snapshot: {
291
+ tableNames: readonly string[];
292
+ schemaVersion?: number;
293
+ }): KnowledgePagesSchemaInspection;
294
+ /**
295
+ * The old Knowledge tables an adapter drops on init, rows included: Knowledge before schema 4 was an
296
+ * experimental store with no migration. Every schema-1/2-only table present is dropped. The table
297
+ * names schema 4 reuses (mentions, activity, the state table) are dropped too, but only when an old
298
+ * table is present and no schema-4 state row exists, so they are old-shaped. Schema-4-only tables
299
+ * are never listed. On a schema-4 store this lists only tables an older process recreated during a
300
+ * rolling deploy. Drop order is safe for adapters that enforce references.
301
+ */
302
+ export declare function legacyKnowledgeTablesToDrop(snapshot: {
303
+ tableNames: readonly string[];
304
+ schemaVersion?: number;
305
+ }): string[];
306
+ /** Message for the error an adapter throws on `incompatible-reset-required`. */
307
+ export declare function knowledgePagesResetMessage(reason: string): string;
308
+ /**
309
+ * The page-store runtime pieces adapters take from `@mastra/core/storage`. They are loaded through
310
+ * `createKnowledgePagesCoreLoader` instead of static imports so adapters keep loading on cores
311
+ * older than the `knowledge-pages` feature without raising their `@mastra/core` peer floor.
312
+ */
313
+ export interface KnowledgePagesCore {
314
+ assertKnowledgePageDescriptionWithinBound(description: string | undefined): void;
315
+ assertKnowledgeNoteTextWithinBound(text: string): void;
316
+ canonicalKnowledgeName(name: string): string;
317
+ knowledgePositionBetween(before?: string, after?: string): string;
318
+ MAX_KNOWLEDGE_MOVE_PAGES: number;
319
+ MAX_KNOWLEDGE_PAGE_DEPTH: number;
320
+ MAX_KNOWLEDGE_PAGE_LIST_LIMIT: number;
321
+ KnowledgeMoveTooLargeError: new (pageId: string, pages: number) => Error;
322
+ KnowledgePageDepthError: new (pageId: string) => Error;
323
+ KnowledgePageHasChildrenError: new (pageId: string) => Error;
324
+ KnowledgePageKeyConflictError: new (key: string, parentId: string) => Error;
325
+ }
326
+ /** Loads core's page-store runtime once, after checking core advertises `knowledge-pages`. */
327
+ export declare function createKnowledgePagesCoreLoader(features: ReadonlySet<string>, loadStorageModule: () => Promise<unknown>): () => Promise<KnowledgePagesCore>;
328
+ /**
329
+ * Keyword-search words: the query split on whitespace, lowercased, deduplicated. Every word must
330
+ * appear (as a case-insensitive substring) in a hit; an empty list means the search returns nothing.
331
+ */
332
+ export declare function knowledgeSearchWords(query: string): string[];
333
+ /**
334
+ * Why `key` can't be a Knowledge page key, or undefined when it can. Keys are one path segment:
335
+ * non-empty, with no `/` (path separator), `#` (scope/path separator) or `%` (escape character).
336
+ */
337
+ export declare function knowledgePageKeyProblem(key: string): string | undefined;
338
+ //# sourceMappingURL=index.d.ts.map
@@ -0,0 +1,101 @@
1
+ /** Merge working memory patches: null deletes keys, arrays replace. */
2
+ export declare function deepMergeWorkingMemory(existing: Record<string, unknown> | null | undefined, update: Record<string, unknown> | null | undefined): Record<string, unknown>;
3
+ /**
4
+ * Shared rules for observational memory lifecycle writes. Every storage adapter applies
5
+ * these inside its own atomic section (lock, transaction, or conditional update), so the
6
+ * decisions are identical across adapters.
7
+ */
8
+ /**
9
+ * Observational memory columns that lifecycle writes depend on. Storage adapters merge these
10
+ * into the table schema they get from `@mastra/core`, so the columns exist even when the
11
+ * installed core predates them.
12
+ */
13
+ export declare const OBSERVATIONAL_MEMORY_LIFECYCLE_COLUMNS: {
14
+ readonly supersededBy: {
15
+ readonly type: 'text';
16
+ readonly nullable: true;
17
+ };
18
+ };
19
+ /** `schema` plus {@link OBSERVATIONAL_MEMORY_LIFECYCLE_COLUMNS}; `undefined` when `schema` is. */
20
+ export declare function withObservationalMemoryLifecycleColumns<T extends object>(schema: T | undefined): (T & typeof OBSERVATIONAL_MEMORY_LIFECYCLE_COLUMNS) | undefined;
21
+ /**
22
+ * Result of `commitActiveObservations`.
23
+ */
24
+ export interface UpdateActiveObservationsResult {
25
+ /** Whether the observations were written. */
26
+ applied: boolean;
27
+ /**
28
+ * Why nothing was written: `retired` — the target record was superseded by a newer
29
+ * generation; `conflict` — `expectedActiveObservations` no longer matches the stored text.
30
+ */
31
+ reason?: 'retired' | 'conflict';
32
+ }
33
+ /**
34
+ * Result of `appendBufferedObservations`.
35
+ *
36
+ * The append targets the head generation: when `input.id` was superseded, the chunk is
37
+ * appended to the current head instead. The append is skipped (`persisted: false`) when the
38
+ * head already holds a chunk with the same `cycleId`, or when the chunk is wholly covered by
39
+ * the head's cursor. Chunks carry `lastObservedAt = max message time + 1ms`, so a chunk is
40
+ * wholly covered iff `head.lastObservedAt >= chunk.lastObservedAt - 1ms`.
41
+ */
42
+ export interface UpdateBufferedObservationsResult {
43
+ /** Whether the chunk was stored. */
44
+ persisted: boolean;
45
+ /** The record the chunk was written to (or would have been written to). */
46
+ recordId: string;
47
+ }
48
+ /** The fields of an observational memory record that decide head order. */
49
+ export interface ObservationalMemoryHeadOrderFields {
50
+ generationCount: number;
51
+ createdAt: Date | string;
52
+ id: string;
53
+ }
54
+ /**
55
+ * Canonical head order: `generationCount DESC, createdAt ASC, id ASC`.
56
+ * Returns a negative number when `a` sorts before `b` (i.e. `a` is the better head candidate).
57
+ */
58
+ export declare function compareObservationalMemoryHeadOrder(a: ObservationalMemoryHeadOrderFields, b: ObservationalMemoryHeadOrderFields): number;
59
+ /**
60
+ * A buffered chunk stores `lastObservedAt = max message time + 1ms`. It is wholly covered
61
+ * (every message it observed is already at or before the cursor) iff
62
+ * `cursor >= chunk.lastObservedAt - 1ms`.
63
+ */
64
+ export declare function isBufferedChunkCoveredByCursor(chunkLastObservedAt: Date | string, cursor: Date | string | null | undefined): boolean;
65
+ /** The later of two cursors; `undefined` only when both are absent. */
66
+ export declare function maxObservationCursor(a: Date | string | null | undefined, b: Date | string | null | undefined): Date | undefined;
67
+ export interface ReflectionTextPlan {
68
+ /** `equal`: stored text equals the snapshot. `append`: observations were appended after the snapshot. */
69
+ mode: 'equal' | 'append';
70
+ observations: string;
71
+ tokenCount: number;
72
+ }
73
+ /**
74
+ * Decide the new generation's text when a reflection built from `snapshot` commits against
75
+ * the stored record.
76
+ *
77
+ * - Stored text equals the snapshot: the reflection replaces it.
78
+ * - Stored text extends the snapshot (activation only appends): the appended tail is kept
79
+ * after the reflection, and its tokens are added.
80
+ * - Anything else (a non-append rewrite): `null` — the reflection must not be applied.
81
+ */
82
+ export declare function planReflectionGenerationText(input: {
83
+ storedObservations: string;
84
+ storedObservationTokenCount: number;
85
+ snapshotObservations: string;
86
+ snapshotObservationTokenCount: number;
87
+ reflection: string;
88
+ tokenCount: number;
89
+ }): ReflectionTextPlan | null;
90
+ /**
91
+ * Backs `updateActiveObservations` in adapters that implement `commitActiveObservations`.
92
+ * Callers of `updateActiveObservations` (which resolves `void`) can't see a commit result, so a
93
+ * write that was not applied throws instead of resolving as if it had committed.
94
+ */
95
+ export declare function assertActiveObservationsApplied(result: UpdateActiveObservationsResult, id: string): void;
96
+ /**
97
+ * Whether the stored text can still accept a reflection built from `snapshot`
98
+ * (equal, or only appended to since).
99
+ */
100
+ export declare function isAppendOnlySince(storedObservations: string, snapshotObservations: string): boolean;
101
+ //# sourceMappingURL=index.d.ts.map
@@ -0,0 +1 @@
1
+ {"type":"module"}