@mastra/memory 1.6.0 → 1.6.1

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 (58) hide show
  1. package/CHANGELOG.md +54 -0
  2. package/dist/{chunk-5UYAHJVJ.cjs → chunk-D6II7EP4.cjs} +660 -531
  3. package/dist/chunk-D6II7EP4.cjs.map +1 -0
  4. package/dist/{chunk-A62BQK35.js → chunk-GBBQIJQF.js} +660 -531
  5. package/dist/chunk-GBBQIJQF.js.map +1 -0
  6. package/dist/docs/SKILL.md +1 -1
  7. package/dist/docs/assets/SOURCE_MAP.json +25 -25
  8. package/dist/docs/references/docs-agents-agent-approval.md +61 -31
  9. package/dist/docs/references/docs-agents-supervisor-agents.md +1 -1
  10. package/dist/docs/references/docs-memory-observational-memory.md +9 -0
  11. package/dist/docs/references/docs-memory-semantic-recall.md +17 -1
  12. package/dist/docs/references/reference-core-getMemory.md +2 -2
  13. package/dist/docs/references/reference-core-listMemory.md +1 -1
  14. package/dist/docs/references/reference-memory-clone-utilities.md +5 -5
  15. package/dist/docs/references/reference-memory-cloneThread.md +17 -21
  16. package/dist/docs/references/reference-memory-createThread.md +10 -10
  17. package/dist/docs/references/reference-memory-getThreadById.md +2 -2
  18. package/dist/docs/references/reference-memory-listThreads.md +5 -5
  19. package/dist/docs/references/reference-memory-memory-class.md +12 -14
  20. package/dist/docs/references/reference-memory-observational-memory.md +102 -94
  21. package/dist/docs/references/reference-processors-token-limiter-processor.md +11 -13
  22. package/dist/docs/references/reference-storage-dynamodb.md +9 -9
  23. package/dist/docs/references/reference-storage-libsql.md +2 -2
  24. package/dist/docs/references/reference-storage-mongodb.md +5 -5
  25. package/dist/docs/references/reference-storage-postgresql.md +25 -25
  26. package/dist/docs/references/reference-storage-upstash.md +3 -3
  27. package/dist/docs/references/reference-vectors-libsql.md +31 -31
  28. package/dist/docs/references/reference-vectors-mongodb.md +32 -32
  29. package/dist/docs/references/reference-vectors-pg.md +60 -44
  30. package/dist/docs/references/reference-vectors-upstash.md +25 -25
  31. package/dist/index.cjs +246 -57
  32. package/dist/index.cjs.map +1 -1
  33. package/dist/index.d.ts +19 -0
  34. package/dist/index.d.ts.map +1 -1
  35. package/dist/index.js +246 -57
  36. package/dist/index.js.map +1 -1
  37. package/dist/{observational-memory-MXI54VC7.cjs → observational-memory-AHVELJX4.cjs} +17 -17
  38. package/dist/{observational-memory-MXI54VC7.cjs.map → observational-memory-AHVELJX4.cjs.map} +1 -1
  39. package/dist/{observational-memory-SR6G4HN5.js → observational-memory-QFQUF5EY.js} +3 -3
  40. package/dist/{observational-memory-SR6G4HN5.js.map → observational-memory-QFQUF5EY.js.map} +1 -1
  41. package/dist/processors/index.cjs +15 -15
  42. package/dist/processors/index.js +1 -1
  43. package/dist/processors/observational-memory/date-utils.d.ts +35 -0
  44. package/dist/processors/observational-memory/date-utils.d.ts.map +1 -0
  45. package/dist/processors/observational-memory/markers.d.ts +94 -0
  46. package/dist/processors/observational-memory/markers.d.ts.map +1 -0
  47. package/dist/processors/observational-memory/observational-memory.d.ts +0 -76
  48. package/dist/processors/observational-memory/observational-memory.d.ts.map +1 -1
  49. package/dist/processors/observational-memory/operation-registry.d.ts +14 -0
  50. package/dist/processors/observational-memory/operation-registry.d.ts.map +1 -0
  51. package/dist/processors/observational-memory/thresholds.d.ts +52 -0
  52. package/dist/processors/observational-memory/thresholds.d.ts.map +1 -0
  53. package/dist/processors/observational-memory/token-counter.d.ts +4 -0
  54. package/dist/processors/observational-memory/token-counter.d.ts.map +1 -1
  55. package/dist/tools/working-memory.d.ts.map +1 -1
  56. package/package.json +7 -7
  57. package/dist/chunk-5UYAHJVJ.cjs.map +0 -1
  58. package/dist/chunk-A62BQK35.js.map +0 -1
@@ -41,35 +41,35 @@ const storage = new PostgresStore({
41
41
 
42
42
  ## Parameters
43
43
 
44
- **id:** (`string`): Unique identifier for this storage instance.
44
+ **id** (`string`): Unique identifier for this storage instance.
45
45
 
46
- **connectionString?:** (`string`): PostgreSQL connection string (e.g., postgresql://user:pass\@host:5432/dbname). Required unless using \`pool\` or individual host-based parameters (\`host\`, \`port\`, \`database\`, \`user\`, \`password\`).
46
+ **connectionString** (`string`): PostgreSQL connection string (e.g., postgresql://user:pass\@host:5432/dbname). Required unless using \`pool\` or individual host-based parameters (\`host\`, \`port\`, \`database\`, \`user\`, \`password\`).
47
47
 
48
- **host?:** (`string`): Database server hostname or IP address. Used with other host-based parameters as an alternative to connectionString.
48
+ **host** (`string`): Database server hostname or IP address. Used with other host-based parameters as an alternative to connectionString.
49
49
 
50
- **port?:** (`number`): Database server port number. Defaults to 5432 if not specified.
50
+ **port** (`number`): Database server port number. Defaults to 5432 if not specified.
51
51
 
52
- **database?:** (`string`): Name of the database to connect to.
52
+ **database** (`string`): Name of the database to connect to.
53
53
 
54
- **user?:** (`string`): Database user for authentication.
54
+ **user** (`string`): Database user for authentication.
55
55
 
56
- **password?:** (`string`): Password for the database user.
56
+ **password** (`string`): Password for the database user.
57
57
 
58
- **pool?:** (`pg.Pool`): Pre-configured pg.Pool instance. Use this to reuse an existing connection pool. When provided, Mastra will not create its own pool and will not close it when \`store.close()\` is called.
58
+ **pool** (`pg.Pool`): Pre-configured pg.Pool instance. Use this to reuse an existing connection pool. When provided, Mastra will not create its own pool and will not close it when \`store.close()\` is called.
59
59
 
60
- **schemaName?:** (`string`): The name of the schema you want the storage to use. Defaults to 'public'.
60
+ **schemaName** (`string`): The name of the schema you want the storage to use. Defaults to 'public'.
61
61
 
62
- **ssl?:** (`boolean | ConnectionOptions`): SSL configuration for the connection; set to true to use default SSL or provide a ConnectionOptions object for custom SSL settings.
62
+ **ssl** (`boolean | ConnectionOptions`): SSL configuration for the connection; set to true to use default SSL or provide a ConnectionOptions object for custom SSL settings.
63
63
 
64
- **max?:** (`number`): Maximum number of connections in the pool. Defaults to 20.
64
+ **max** (`number`): Maximum number of connections in the pool. Defaults to 20.
65
65
 
66
- **idleTimeoutMillis?:** (`number`): How long a connection can sit idle before being closed. Defaults to 30000 (30 seconds).
66
+ **idleTimeoutMillis** (`number`): How long a connection can sit idle before being closed. Defaults to 30000 (30 seconds).
67
67
 
68
- **disableInit?:** (`boolean`): When true, automatic table creation/migrations are disabled. Useful for CI/CD pipelines where migrations are run separately.
68
+ **disableInit** (`boolean`): When true, automatic table creation/migrations are disabled. Useful for CI/CD pipelines where migrations are run separately.
69
69
 
70
- **skipDefaultIndexes?:** (`boolean`): When true, default indexes will not be created during initialization.
70
+ **skipDefaultIndexes** (`boolean`): When true, default indexes will not be created during initialization.
71
71
 
72
- **indexes?:** (`CreateIndexOptions[]`): Custom indexes to create during initialization.
72
+ **indexes** (`CreateIndexOptions[]`): Custom indexes to create during initialization.
73
73
 
74
74
  ## Constructor Examples
75
75
 
@@ -448,25 +448,25 @@ For advanced index types, you can specify additional options:
448
448
 
449
449
  ### Index Options
450
450
 
451
- **name:** (`string`): Unique name for the index
451
+ **name** (`string`): Unique name for the index
452
452
 
453
- **table:** (`string`): Table name (e.g., 'mastra\_threads')
453
+ **table** (`string`): Table name (e.g., 'mastra\_threads')
454
454
 
455
- **columns:** (`string[]`): Array of column names with optional sort order (e.g., \['id', 'createdAt DESC'])
455
+ **columns** (`string[]`): Array of column names with optional sort order (e.g., \['id', 'createdAt DESC'])
456
456
 
457
- **unique?:** (`boolean`): Creates a unique constraint index
457
+ **unique** (`boolean`): Creates a unique constraint index
458
458
 
459
- **concurrent?:** (`boolean`): Creates index without locking table (default: true)
459
+ **concurrent** (`boolean`): Creates index without locking table (default: true)
460
460
 
461
- **where?:** (`string`): Partial index condition (PostgreSQL specific)
461
+ **where** (`string`): Partial index condition (PostgreSQL specific)
462
462
 
463
- **method?:** (`'btree' | 'hash' | 'gin' | 'gist' | 'spgist' | 'brin'`): Index method (default: 'btree')
463
+ **method** (`'btree' | 'hash' | 'gin' | 'gist' | 'spgist' | 'brin'`): Index method (default: 'btree')
464
464
 
465
- **opclass?:** (`string`): Operator class for GIN/GIST indexes
465
+ **opclass** (`string`): Operator class for GIN/GIST indexes
466
466
 
467
- **storage?:** (`Record<string, any>`): Storage parameters (e.g., { fillfactor: 90 })
467
+ **storage** (`Record<string, any>`): Storage parameters (e.g., { fillfactor: 90 })
468
468
 
469
- **tablespace?:** (`string`): Tablespace name for index placement
469
+ **tablespace** (`string`): Tablespace name for index placement
470
470
 
471
471
  ### Schema-Specific Indexes
472
472
 
@@ -46,11 +46,11 @@ const storage = new UpstashStore({
46
46
 
47
47
  ## Parameters
48
48
 
49
- **url:** (`string`): Upstash Redis URL
49
+ **url** (`string`): Upstash Redis URL
50
50
 
51
- **token:** (`string`): Upstash Redis authentication token
51
+ **token** (`string`): Upstash Redis authentication token
52
52
 
53
- **prefix?:** (`string`): Key prefix for all stored items (Default: `mastra:`)
53
+ **prefix** (`string`): Key prefix for all stored items (Default: `mastra:`)
54
54
 
55
55
  ## Additional Notes
56
56
 
@@ -71,13 +71,13 @@ const results = await store.query({
71
71
 
72
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
 
@@ -85,45 +85,45 @@ const results = await store.query({
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
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
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
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
 
@@ -139,7 +139,7 @@ interface IndexStats {
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
144
  ### listIndexes()
145
145
 
@@ -151,41 +151,41 @@ Returns: `Promise<string[]>`
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
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
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
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
190
  ## Response Types
191
191
 
@@ -57,15 +57,15 @@ const store = new MongoDBVector({
57
57
 
58
58
  ## Constructor Options
59
59
 
60
- **id:** (`string`): Unique identifier for this vector store instance
60
+ **id** (`string`): Unique identifier for this vector store instance
61
61
 
62
- **uri:** (`string`): MongoDB connection string
62
+ **uri** (`string`): MongoDB connection string
63
63
 
64
- **dbName:** (`string`): Name of the MongoDB database to use
64
+ **dbName** (`string`): Name of the MongoDB database to use
65
65
 
66
- **options?:** (`MongoClientOptions`): Optional MongoDB client options
66
+ **options** (`MongoClientOptions`): Optional MongoDB client options
67
67
 
68
- **embeddingFieldPath?:** (`string`): Path to the field that stores vector embeddings. Supports nested paths using dot notation (e.g., 'text.contentEmbedding'). (Default: `embedding`)
68
+ **embeddingFieldPath** (`string`): Path to the field that stores vector embeddings. Supports nested paths using dot notation (e.g., 'text.contentEmbedding'). (Default: `embedding`)
69
69
 
70
70
  ## Methods
71
71
 
@@ -73,47 +73,47 @@ const store = new MongoDBVector({
73
73
 
74
74
  Creates a new vector index (collection) in MongoDB.
75
75
 
76
- **indexName:** (`string`): Name of the collection to create
76
+ **indexName** (`string`): Name of the collection to create
77
77
 
78
- **dimension:** (`number`): Vector dimension (must match your embedding model)
78
+ **dimension** (`number`): Vector dimension (must match your embedding model)
79
79
 
80
- **metric?:** (`'cosine' | 'euclidean' | 'dotproduct'`): Distance metric for similarity search (Default: `cosine`)
80
+ **metric** (`'cosine' | 'euclidean' | 'dotproduct'`): Distance metric for similarity search (Default: `cosine`)
81
81
 
82
82
  ### upsert()
83
83
 
84
84
  Adds or updates vectors and their metadata in the collection.
85
85
 
86
- **indexName:** (`string`): Name of the collection to insert into
86
+ **indexName** (`string`): Name of the collection to insert into
87
87
 
88
- **vectors:** (`number[][]`): Array of embedding vectors
88
+ **vectors** (`number[][]`): Array of embedding vectors
89
89
 
90
- **metadata?:** (`Record<string, any>[]`): Metadata for each vector
90
+ **metadata** (`Record<string, any>[]`): Metadata for each vector
91
91
 
92
- **ids?:** (`string[]`): Optional vector IDs (auto-generated if not provided)
92
+ **ids** (`string[]`): Optional vector IDs (auto-generated if not provided)
93
93
 
94
94
  ### query()
95
95
 
96
96
  Searches for similar vectors with optional metadata filtering.
97
97
 
98
- **indexName:** (`string`): Name of the collection to search in
98
+ **indexName** (`string`): Name of the collection to search in
99
99
 
100
- **queryVector:** (`number[]`): Query vector to find similar vectors for
100
+ **queryVector** (`number[]`): Query vector to find similar vectors for
101
101
 
102
- **topK?:** (`number`): Number of results to return (Default: `10`)
102
+ **topK** (`number`): Number of results to return (Default: `10`)
103
103
 
104
- **filter?:** (`Record<string, any>`): Metadata filters (applies to the \`metadata\` field)
104
+ **filter** (`Record<string, any>`): Metadata filters (applies to the \`metadata\` field)
105
105
 
106
- **documentFilter?:** (`Record<string, any>`): Filters on original document fields (not just metadata)
106
+ **documentFilter** (`Record<string, any>`): Filters on original document fields (not just metadata)
107
107
 
108
- **includeVector?:** (`boolean`): Whether to include vector data in results (Default: `false`)
108
+ **includeVector** (`boolean`): Whether to include vector data in results (Default: `false`)
109
109
 
110
- **minScore?:** (`number`): Minimum similarity score threshold (Default: `0`)
110
+ **minScore** (`number`): Minimum similarity score threshold (Default: `0`)
111
111
 
112
112
  ### describeIndex()
113
113
 
114
114
  Returns information about the index (collection).
115
115
 
116
- **indexName:** (`string`): Name of the collection to describe
116
+ **indexName** (`string`): Name of the collection to describe
117
117
 
118
118
  Returns:
119
119
 
@@ -129,7 +129,7 @@ interface IndexStats {
129
129
 
130
130
  Deletes a collection and all its data.
131
131
 
132
- **indexName:** (`string`): Name of the collection to delete
132
+ **indexName** (`string`): Name of the collection to delete
133
133
 
134
134
  ### listIndexes()
135
135
 
@@ -141,35 +141,35 @@ Returns: `Promise<string[]>`
141
141
 
142
142
  Update a single vector by ID or by metadata filter. Either `id` or `filter` must be provided, but not both.
143
143
 
144
- **indexName:** (`string`): Name of the collection containing the vector
144
+ **indexName** (`string`): Name of the collection containing the vector
145
145
 
146
- **id?:** (`string`): ID of the vector entry to update (mutually exclusive with filter)
146
+ **id** (`string`): ID of the vector entry to update (mutually exclusive with filter)
147
147
 
148
- **filter?:** (`Record<string, any>`): Metadata filter to identify vector(s) to update (mutually exclusive with id)
148
+ **filter** (`Record<string, any>`): Metadata filter to identify vector(s) to update (mutually exclusive with id)
149
149
 
150
- **update:** (`object`): Update data containing vector and/or metadata
150
+ **update** (`object`): Update data containing vector and/or metadata
151
151
 
152
- **update.vector?:** (`number[]`): New vector data to update
152
+ **update.vector** (`number[]`): New vector data to update
153
153
 
154
- **update.metadata?:** (`Record<string, any>`): New metadata to update
154
+ **update.metadata** (`Record<string, any>`): New metadata to update
155
155
 
156
156
  ### deleteVector()
157
157
 
158
158
  Deletes a specific vector entry from an index by its ID.
159
159
 
160
- **indexName:** (`string`): Name of the collection containing the vector
160
+ **indexName** (`string`): Name of the collection containing the vector
161
161
 
162
- **id:** (`string`): ID of the vector entry to delete
162
+ **id** (`string`): ID of the vector entry to delete
163
163
 
164
164
  ### deleteVectors()
165
165
 
166
166
  Delete multiple vectors by IDs or by metadata filter. Either `ids` or `filter` must be provided, but not both.
167
167
 
168
- **indexName:** (`string`): Name of the collection containing the vectors to delete
168
+ **indexName** (`string`): Name of the collection containing the vectors to delete
169
169
 
170
- **ids?:** (`string[]`): Array of vector IDs to delete (mutually exclusive with filter)
170
+ **ids** (`string[]`): Array of vector IDs to delete (mutually exclusive with filter)
171
171
 
172
- **filter?:** (`Record<string, any>`): Metadata filter to identify vectors to delete (mutually exclusive with ids)
172
+ **filter** (`Record<string, any>`): Metadata filter to identify vectors to delete (mutually exclusive with ids)
173
173
 
174
174
  ### disconnect()
175
175
 
@@ -4,27 +4,27 @@ The PgVector class provides vector search using [PostgreSQL](https://www.postgre
4
4
 
5
5
  ## Constructor Options
6
6
 
7
- **connectionString?:** (`string`): PostgreSQL connection URL
7
+ **connectionString** (`string`): PostgreSQL connection URL
8
8
 
9
- **host?:** (`string`): PostgreSQL server host
9
+ **host** (`string`): PostgreSQL server host
10
10
 
11
- **port?:** (`number`): PostgreSQL server port
11
+ **port** (`number`): PostgreSQL server port
12
12
 
13
- **database?:** (`string`): PostgreSQL database name
13
+ **database** (`string`): PostgreSQL database name
14
14
 
15
- **user?:** (`string`): PostgreSQL user
15
+ **user** (`string`): PostgreSQL user
16
16
 
17
- **password?:** (`string`): PostgreSQL password
17
+ **password** (`string`): PostgreSQL password
18
18
 
19
- **ssl?:** (`boolean | ConnectionOptions`): Enable SSL or provide custom SSL configuration
19
+ **ssl** (`boolean | ConnectionOptions`): Enable SSL or provide custom SSL configuration
20
20
 
21
- **schemaName?:** (`string`): The name of the schema you want the vector store to use. Will use the default schema if not provided.
21
+ **schemaName** (`string`): The name of the schema you want the vector store to use. Will use the default schema if not provided.
22
22
 
23
- **max?:** (`number`): Maximum number of pool connections (default: 20)
23
+ **max** (`number`): Maximum number of pool connections (default: 20)
24
24
 
25
- **idleTimeoutMillis?:** (`number`): Idle connection timeout in milliseconds (default: 30000)
25
+ **idleTimeoutMillis** (`number`): Idle connection timeout in milliseconds (default: 30000)
26
26
 
27
- **pgPoolOptions?:** (`PoolConfig`): Additional pg pool configuration options
27
+ **pgPoolOptions** (`PoolConfig`): Additional pg pool configuration options
28
28
 
29
29
  ## Constructor Examples
30
30
 
@@ -72,23 +72,35 @@ const vectorStore = new PgVector({
72
72
 
73
73
  ### createIndex()
74
74
 
75
- **indexName:** (`string`): Name of the index to create
75
+ **indexName** (`string`): Name of the index to create
76
76
 
77
- **dimension:** (`number`): Vector dimension (must match your embedding model)
77
+ **dimension** (`number`): Vector dimension (must match your embedding model)
78
78
 
79
- **metric?:** (`'cosine' | 'euclidean' | 'dotproduct'`): Distance metric for similarity search (Default: `cosine`)
79
+ **metric** (`'cosine' | 'euclidean' | 'dotproduct'`): Distance metric for similarity search (Default: `cosine`)
80
80
 
81
- **indexConfig?:** (`IndexConfig`): Index configuration (Default: `{ type: 'ivfflat' }`)
81
+ **indexConfig** (`IndexConfig`): Index configuration (Default: `{ type: 'ivfflat' }`)
82
82
 
83
- **buildIndex?:** (`boolean`): Whether to build the index (Default: `true`)
83
+ **buildIndex** (`boolean`): Whether to build the index (Default: `true`)
84
84
 
85
85
  #### IndexConfig
86
86
 
87
- **type:** (`'flat' | 'hnsw' | 'ivfflat'`): stringflat:flatSequential scan (no index) that performs exhaustive search.ivfflat:ivfflatClusters vectors into lists for approximate search.hnsw:hnswGraph-based index offering fast search times and high recall. (Default: `ivfflat`)
87
+ **type** (`'flat' | 'hnsw' | 'ivfflat'`): Index type (Default: `ivfflat`)
88
88
 
89
- **ivf?:** (`IVFConfig`): objectlists?:numberNumber of lists. If not specified, automatically calculated based on dataset size. (Minimum 100, Maximum 4000)
89
+ **type.flat** (`flat`): Sequential scan (no index) that performs exhaustive search.
90
90
 
91
- **hnsw?:** (`HNSWConfig`): objectm?:numberMaximum number of connections per node (default: 8)efConstruction?:numberBuild-time complexity (default: 32)
91
+ **type.ivfflat** (`ivfflat`): Clusters vectors into lists for approximate search.
92
+
93
+ **type.hnsw** (`hnsw`): Graph-based index offering fast search times and high recall.
94
+
95
+ **ivf** (`IVFConfig`): IVF configuration
96
+
97
+ **ivf.lists** (`number`): Number of lists. If not specified, automatically calculated based on dataset size. (Minimum 100, Maximum 4000)
98
+
99
+ **hnsw** (`HNSWConfig`): HNSW configuration
100
+
101
+ **hnsw\.m** (`number`): Maximum number of connections per node (default: 8)
102
+
103
+ **hnsw\.efConstruction** (`number`): Build-time complexity (default: 32)
92
104
 
93
105
  #### Memory Requirements
94
106
 
@@ -102,29 +114,33 @@ Higher M values or efConstruction values will increase memory requirements signi
102
114
 
103
115
  ### upsert()
104
116
 
105
- **indexName:** (`string`): Name of the index to upsert vectors into
117
+ **indexName** (`string`): Name of the index to upsert vectors into
106
118
 
107
- **vectors:** (`number[][]`): Array of embedding vectors
119
+ **vectors** (`number[][]`): Array of embedding vectors
108
120
 
109
- **metadata?:** (`Record<string, any>[]`): Metadata for each vector
121
+ **metadata** (`Record<string, any>[]`): Metadata for each vector
110
122
 
111
- **ids?:** (`string[]`): Optional vector IDs (auto-generated if not provided)
123
+ **ids** (`string[]`): Optional vector IDs (auto-generated if not provided)
112
124
 
113
125
  ### query()
114
126
 
115
- **indexName:** (`string`): Name of the index to query
127
+ **indexName** (`string`): Name of the index to query
128
+
129
+ **queryVector** (`number[]`): Query vector
130
+
131
+ **topK** (`number`): Number of results to return (Default: `10`)
116
132
 
117
- **queryVector:** (`number[]`): Query vector
133
+ **filter** (`Record<string, any>`): Metadata filters
118
134
 
119
- **topK?:** (`number`): Number of results to return (Default: `10`)
135
+ **includeVector** (`boolean`): Whether to include the vector in the result (Default: `false`)
120
136
 
121
- **filter?:** (`Record<string, any>`): Metadata filters
137
+ **minScore** (`number`): Minimum similarity score threshold (Default: `0`)
122
138
 
123
- **includeVector?:** (`boolean`): Whether to include the vector in the result (Default: `false`)
139
+ **options** (`{ ef?: number; probes?: number }`): Additional options for HNSW and IVF indexes
124
140
 
125
- **minScore?:** (`number`): Minimum similarity score threshold (Default: `0`)
141
+ **options.ef** (`number`): HNSW search parameter
126
142
 
127
- **options?:** (`{ ef?: number; probes?: number }`): objectef?:numberHNSW search parameterprobes?:numberIVF search parameter
143
+ **options.probes** (`number`): IVF search parameter
128
144
 
129
145
  ### listIndexes()
130
146
 
@@ -132,7 +148,7 @@ Returns an array of index names as strings.
132
148
 
133
149
  ### describeIndex()
134
150
 
135
- **indexName:** (`string`): Name of the index to describe
151
+ **indexName** (`string`): Name of the index to describe
136
152
 
137
153
  Returns:
138
154
 
@@ -153,19 +169,19 @@ interface PGIndexStats {
153
169
 
154
170
  ### deleteIndex()
155
171
 
156
- **indexName:** (`string`): Name of the index to delete
172
+ **indexName** (`string`): Name of the index to delete
157
173
 
158
174
  ### updateVector()
159
175
 
160
176
  Update a single vector by ID or by metadata filter. Either `id` or `filter` must be provided, but not both.
161
177
 
162
- **indexName:** (`string`): Name of the index containing the vector
178
+ **indexName** (`string`): Name of the index containing the vector
163
179
 
164
- **id?:** (`string`): ID of the vector to update (mutually exclusive with filter)
180
+ **id** (`string`): ID of the vector to update (mutually exclusive with filter)
165
181
 
166
- **filter?:** (`Record<string, any>`): Metadata filter to identify vector(s) to update (mutually exclusive with id)
182
+ **filter** (`Record<string, any>`): Metadata filter to identify vector(s) to update (mutually exclusive with id)
167
183
 
168
- **update:** (`{ vector?: number[]; metadata?: Record<string, any>; }`): Object containing the vector and/or metadata to update
184
+ **update** (`{ vector?: number[]; metadata?: Record<string, any>; }`): Object containing the vector and/or metadata to update
169
185
 
170
186
  Updates an existing vector by ID or filter. At least one of vector or metadata must be provided in the update object.
171
187
 
@@ -192,9 +208,9 @@ await pgVector.updateVector({
192
208
 
193
209
  ### deleteVector()
194
210
 
195
- **indexName:** (`string`): Name of the index containing the vector
211
+ **indexName** (`string`): Name of the index containing the vector
196
212
 
197
- **id:** (`string`): ID of the vector to delete
213
+ **id** (`string`): ID of the vector to delete
198
214
 
199
215
  Deletes a single vector by ID from the specified index.
200
216
 
@@ -206,11 +222,11 @@ await pgVector.deleteVector({ indexName: 'my_vectors', id: 'vector123' })
206
222
 
207
223
  Delete multiple vectors by IDs or by metadata filter. Either `ids` or `filter` must be provided, but not both.
208
224
 
209
- **indexName:** (`string`): Name of the index containing the vectors to delete
225
+ **indexName** (`string`): Name of the index containing the vectors to delete
210
226
 
211
- **ids?:** (`string[]`): Array of vector IDs to delete (mutually exclusive with filter)
227
+ **ids** (`string[]`): Array of vector IDs to delete (mutually exclusive with filter)
212
228
 
213
- **filter?:** (`Record<string, any>`): Metadata filter to identify vectors to delete (mutually exclusive with ids)
229
+ **filter** (`Record<string, any>`): Metadata filter to identify vectors to delete (mutually exclusive with ids)
214
230
 
215
231
  ### disconnect()
216
232
 
@@ -218,11 +234,11 @@ Closes the database connection pool. Should be called when done using the store.
218
234
 
219
235
  ### buildIndex()
220
236
 
221
- **indexName:** (`string`): Name of the index to define
237
+ **indexName** (`string`): Name of the index to define
222
238
 
223
- **metric?:** (`'cosine' | 'euclidean' | 'dotproduct'`): Distance metric for similarity search (Default: `cosine`)
239
+ **metric** (`'cosine' | 'euclidean' | 'dotproduct'`): Distance metric for similarity search (Default: `cosine`)
224
240
 
225
- **indexConfig:** (`IndexConfig`): Configuration for the index type and parameters
241
+ **indexConfig** (`IndexConfig`): Configuration for the index type and parameters
226
242
 
227
243
  Builds or rebuilds an index with specified metric and configuration. Will drop any existing index before creating the new one.
228
244