agent-context-recovery

agent-cop

Context recovery for AI agents. Analyze fatigue, compress context, improve token efficiency.

from agent_cop import analyze, recover

# Detect context bloat
report = analyze(messages)
# → { fatigue_score: 73, issues: [...], ... }

# Recover with algorithmic compression (free, no API key needed)
result = await recover(messages, budget_ratio=0.4)
# → { messages: [...], stats: { compression_ratio: "62.3%", ... } }

# Recover with LLM-based deep summarization (requires openai key)
result = await recover(messages, deep=True, openai_api_key="sk-...")

Quick install

pip install agent-cop

For deep LLM summarization:

pip install "agent-cop[deep]"

API

analyze(messages)

Detect context fatigue and bloat in a message history.

recover(messages, budget_ratio=0.5, deep=False, openai_api_key=None)

Compress a message history to fit within a budget. Algorithmic by default (free). Pass deep=True with an OpenAI key for semantic LLM-based summarization.

LangChain integration

from agent_cop.langchain import CopCallback
from langchain.agents import AgentExecutor

callback = SpaCallback(threshold=0.8)
agent = AgentExecutor(..., callbacks=[callback])
# Auto-recovers context at 80% token usage

REST API

curl -X POST https://api.agent-spa.dev/v1/recover \
  -H "x-api-key: $KEY" \
  -H "Content-Type: application/json" \
  -d '{"messages": [...], "budget_ratio": 0.4, "deep": true}'

Generate a free API key at https://agent-cop.dev.

License

MIT