contextdecay

Persistent, cross-session context decay detection for LLM apps.

contextdecay tracks how much your Claude session has drifted from its original context — across multiple sessions — and surfaces it on demand via decaycheck() or the contextdecay check CLI command.

---

Install

pip install contextdecay

---

Quick start

from anthropic import Anthropic
from contextdecay import ContextDecayDetector

client = Anthropic()
detector = ContextDecayDetector(client, persist="./myapp.decay")

# Normal calls — zero overhead
response = detector.messages.create(
    model="claude-haiku-4-5-20251001",
    system="You are a customer support assistant for RetailCo.",
    messages=[{"role": "user", "content": "What is your return policy?"}],
    max_tokens=200,
)

# Check drift on demand
report = detector.decaycheck()
print(report)

Output:

DecayReport (sessions=3, turns=18)
  cumulative : score=0.721 | on_track | OK
  recent     : score=0.812 | on_track | OK

---

How it works

Session 1, msgs 1–5  →  original context fingerprint captured + saved to .decay file
Session N, any turn  →  response embedded locally (~20ms) — zero API cost
decaycheck()         →  cumulative score (vs original) + recent score (vs last check)
                     →  if triggered: Haiku explains what drifted
                     →  checkpoint updated

Original context = system prompt + first 5 user+assistant messages. Fingerprint = persisted to a local .decay JSON file — survives across sessions.

---

CLI

# Check drift now (requires ANTHROPIC_API_KEY)
contextdecay check
contextdecay check --file ./myapp.decay

# Inspect fingerprint metadata (no API call)
contextdecay status
contextdecay status --file ./myapp.decay

# Reset — wipe fingerprint and start fresh
contextdecay reset
contextdecay reset --file ./myapp.decay

---

DecayReport

report = detector.decaycheck()

# Cumulative: vs original context (session 1)
report.cumulative.score        # 0.38
report.cumulative.level        # DecayLevel.SIGNIFICANT
report.cumulative.triggered    # True
report.cumulative.explanation  # "Responses shifted from retail support to..."

# Recent: vs last decaycheck() call
report.recent.score            # 0.71
report.recent.level            # DecayLevel.ON_TRACK
report.recent.triggered        # False

# Session metadata
report.session_count           # 4
report.total_turns             # 23

---

Decay levels

Score	Level	Meaning
≥ 0.55	on_track	Aligned with original context
0.40 – 0.54	mild	Some drift
0.25 – 0.39	significant	Noticeable drift
< 0.25	severe	Serious misalignment

---

Configuration

detector = ContextDecayDetector(
    client,
    persist="./myapp.decay",       # where to store the fingerprint
    threshold=0.40,                 # trigger sensitivity
    explain=True,                   # Haiku explains drift on trigger
    embedding_model="all-MiniLM-L6-v2",
    explainer_model="claude-haiku-4-5-20251001",
)

---

Session management

# Check if original context has been captured yet
detector.is_fingerprinted   # True after 5 messages

# Current session and turn counts
detector.session            # 3
detector.turn               # 18

# Wipe everything and start fresh
detector.reset()

---

Cost and latency

Operation	Extra tokens	Cost	Latency
Normal API call	0	$0	~20ms (local embed)
decaycheck() — no trigger	0	$0	<5ms
decaycheck() — triggered	~300	~$0.0003	+500ms
First run (model download)	0	$0	~3s one-time

---

Run the example

ANTHROPIC_API_KEY=your_key python3 examples/quickstart.py

---

Run tests

pip install -e ".[dev]"
pytest tests/ -v

---

Roadmap

• Multi-anchor support
• Decay history timeline
• Streaming support
• OpenAI / Gemini adapters
• Web dashboard

---

License

MIT