feat: add context compaction hook

[sjrl]

Related Issues

• part of Add a Compaction Tool and Hook #10866

Proposed Changes:

Added experimental context compaction for the Agent. ContextCompactionHook runs before LLM calls and shortens the conversation when it reaches a configured fraction of the model's context window.

The first built-in strategy, SlidingWindowCompactor, preserves leading system messages and as much recent history as the target allows. It replaces removed history with a short omission note.

from haystack.components.agents import Agent
from haystack.components.generators.chat import OpenAIChatGenerator
from haystack.hooks.compaction import ContextCompactionHook, SlidingWindowCompactor

hook = ContextCompactionHook(
    compactor=SlidingWindowCompactor(),
    context_window=200_000,
    compact_at=0.7,
    compact_to=0.4,
)
agent = Agent(
    chat_generator=OpenAIChatGenerator(model="gpt-5.4-nano"),
    tools=[web_search],
    hooks={"before_llm": [hook]},
)

The hook uses provider-reported context usage when available and locally estimates the request otherwise, including
tool schemas. Leave headroom above compact_at for the next reply and its tool results.

SlidingWindowCompactor keeps tool calls together with their results, so it may retain slightly more history than the requested target. Compaction is lossy: removed messages cannot be recovered or summarized by this strategy. Implement the Compactor protocol to provide a custom strategy.

ContextCompactionHook and SlidingWindowCompactor emit an ExperimentalWarning and may change without a deprecation cycle.

How did you test it?

New tests

Notes for the reviewer

Checklist

• I have read the contributors guidelines and the code of conduct.
• I have updated the related issue with new insights and changes.
• I have added unit tests and updated the docstrings.
• I've used one of the conventional commit types for my PR title: fix:, feat:, build:, chore:, ci:, docs:, style:, refactor:, perf:, test: and added ! in case the PR includes breaking changes.
• I have documented my code.
• I have added a release note file, following the contributors guidelines.
• I have run pre-commit hooks and fixed any issue.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

1 Skipped Deployment

Project	Deployment	Actions	Updated (UTC)
haystack-docs	Ignored	Preview	Jul 31, 2026 10:10am

[github-actions]

Coverage report

Click to see where and how coverage changed

File	Statements	Missing	Coverage	Coverage (new stmts)	Lines missing
haystack/hooks/compaction
__init__.py
hooks.py					215, 222, 227, 239-240
sliding_window.py
utils.py
haystack/hooks/compaction/types
__init__.py
protocol.py
Project Total

This report was generated by python-coverage-comment-action

[anakin87]

If the overhead is negative, should we log a warning to alert the user that the token_counter tends to overestimate?

[anakin87]

I have some doubts about min_keep_messages

• I'm not sure that the explanation is correct
• looking at how it works, what about using min_keep_turns instead?

[sjrl]

Thats fair! For something like min_keep_turns what would you say a full turn is? Is one turn a "user" --> "assistant" --> "all tool results" group?

[anakin87]

1. Sorry, maybe min_keep_steps is better where step = assistant msg + all tool results
2. I now notice that we risk losing the first user message that probably contains the most relevant info

[anakin87]

Somewhere we should mention that a Compactor should not divide tool results from tool calls

[anakin87]

I left some comments but overall I like the design!