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

> Master chunk overlap in Cognee with our complete guide. Learn configuration options via API, CLI, or TextChunkerWithOverlap for optimized document processing.

- Repository: [Topoteretes/cognee](https://github.com/topoteretes/cognee)
- Tags: how-to-guide
- Published: 2026-03-16

---

**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`](https://github.com/topoteretes/cognee/blob/main/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`](https://github.com/topoteretes/cognee/blob/main/cognee/api/v1/config/config.py). This approach ensures all subsequent chunking operations use the specified overlap value.

```python
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`](https://github.com/topoteretes/cognee/blob/main/cognee/cli/commands/config_command.py). The command maps directly to `config.set_chunk_overlap`.

```bash
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`](https://github.com/topoteretes/cognee/blob/main/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)`.

```python
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`](https://github.com/topoteretes/cognee/blob/main/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`](https://github.com/topoteretes/cognee/blob/main/cognee/infrastructure/data/chunking/config.py) - Declares default overlap values
- [`cognee/api/v1/config/config.py`](https://github.com/topoteretes/cognee/blob/main/cognee/api/v1/config/config.py) - Implements the public `set_chunk_overlap` API
- [`cognee/cli/commands/config_command.py`](https://github.com/topoteretes/cognee/blob/main/cognee/cli/commands/config_command.py) - Handles CLI configuration commands
- [`cognee/modules/chunking/text_chunker_with_overlap.py`](https://github.com/topoteretes/cognee/blob/main/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`](https://github.com/topoteretes/cognee/blob/main/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`](https://github.com/topoteretes/cognee/blob/main/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`](https://github.com/topoteretes/cognee/blob/main/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.