Module dedup 

Hint-based deduplication cache for tool responses in multi-turn agents.

When an LLM agent re-requests data it has already seen (file re-reads after unrelated edits, MCP pipeline polls, repeated status checks), the response bytes are often identical. Instead of re-emitting the full payload, the pipeline emits a compact reference hint that points at an earlier tool_call_id still present in the agent’s context window.

On anonymized Claude Code session logs, this mechanism recovers ≈33% of total tokens (see docs/research/paper-2-mckp-format-adaptive.md).

Design

• Content-hash fingerprint — SHA-256/128-bit prefix. Collisions are negligible for session volumes (≤10⁵ responses).
• Bounded LRU — capacity defaults to 5; 95% of real-world savings concentrate in the most recent 3 responses.
• Partition-scoped — cleared on on_compaction_boundary() (corresponds to Claude Code’s compact_boundary JSONL event); older references are no longer reachable from the agent’s context.
• Mutation-aware — FileRead entries whose path is later mutated by FileMutate are invalidated immediately. Prevents stale hints after an Edit or Write.

Usage

use devboy_format_pipeline::dedup::{DedupCache, DedupDecision, ToolKind, content_hash, render_reference_hint};

let mut cache = DedupCache::with_capacity(5);
let body = "pipeline 12345 status=success duration=120s";
let fp = content_hash(body.as_bytes());

match cache.check(&fp) {
    DedupDecision::Hint { reference_tool_call_id } => {
        let hint = render_reference_hint(&reference_tool_call_id);
        // emit `hint` instead of `body`
    }
    DedupDecision::Fresh => {
        // emit `body` normally and cache it
        cache.insert(fp, "tc_42", ToolKind::Other, None, "Bash");
    }
}

Structs

DedupCache

Session-scoped deduplication cache.

Enums

DedupDecision

Outcome of a DedupCache::check lookup.

HintVerbosity

Verbosity level for rendered reference hints.

ToolKind

Classification used to drive mutation-based invalidation.

Functions

content_hash

Compute the content hash used by DedupCache.

render_reference_hint

Render a reference hint using the default (Standard) verbosity.

render_reference_hint_with

Render a reference hint at the requested verbosity.

Type Aliases

ContentHash

128-bit content fingerprint (first 16 bytes of SHA-256).