How to Set Chunk Overlap in Cognee: A Complete Configuration Guide

Chunk overlap in Cognee can be configured globally via the configuration API, through the CLI using cognee config set chunk_overlap, or per-instance using the chunk_overlap_ratio parameter in TextChunkerWithOverlap.

When splitting documents into chunks for retrieval-augmented generation (RAG), preserving context across boundaries is critical for maintaining semantic coherence. In the Cognee open-source repository, chunk overlap determines how many characters are duplicated between consecutive chunks to ensure no information is lost at segment boundaries. This guide covers the three distinct methods to configure chunk overlap in Cognee, from global application settings to granular instance-level control.

Understanding Chunk Overlap Defaults

The global chunking configuration in cognee/infrastructure/data/chunking/config.py defines a default chunk_overlap value of 10 characters. This setting applies universally unless overridden by specific chunking engines or runtime configurations. However, when instantiating TextChunkerWithOverlap directly, the default chunk_overlap_ratio is 0.0, resulting in no overlap unless explicitly specified.

Global Configuration Methods

Programmatic Configuration via Python API

The cognee.api.v1.config.config module exposes a static method set_chunk_overlap() that updates the shared configuration object defined in cognee/api/v1/config/config.py. This approach ensures all subsequent chunking operations use the specified overlap value.

from cognee.api.v1.config import config

# Set a fixed overlap of 20 characters for all chunkers

config.set_chunk_overlap(20)

Command Line Interface

For runtime adjustments without modifying code, use the built-in CLI handler defined in cognee/cli/commands/config_command.py. The command maps directly to config.set_chunk_overlap.

cognee config set chunk_overlap 30

Instance-Level Configuration with TextChunkerWithOverlap

For proportional overlap based on chunk size rather than fixed character counts, instantiate TextChunkerWithOverlap from cognee/modules/chunking/text_chunker_with_overlap.py with the chunk_overlap_ratio parameter. The chunker automatically calculates the absolute overlap as int(max_chunk_size * ratio).

from cognee.modules.chunking.text_chunker_with_overlap import TextChunkerWithOverlap

chunker = TextChunkerWithOverlap(
    document=my_doc,
    get_text=my_async_text_provider,
    max_chunk_size=1500,
    chunk_overlap_ratio=0.1,  # 10% of 1500 = 150 characters overlap

)

How Chunk Overlap Works Under the Hood

The core overlap logic resides in TextChunkerWithOverlap._clear_accumulation within cognee/modules/chunking/text_chunker_with_overlap.py. As the chunker accumulates text, it monitors the total size against max_chunk_size. When adding the next segment would exceed this limit, the chunker emits the current chunk and preserves the last N characters (as defined by the overlap configuration) as the starting buffer for the next accumulation cycle. This ensures contextual continuity across chunk boundaries without duplicating entire documents.

Key configuration files:

• cognee/infrastructure/data/chunking/config.py - Declares default overlap values
• cognee/api/v1/config/config.py - Implements the public set_chunk_overlap API
• cognee/cli/commands/config_command.py - Handles CLI configuration commands
• cognee/modules/chunking/text_chunker_with_overlap.py - Implements proportional overlap logic and buffer management

Summary

• Global default: 10 characters, defined in cognee/infrastructure/data/chunking/config.py
• API method: Use config.set_chunk_overlap(20) from cognee.api.v1.config
• CLI method: Execute cognee config set chunk_overlap <int>
• Instance control: Pass chunk_overlap_ratio to TextChunkerWithOverlap for proportional overlap
• Implementation: Overlap buffers are managed in _clear_accumulation during the chunking process

Frequently Asked Questions

What is the default chunk overlap in Cognee?

The default global chunk overlap is 10 characters, as defined in cognee/infrastructure/data/chunking/config.py. However, TextChunkerWithOverlap instances default to chunk_overlap_ratio=0.0, meaning no overlap unless explicitly configured.

How do I calculate the overlap when using chunk_overlap_ratio?

Cognee calculates the absolute overlap automatically using the formula int(max_chunk_size * chunk_overlap_ratio). For example, with max_chunk_size=1000 and chunk_overlap_ratio=0.15, the resulting overlap is 150 characters.

Can I set chunk overlap for specific documents only?

Yes. While global settings affect all chunking operations, you can override overlap for specific documents by instantiating TextChunkerWithOverlap directly with a custom chunk_overlap_ratio or by temporarily modifying the global config before processing specific documents.

Where is the overlap buffer logic implemented?

The overlap preservation logic is implemented in the _clear_accumulation method of TextChunkerWithOverlap, located in cognee/modules/chunking/text_chunker_with_overlap.py. This method handles retaining the tail end of each chunk to prepend to the next chunk accumulation.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}