Semantic Splitter with Context for n8n with LangChain integration
npm install n8n-nodes-semantic-splitter-with-contextA production-ready n8n node that provides semantic text splitting with intelligent contextual enhancement. This node combines semantic double-pass merging with a Global Summary approach for optimal token efficiency and retrieval performance. Zero external dependencies - uses n8n's built-in LangChain modules for seamless integration.
- Semantic Double-Pass Merging: Uses embeddings to identify semantic boundaries and intelligently merges similar adjacent chunks
- Global Summary Approach: Generates one document summary and uses it to create specific context for each chunk (dramatically reduces API calls)
- Dual Customizable Prompts: Separate user-defined prompts for document summarization and chunk context generation
- Multiple Threshold Methods: Percentile, standard deviation, interquartile, and gradient-based breakpoint detection
- Enhanced Size Constraints: Sentence-boundary-aware splitting and merging with intelligent size management
- Flexible Sentence Splitting: Customizable regex patterns with safety fallbacks
- Memory Leak Protection: Instance and document caching prevent infinite retry loops and memory exhaustion
- Production Ready: Comprehensive error handling, payload validation, and visual feedback integration
1. Document Input: Receives documents from document loaders
2. Global Summary Generation: Creates a single document-level summary (1 API call per document)
3. Semantic Splitting: Splits text using semantic similarity analysis with intelligent double-pass merging
4. Context Generation: For each chunk, generates specific contextual description using the global summary + chunk (1 API call per chunk)
5. Output Format: Returns chunks in the format: [chunk-specific context]\n\n[chunk content]
1. Go to Settings > Community Nodes
2. Select Install
3. Enter n8n-nodes-semantic-splitter-with-context in the search field
4. Select Install
- Node.js (version 18 or above)
- npm
- n8n installed globally or locally
This node uses n8n's built-in LangChain integration. The package declares LangChain as peer dependencies to ensure type compatibility, but at runtime n8n provides the required modules. You typically do not need to install additional LangChain packages yourself when using this node inside n8n.
1. Clone the repository:
``bash`
git clone
cd n8n-nodes-semantic-splitter-with-context
2. Install dependencies:
`bash`
npm install
3. Build the node:
`bash`
npm run build
4. Link the node to n8n:
`bash`
npm link
cd ~/.n8n/custom
npm link n8n-nodes-semantic-splitter-with-context
5. Start n8n:
`bash`
n8n start
1. In n8n, search for "Semantic Splitter with Context" in the nodes panel
2. Drag the node into your workflow
3. Connect required inputs:
- Chat Model: For generating contextual descriptions
- Embeddings: For semantic similarity analysis
4. Configure the context prompt and options as needed
The node uses two separate prompts for optimal contextual enhancement:
Summary Prompt (for document-level summary):
`
Summarize the following document in 5-7 sentences, focusing on the main topics and concepts that would help retrieve relevant chunks.
Context Prompt (for chunk-specific context):
`
Using the document summary above, generate a brief contextual description that explains what this specific chunk covers and how it relates to the overall document. Focus on the unique aspects of this chunk. Keep it to 2-3 sentences and answer only with the context.
Both prompts are fully customizable. The document summary and chunk content are automatically provided in a structured format.
You can choose whether to include labels in the output:
- Without Labels (default): Clean output with just context and chunk content separated by line breaks
- With Labels: Includes "Context:" and "Chunk:" labels for clarity
#### Prompt Configuration
- Summary Prompt: Instructions for generating the global document summary
- Context Prompt: Instructions for generating chunk-specific context using the summary
- Include Labels: Whether to include "Context:" and "Chunk:" labels in the output
#### Splitting Options
- Buffer Size: Number of sentences to combine for context when creating embeddings (default: 1)
- Breakpoint Threshold Type: Method for determining chunk boundaries (percentile, standard deviation, interquartile, gradient)
- Number of Chunks: Target number of chunks to create (overrides threshold settings if set)
- Second Pass Threshold: Similarity threshold for merging chunks in the second pass (0-1, default: 0.8)
- Min/Max Chunk Size: Size constraints for generated chunks (default: 100-2000 characters)
- Sentence Split Regex: Pattern for splitting text into sentences (default: (?<=[.?!])\\s+)
`
[Document Loader] → [Semantic Splitter with Context] → [Vector Store]
↑ ↑
[Chat Model] [Embeddings]
Each chunk is enhanced with contextual information generated using the Global Summary approach. With labels disabled (default):
`
Parents of Orange County teen Adam Raine and 153 other families urged Governor Gavin Newsom to sign AB 56 and AB 1064 after their children died by suicide linked to AI chatbots or harmful social media content.
SAN FRANCISCO, October 6, 2025 — The parents of Orange County teenager Adam Raine, who died by suicide after using an artificial intelligence (AI) chatbot, and 153 other parents whose children died related to their use of social media or AI, today called on Governor Gavin Newsom to sign into law two bills...
`
With labels enabled:
`
Context: Parents of Orange County teen Adam Raine and 153 other families urged Governor Gavin Newsom to sign AB 56 and AB 1064 after their children died by suicide linked to AI chatbots or harmful social media content.
Chunk: SAN FRANCISCO, October 6, 2025 — The parents of Orange County teenager Adam Raine, who died by suicide after using an artificial intelligence (AI) chatbot, and 153 other parents whose children died related to their use of social media or AI, today called on Governor Gavin Newsom to sign into law two bills...
`
- Improved Retrieval: Contextual descriptions help with more accurate search results
- Semantic Coherence: Chunks maintain semantic meaning through intelligent boundary detection and merging
- Token Efficiency: Global summary option dramatically reduces API costs for large documents
- Production Stability: Memory leak protections and payload validation prevent system crashes
- Flexible Configuration: Adaptable to different document types and use cases
- RAG Optimization: Designed specifically for Retrieval-Augmented Generation workflows
- Token Efficiency: Global Summary approach reduces API calls from N to 1+N (1 summary + N contexts vs N full-document contexts)
- Prompt Customization: Adjust Summary Prompt for better document overviews, Context Prompt for better chunk descriptions
- Chunk Control: Use numberOfChunks for predictable output size, or threshold methods for semantic-driven splittingN8N_NODES_DEBUG=1
- Large Documents: Node handles up to 10MB documents with automatic payload size validation
- Debugging: Set to see detailed debug logs during development
and @langchain/textsplitters` dependenciesMIT
Contributions are welcome! Please feel free to submit a Pull Request.