Vector Stores & Memory

Relevant source files

The following files were used as context for generating this wiki page:

• packages/@n8n/workflow-sdk/src/prompts/best-practices/guides/knowledge-base.ts
• packages/@n8n/ai-utilities/src/utils/vector-store/createVectorStoreNode/README.md
• packages/@n8n/ai-utilities/src/utils/vector-store/createVectorStoreNode/createVectorStoreNode.test.ts
• packages/@n8n/ai-workflow-builder.ee/src/prompts/agents/discovery.prompt.ts
• packages/@n8n/workflow-sdk/src/prompts/best-practices/guides/document-processing.ts
• packages/@n8n/workflow-sdk/src/prompts/best-practices/guides/data-extraction.ts

Vector Stores and Memory components provide the persistence layer for AI-driven workflows in n8n. Vector stores index and retrieve high-dimensional document embeddings to support semantic search and Retrieval-Augmented Generation (RAG). Memory components maintain conversation state across multiple turns in chat-based interactions. These modules integrate with LangChain-based nodes to enable intelligent data retrieval and contextual AI reasoning.

Sources: knowledge-base.ts, discovery.prompt.ts, README.md:3-10

Vector Store Architecture

The vector store system uses a factory pattern to create standardized nodes for different providers like Pinecone, Qdrant, and Supabase. The createVectorStoreNode function generates these nodes, ensuring a consistent UI and operational logic across various database backends.

Sources: README.md:12-19, knowledge-base.ts:85-115

Operation Modes

Vector store nodes operate in five distinct modes that define how they interact with document data and AI models:

Mode	Description
Insert	Processes input documents, generates embeddings, and stores them in the database.
Retrieve	Returns a vector store instance directly to an AI node (e.g., a Retriever) for internal use.
Retrieve-as-Tool	Wraps the vector store as a tool that an AI Agent can autonomously call during reasoning.
Load	Performs a similarity search based on a text query and returns ranked documents.
Update	Modifies existing documents in the store using unique identifiers.

Sources: README.md:46-77, createVectorStoreNode.test.ts:82-140

Document Processing Pipeline

When ingestion occurs, documents undergo a multi-step transformation before storage. The pipeline fetches raw content, splits it into manageable chunks, generates embeddings using a specific model, and finally performs an "upsert" operation into the vector database.

The diagram shows the standard flow for document ingestion into a vector store.
Sources: knowledge-base.ts:25-45, document-processing.ts:160-175

Knowledge Base Implementation

Knowledge bases are structured into two separate workflow types to maintain modularity and performance:

1. Ingestion Workflow: Triggered by file changes or schedules to process and index new documents.
2. Query Workflow: Triggered by user input to retrieve context and generate answers via an LLM.

Sources: knowledge-base.ts:8-15

Best Practices for Retrieval

• Consistency: You must use the same embedding model for both indexing and querying (e.g., text-embedding-3-small).
• Chunking: Chunks should be 500-1000 characters (~200 tokens) with a 10-15% overlap to preserve context.
• Limits: Typical optimal retrieval is limited to 3-5 results (Top-K) to avoid overwhelming the LLM context window.
• Similarity Thresholds: Apply scores to filter out irrelevant matches during searches.

Sources: knowledge-base.ts:30-40, knowledge-base.ts:135-155

Memory Management

Memory components allow AI Agents to retain context from previous messages. This is primarily implemented through the Window Buffer Memory node.

Configuration

• Window Size: Usually 3-5 message turns are sufficient to maintain context without exceeding token limits.
• Persistence: Memory ensures that subsequent queries in a session can reference earlier data provided by the user.

The sequence diagram illustrates how memory maintains conversation state between turns.
Sources: knowledge-base.ts:118-131, discovery.prompt.ts:40-48

Technical Implementation Details

createVectorStoreNode Factory

The factory function requires a VectorStoreNodeConstructorArgs object to define specific provider behavior. It handles resource management via releaseVectorStoreClient to prevent connection pool exhaustion, which is critical for database-backed stores like PGVector.

// Example: Minimal Vector Store Node Definition
export class MyVectorStoreNode {
  static description = createVectorStoreNode({
    meta: {
      displayName: 'My Vector Store',
      name: 'myVectorStore',
      operationModes: ['load', 'insert', 'retrieve', 'retrieve-as-tool'],
    },
    getVectorStoreClient: async (context, filter, embeddings, itemIndex) => {
      // Logic to return vector store instance
    },
    populateVectorStore: async (context, embeddings, documents, itemIndex) => {
      // Logic to store document batches
    },
    releaseVectorStoreClient: (vectorStore) => {
      // Cleanup logic (e.g., release DB connection)
    },
  });
}

Sources: README.md:23-44, README.md:120-135

Error Normalization

The vector store module implements a normalization boundary. Provider-specific SDK errors (e.g., Pinecone dimension mismatches) are caught and wrapped in NodeApiError or UserError. This ensures the n8n UI displays readable warnings instead of raw stack traces.

Sources: createVectorStoreNode.test.ts:250-290

Summary

Vector Stores and Memory provide the foundational infrastructure for stateful, context-aware AI applications within n8n. By standardizing document ingestion through specific chunking strategies and embedding model consistency, the system enables reliable semantic search. The modular architecture, supported by the createVectorStoreNode factory, allows for scalable integration of diverse vector database providers while maintaining conversation continuity through dedicated memory managers.