@mastra/memory 1.0.0-beta.9 → 1.0.0

package/dist/docs/vectors/01-reference.md

@@ -0,0 +1,942 @@
+# Vectors API Reference
+
+> API reference for vectors - 4 entries
+
+
+---
+
+## Reference: libSQL Vector Store
+
+> Documentation for the LibSQLVector class in Mastra, which provides vector search using libSQL with vector extensions.
+
+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.
+
+## Installation
+
+```bash
+npm install @mastra/libsql@beta
+```
+
+## Usage
+
+```typescript
+import { LibSQLVector } from "@mastra/libsql";
+
+// Create a new vector store instance
+const store = new LibSQLVector({
+  id: 'libsql-vector',
+  url: process.env.DATABASE_URL,
+  // Optional: for Turso cloud databases
+  authToken: process.env.DATABASE_AUTH_TOKEN,
+});
+
+// Create an index
+await store.createIndex({
+  indexName: "myCollection",
+  dimension: 1536,
+});
+
+// Add vectors with metadata
+const vectors = [[0.1, 0.2, ...], [0.3, 0.4, ...]];
+const metadata = [
+  { text: "first document", category: "A" },
+  { text: "second document", category: "B" }
+];
+await store.upsert({
+  indexName: "myCollection",
+  vectors,
+  metadata,
+});
+
+// Query similar vectors
+const queryVector = [0.1, 0.2, ...];
+const results = await store.query({
+  indexName: "myCollection",
+  queryVector,
+  topK: 10, // top K results
+  filter: { category: "A" } // optional metadata filter
+});
+```
+
+## Constructor Options
+
+## Methods
+
+### createIndex()
+
+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.
+
+### upsert()
+
+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.
+
+### query()
+
+Searches for similar vectors with optional metadata filtering.
+
+### describeIndex()
+
+Gets information about an index.
+
+Returns:
+
+```typescript
+interface IndexStats {
+  dimension: number;
+  count: number;
+  metric: "cosine" | "euclidean" | "dotproduct";
+}
+```
+
+### deleteIndex()
+
+Deletes an index and all its data.
+
+### listIndexes()
+
+Lists all vector indexes in the database.
+
+Returns: `Promise<string[]>`
+
+### truncateIndex()
+
+Removes all vectors from an index while keeping the index structure.
+
+### updateVector()
+
+Update a single vector by ID or by metadata filter. Either `id` or `filter` must be provided, but not both.
+
+### deleteVector()
+
+Deletes a specific vector entry from an index by its ID.
+
+### deleteVectors()
+
+Delete multiple vectors by IDs or by metadata filter. Either `ids` or `filter` must be provided, but not both.
+
+## Response Types
+
+Query results are returned in this format:
+
+```typescript
+interface QueryResult {
+  id: string;
+  score: number;
+  metadata: Record<string, any>;
+  vector?: number[]; // Only included if includeVector is true
+}
+```
+
+## Error Handling
+
+The store throws specific errors for different failure cases:
+
+```typescript
+try {
+  await store.query({
+    indexName: "my-collection",
+    queryVector: queryVector,
+  });
+} catch (error) {
+  // Handle specific error cases
+  if (error.message.includes("Invalid index name format")) {
+    console.error(
+      "Index name must start with a letter/underscore and contain only alphanumeric characters",
+    );
+  } else if (error.message.includes("Table not found")) {
+    console.error("The specified index does not exist");
+  } else {
+    console.error("Vector store error:", error.message);
+  }
+}
+```
+
+Common error cases include:
+
+- Invalid index name format
+- Invalid vector dimensions
+- Table/index not found
+- Database connection issues
+- Transaction failures during upsert
+
+## Usage Example
+
+### Local embeddings with fastembed
+
+Embeddings are numeric vectors used by memory's `semanticRecall` to retrieve related messages by meaning (not keywords). This setup uses `@mastra/fastembed` to generate vector embeddings.
+
+Install `fastembed` to get started:
+
+```bash 
+npm install @mastra/fastembed@beta
+```
+
+Add the following to your agent:
+
+```typescript title="src/mastra/agents/example-libsql-agent.ts"
+import { Memory } from "@mastra/memory";
+import { Agent } from "@mastra/core/agent";
+import { LibSQLStore, LibSQLVector } from "@mastra/libsql";
+import { fastembed } from "@mastra/fastembed";
+
+export const libsqlAgent = new Agent({
+  id: "libsql-agent",
+  name: "libSQL Agent",
+  instructions:
+    "You are an AI agent with the ability to automatically recall memories from previous interactions.",
+  model: "openai/gpt-5.1",
+  memory: new Memory({
+    storage: new LibSQLStore({
+      id: 'libsql-agent-storage',
+      url: "file:libsql-agent.db",
+    }),
+    vector: new LibSQLVector({
+      id: 'libsql-agent-vector',
+      url: "file:libsql-agent.db",
+    }),
+    embedder: fastembed,
+    options: {
+      lastMessages: 10,
+      semanticRecall: {
+        topK: 3,
+        messageRange: 2,
+      },
+      generateTitle: true, // Explicitly enable automatic title generation
+    },
+  }),
+});
+```
+
+## Related
+
+- [Metadata Filters](../rag/metadata-filters)
+
+---
+
+## Reference: MongoDB Vector Store
+
+> Documentation for the MongoDBVector class in Mastra, which provides vector search using MongoDB Atlas and Atlas Vector Search.
+
+The `MongoDBVector` class provides vector search using [MongoDB Atlas Vector Search](https://www.mongodb.com/docs/atlas/atlas-vector-search/). It enables efficient similarity search and metadata filtering within your MongoDB collections.
+
+## Installation
+
+```bash
+npm install @mastra/mongodb@beta
+```
+
+## Usage Example
+
+```typescript
+import { MongoDBVector } from "@mastra/mongodb";
+
+const store = new MongoDBVector({
+  id: 'mongodb-vector',
+  uri: process.env.MONGODB_URI,
+  dbName: process.env.MONGODB_DATABASE,
+});
+```
+
+### Custom Embedding Field Path
+
+If you need to store embeddings in a nested field structure (e.g., to integrate with existing MongoDB collections), use the `embeddingFieldPath` option:
+
+```typescript
+import { MongoDBVector } from "@mastra/mongodb";
+
+const store = new MongoDBVector({
+  id: 'mongodb-vector',
+  uri: process.env.MONGODB_URI,
+  dbName: process.env.MONGODB_DATABASE,
+  embeddingFieldPath: 'text.contentEmbedding', // Store embeddings at text.contentEmbedding
+});
+```
+
+## Constructor Options
+
+## Methods
+
+### createIndex()
+
+Creates a new vector index (collection) in MongoDB.
+
+### upsert()
+
+Adds or updates vectors and their metadata in the collection.
+
+### query()
+
+Searches for similar vectors with optional metadata filtering.
+
+### describeIndex()
+
+Returns information about the index (collection).
+
+Returns:
+
+```typescript
+interface IndexStats {
+  dimension: number;
+  count: number;
+  metric: "cosine" | "euclidean" | "dotproduct";
+}
+```
+
+### deleteIndex()
+
+Deletes a collection and all its data.
+
+### listIndexes()
+
+Lists all vector collections in the MongoDB database.
+
+Returns: `Promise<string[]>`
+
+### updateVector()
+
+Update a single vector by ID or by metadata filter. Either `id` or `filter` must be provided, but not both.
+
+### deleteVector()
+
+Deletes a specific vector entry from an index by its ID.
+
+### deleteVectors()
+
+Delete multiple vectors by IDs or by metadata filter. Either `ids` or `filter` must be provided, but not both.
+
+### disconnect()
+
+Closes the MongoDB client connection. Should be called when done using the store.
+
+## Response Types
+
+Query results are returned in this format:
+
+```typescript
+interface QueryResult {
+  id: string;
+  score: number;
+  metadata: Record<string, any>;
+  vector?: number[]; // Only included if includeVector is true
+}
+```
+
+## Error Handling
+
+The store throws typed errors that can be caught:
+
+```typescript
+try {
+  await store.query({
+    indexName: "my_collection",
+    queryVector: queryVector,
+  });
+} catch (error) {
+  // Handle specific error cases
+  if (error.message.includes("Invalid collection name")) {
+    console.error(
+      "Collection name must start with a letter or underscore and contain only valid characters.",
+    );
+  } else if (error.message.includes("Collection not found")) {
+    console.error("The specified collection does not exist");
+  } else {
+    console.error("Vector store error:", error.message);
+  }
+}
+```
+
+## Best Practices
+
+- Index metadata fields used in filters for optimal query performance.
+- Use consistent field naming in metadata to avoid unexpected query results.
+- Regularly monitor index and collection statistics to ensure efficient search.
+
+## Usage Example
+
+### Vector embeddings with MongoDB
+
+Embeddings are numeric vectors used by memory's `semanticRecall` to retrieve related messages by meaning (not keywords).
+
+> Note: You must use a deployment hosted on MongoDB Atlas to successfully use the MongoDB Vector database.
+
+This setup uses FastEmbed, a local embedding model, to generate vector embeddings.
+To use this, install `@mastra/fastembed`:
+
+```bash 
+npm install @mastra/fastembed@beta
+```
+
+Add the following to your agent:
+
+```typescript title="src/mastra/agents/example-mongodb-agent.ts"
+import { Memory } from "@mastra/memory";
+import { Agent } from "@mastra/core/agent";
+import { MongoDBStore, MongoDBVector } from "@mastra/mongodb";
+import { fastembed } from "@mastra/fastembed";
+
+export const mongodbAgent = new Agent({
+  id: "mongodb-agent",
+  name: "mongodb-agent",
+  instructions:
+    "You are an AI agent with the ability to automatically recall memories from previous interactions.",
+  model: "openai/gpt-5.1",
+  memory: new Memory({
+    storage: new MongoDBStore({
+      id: 'mongodb-storage',
+      uri: process.env.MONGODB_URI!,
+      dbName: process.env.MONGODB_DB_NAME!,
+    }),
+    vector: new MongoDBVector({
+      id: 'mongodb-vector',
+      uri: process.env.MONGODB_URI!,
+      dbName: process.env.MONGODB_DB_NAME!,
+    }),
+    embedder: fastembed,
+    options: {
+      lastMessages: 10,
+      semanticRecall: {
+        topK: 3,
+        messageRange: 2,
+      },
+      generateTitle: true, // generates descriptive thread titles automatically
+    },
+  }),
+});
+```
+
+## Related
+
+- [Metadata Filters](../rag/metadata-filters)
+
+---
+
+## Reference: PG Vector Store
+
+> Documentation for the PgVector class in Mastra, which provides vector search using PostgreSQL with pgvector extension.
+
+The PgVector class provides vector search using [PostgreSQL](https://www.postgresql.org/) with [pgvector](https://github.com/pgvector/pgvector) extension.
+It provides robust vector similarity search capabilities within your existing PostgreSQL database.
+
+## Constructor Options
+
+## Constructor Examples
+
+### Connection String
+
+```ts
+import { PgVector } from "@mastra/pg";
+
+const vectorStore = new PgVector({
+  id: 'pg-vector',
+  connectionString: "postgresql://user:password@localhost:5432/mydb",
+});
+```
+
+### Host/Port/Database Configuration
+
+```ts
+const vectorStore = new PgVector({
+  id: 'pg-vector',
+  host: "localhost",
+  port: 5432,
+  database: "mydb",
+  user: "postgres",
+  password: "password",
+});
+```
+
+### Advanced Configuration
+
+```ts
+const vectorStore = new PgVector({
+  id: 'pg-vector',
+  connectionString: "postgresql://user:password@localhost:5432/mydb",
+  schemaName: "custom_schema",
+  max: 30,
+  idleTimeoutMillis: 60000,
+  pgPoolOptions: {
+    connectionTimeoutMillis: 5000,
+    allowExitOnIdle: true,
+  },
+});
+```
+
+## Methods
+
+### createIndex()
+
+#### IndexConfig
+
+#### Memory Requirements
+
+HNSW indexes require significant shared memory during construction. For 100K vectors:
+
+- Small dimensions (64d): ~60MB with default settings
+- Medium dimensions (256d): ~180MB with default settings
+- Large dimensions (384d+): ~250MB+ with default settings
+
+Higher M values or efConstruction values will increase memory requirements significantly. Adjust your system's shared memory limits if needed.
+
+### upsert()
+
+### query()
+
+### listIndexes()
+
+Returns an array of index names as strings.
+
+### describeIndex()
+
+Returns:
+
+```typescript
+interface PGIndexStats {
+  dimension: number;
+  count: number;
+  metric: "cosine" | "euclidean" | "dotproduct";
+  type: "flat" | "hnsw" | "ivfflat";
+  config: {
+    m?: number;
+    efConstruction?: number;
+    lists?: number;
+    probes?: number;
+  };
+}
+```
+
+### deleteIndex()
+
+### updateVector()
+
+Update a single vector by ID or by metadata filter. Either `id` or `filter` must be provided, but not both.
+
+Updates an existing vector by ID or filter. At least one of vector or metadata must be provided in the update object.
+
+```typescript
+// Update by ID
+await pgVector.updateVector({
+  indexName: "my_vectors",
+  id: "vector123",
+  update: {
+    vector: [0.1, 0.2, 0.3],
+    metadata: { label: "updated" },
+  },
+});
+
+// Update by filter
+await pgVector.updateVector({
+  indexName: "my_vectors",
+  filter: { category: "product" },
+  update: {
+    metadata: { status: "reviewed" },
+  },
+});
+```
+
+### deleteVector()
+
+Deletes a single vector by ID from the specified index.
+
+```typescript
+await pgVector.deleteVector({ indexName: "my_vectors", id: "vector123" });
+```
+
+### deleteVectors()
+
+Delete multiple vectors by IDs or by metadata filter. Either `ids` or `filter` must be provided, but not both.
+
+### disconnect()
+
+Closes the database connection pool. Should be called when done using the store.
+
+### buildIndex()
+
+Builds or rebuilds an index with specified metric and configuration. Will drop any existing index before creating the new one.
+
+```typescript
+// Define HNSW index
+await pgVector.buildIndex("my_vectors", "cosine", {
+  type: "hnsw",
+  hnsw: {
+    m: 8,
+    efConstruction: 32,
+  },
+});
+
+// Define IVF index
+await pgVector.buildIndex("my_vectors", "cosine", {
+  type: "ivfflat",
+  ivf: {
+    lists: 100,
+  },
+});
+
+// Define flat index
+await pgVector.buildIndex("my_vectors", "cosine", {
+  type: "flat",
+});
+```
+
+## Response Types
+
+Query results are returned in this format:
+
+```typescript
+interface QueryResult {
+  id: string;
+  score: number;
+  metadata: Record<string, any>;
+  vector?: number[]; // Only included if includeVector is true
+}
+```
+
+## Error Handling
+
+The store throws typed errors that can be caught:
+
+```typescript
+try {
+  await store.query({
+    indexName: "index_name",
+    queryVector: queryVector,
+  });
+} catch (error) {
+  if (error instanceof VectorStoreError) {
+    console.log(error.code); // 'connection_failed' | 'invalid_dimension' | etc
+    console.log(error.details); // Additional error context
+  }
+}
+```
+
+## Index Configuration Guide
+
+### Performance Optimization
+
+#### IVFFlat Tuning
+
+- **lists parameter**: Set to `sqrt(n) * 2` where n is the number of vectors
+- More lists = better accuracy but slower build time
+- Fewer lists = faster build but potentially lower accuracy
+
+#### HNSW Tuning
+
+- **m parameter**:
+  - 8-16: Moderate accuracy, lower memory
+  - 16-32: High accuracy, moderate memory
+  - 32-64: Very high accuracy, high memory
+- **efConstruction**:
+  - 32-64: Fast build, good quality
+  - 64-128: Slower build, better quality
+  - 128-256: Slowest build, best quality
+
+### Index Recreation Behavior
+
+The system automatically detects configuration changes and only rebuilds indexes when necessary:
+
+- Same configuration: Index is kept (no recreation)
+- Changed configuration: Index is dropped and rebuilt
+- This prevents the performance issues from unnecessary index recreations
+
+## Best Practices
+
+- Regularly evaluate your index configuration to ensure optimal performance.
+- Adjust parameters like `lists` and `m` based on dataset size and query requirements.
+- **Monitor index performance** using `describeIndex()` to track usage
+- Rebuild indexes periodically to maintain efficiency, especially after significant data changes
+
+## Direct Pool Access
+
+The `PgVector` class exposes its underlying PostgreSQL connection pool as a public field:
+
+```typescript
+pgVector.pool; // instance of pg.Pool
+```
+
+This enables advanced usage such as running direct SQL queries, managing transactions, or monitoring pool state. When using the pool directly:
+
+- You are responsible for releasing clients (`client.release()`) after use.
+- The pool remains accessible after calling `disconnect()`, but new queries will fail.
+- Direct access bypasses any validation or transaction logic provided by PgVector methods.
+
+This design supports advanced use cases but requires careful resource management by the user.
+
+## Usage Example
+
+### Local embeddings with fastembed
+
+Embeddings are numeric vectors used by memory's `semanticRecall` to retrieve related messages by meaning (not keywords). This setup uses `@mastra/fastembed` to generate vector embeddings.
+
+Install `fastembed` to get started:
+
+```bash
+npm install @mastra/fastembed@beta
+```
+
+Add the following to your agent:
+
+```typescript title="src/mastra/agents/example-pg-agent.ts"
+import { Memory } from "@mastra/memory";
+import { Agent } from "@mastra/core/agent";
+import { PostgresStore, PgVector } from "@mastra/pg";
+import { fastembed } from "@mastra/fastembed";
+
+export const pgAgent = new Agent({
+  id: "pg-agent",
+  name: "PG Agent",
+  instructions:
+    "You are an AI agent with the ability to automatically recall memories from previous interactions.",
+  model: "openai/gpt-5.1",
+  memory: new Memory({
+    storage: new PostgresStore({
+      id: 'pg-agent-storage',
+      connectionString: process.env.DATABASE_URL!,
+    }),
+    vector: new PgVector({
+      id: 'pg-agent-vector',
+      connectionString: process.env.DATABASE_URL!,
+    }),
+    embedder: fastembed,
+    options: {
+      lastMessages: 10,
+      semanticRecall: {
+        topK: 3,
+        messageRange: 2,
+      },
+    },
+  }),
+});
+```
+
+## Related
+
+- [Metadata Filters](../rag/metadata-filters)
+
+---
+
+## Reference: Upstash Vector Store
+
+> Documentation for the UpstashVector class in Mastra, which provides vector search using Upstash Vector.
+
+The UpstashVector class provides vector search using [Upstash Vector](https://upstash.com/vector), a serverless vector database service that provides vector similarity search with metadata filtering capabilities and hybrid search support.
+
+## Constructor Options
+
+## Methods
+
+### createIndex()
+
+Note: This method is a no-op for Upstash as indexes are created automatically.
+
+### upsert()
+
+### query()
+
+### listIndexes()
+
+Returns an array of index names (namespaces) as strings.
+
+### describeIndex()
+
+Returns:
+
+```typescript
+interface IndexStats {
+  dimension: number;
+  count: number;
+  metric: "cosine" | "euclidean" | "dotproduct";
+}
+```
+
+### deleteIndex()
+
+### updateVector()
+
+The `update` object can have the following properties:
+
+- `vector` (optional): An array of numbers representing the new dense vector.
+- `sparseVector` (optional): A sparse vector object with `indices` and `values` arrays for hybrid indexes.
+- `metadata` (optional): A record of key-value pairs for metadata.
+
+### deleteVector()
+
+Attempts to delete an item by its ID from the specified index. Logs an error message if the deletion fails.
+
+## Hybrid Vector Search
+
+Upstash Vector supports hybrid search that combines semantic search (dense vectors) with keyword-based search (sparse vectors) for improved relevance and accuracy.
+
+### Basic Hybrid Usage
+
+```typescript
+import { UpstashVector } from "@mastra/upstash";
+
+const vectorStore = new UpstashVector({
+  id: 'upstash-vector',
+  url: process.env.UPSTASH_VECTOR_URL,
+  token: process.env.UPSTASH_VECTOR_TOKEN,
+});
+
+// Upsert vectors with both dense and sparse components
+const denseVectors = [
+  [0.1, 0.2, 0.3],
+  [0.4, 0.5, 0.6],
+];
+const sparseVectors = [
+  { indices: [1, 5, 10], values: [0.8, 0.6, 0.4] },
+  { indices: [2, 6, 11], values: [0.7, 0.5, 0.3] },
+];
+
+await vectorStore.upsert({
+  indexName: "hybrid-index",
+  vectors: denseVectors,
+  sparseVectors: sparseVectors,
+  metadata: [{ title: "Document 1" }, { title: "Document 2" }],
+});
+
+// Query with hybrid search
+const results = await vectorStore.query({
+  indexName: "hybrid-index",
+  queryVector: [0.1, 0.2, 0.3],
+  sparseVector: { indices: [1, 5], values: [0.9, 0.7] },
+  topK: 10,
+});
+```
+
+### Advanced Hybrid Search Options
+
+```typescript
+import { FusionAlgorithm, QueryMode } from "@upstash/vector";
+
+// Query with specific fusion algorithm
+const fusionResults = await vectorStore.query({
+  indexName: "hybrid-index",
+  queryVector: [0.1, 0.2, 0.3],
+  sparseVector: { indices: [1, 5], values: [0.9, 0.7] },
+  fusionAlgorithm: FusionAlgorithm.RRF,
+  topK: 10,
+});
+
+// Dense-only search
+const denseResults = await vectorStore.query({
+  indexName: "hybrid-index",
+  queryVector: [0.1, 0.2, 0.3],
+  queryMode: QueryMode.DENSE,
+  topK: 10,
+});
+
+// Sparse-only search
+const sparseResults = await vectorStore.query({
+  indexName: "hybrid-index",
+  queryVector: [0.1, 0.2, 0.3], // Still required for index structure
+  sparseVector: { indices: [1, 5], values: [0.9, 0.7] },
+  queryMode: QueryMode.SPARSE,
+  topK: 10,
+});
+```
+
+### Updating Hybrid Vectors
+
+```typescript
+// Update both dense and sparse components
+await vectorStore.updateVector({
+  indexName: "hybrid-index",
+  id: "vector-id",
+  update: {
+    vector: [0.2, 0.3, 0.4],
+    sparseVector: { indices: [2, 7, 12], values: [0.9, 0.8, 0.6] },
+    metadata: { title: "Updated Document" },
+  },
+});
+```
+
+## Response Types
+
+Query results are returned in this format:
+
+```typescript
+interface QueryResult {
+  id: string;
+  score: number;
+  metadata: Record<string, any>;
+  vector?: number[]; // Only included if includeVector is true
+}
+```
+
+## Error Handling
+
+The store throws typed errors that can be caught:
+
+```typescript
+try {
+  await store.query({
+    indexName: "index_name",
+    queryVector: queryVector,
+  });
+} catch (error) {
+  if (error instanceof VectorStoreError) {
+    console.log(error.code); // 'connection_failed' | 'invalid_dimension' | etc
+    console.log(error.details); // Additional error context
+  }
+}
+```
+
+## Environment Variables
+
+Required environment variables:
+
+- `UPSTASH_VECTOR_URL`: Your Upstash Vector database URL
+- `UPSTASH_VECTOR_TOKEN`: Your Upstash Vector API token
+
+## Usage Example
+
+### Local embeddings with fastembed
+
+Embeddings are numeric vectors used by memory's `semanticRecall` to retrieve related messages by meaning (not keywords). This setup uses `@mastra/fastembed` to generate vector embeddings.
+
+Install `fastembed` to get started:
+
+```bash
+npm install @mastra/fastembed@beta
+```
+
+Add the following to your agent:
+
+```typescript title="src/mastra/agents/example-upstash-agent.ts"
+import { Memory } from "@mastra/memory";
+import { Agent } from "@mastra/core/agent";
+import { UpstashStore, UpstashVector } from "@mastra/upstash";
+import { fastembed } from "@mastra/fastembed";
+
+export const upstashAgent = new Agent({
+  id: "upstash-agent",
+  name: "Upstash Agent",
+  instructions:
+    "You are an AI agent with the ability to automatically recall memories from previous interactions.",
+  model: "openai/gpt-5.1",
+  memory: new Memory({
+    storage: new UpstashStore({
+      id: 'upstash-agent-storage',
+      url: process.env.UPSTASH_REDIS_REST_URL!,
+      token: process.env.UPSTASH_REDIS_REST_TOKEN!,
+    }),
+    vector: new UpstashVector({
+      id: 'upstash-agent-vector',
+      url: process.env.UPSTASH_VECTOR_REST_URL!,
+      token: process.env.UPSTASH_VECTOR_REST_TOKEN!,
+    }),
+    embedder: fastembed,
+    options: {
+      lastMessages: 10,
+      semanticRecall: {
+        topK: 3,
+        messageRange: 2,
+      },
+    },
+  }),
+});
+```
+
+## Related
+
+- [Metadata Filters](../rag/metadata-filters)