claudetools/api/utils/CONTEXT_COMPRESSION_QUICK_REF.md

Context Compression - Quick Reference

Location: D:\ClaudeTools\api\utils\context_compression.py

Quick Import

from api.utils.context_compression import *
# or
from api.utils import compress_conversation_summary, create_context_snippet, format_for_injection

Function Quick Reference

Function	Input	Output	Token Reduction
compress_conversation_summary(conversation)	str or list[dict]	Dense JSON summary	85-90%
create_context_snippet(content, type, importance)	str, str, int	Structured snippet	N/A
compress_project_state(details, work, files)	dict, str, list	Dense state	85-90%
extract_key_decisions(text)	str	list[dict]	N/A
calculate_relevance_score(snippet, time)	dict, datetime	float (0-10)	N/A
merge_contexts(contexts)	list[dict]	Merged dict	30-50%
format_for_injection(contexts, max_tokens)	list[dict], int	Markdown str	60-80%
extract_tags_from_text(text)	str	list[str]	N/A
compress_file_changes(files)	list[str]	list[dict]	N/A

Common Patterns

Pattern 1: Save Conversation Context

summary = compress_conversation_summary(messages)
snippet = create_context_snippet(
    json.dumps(summary),
    snippet_type="state",
    importance=6
)
db.add(ContextSnippet(**snippet))
db.commit()

Pattern 2: Load and Inject Context

snippets = db.query(ContextSnippet)\
    .order_by(ContextSnippet.relevance_score.desc())\
    .limit(20).all()

contexts = [s.to_dict() for s in snippets]
prompt = format_for_injection(contexts, max_tokens=1000)

# Use in Claude prompt
messages = [
    {"role": "system", "content": f"{system_msg}\n\n{prompt}"},
    {"role": "user", "content": user_msg}
]

Pattern 3: Record Decision

decision = create_context_snippet(
    "Using PostgreSQL for better JSON support and performance",
    snippet_type="decision",
    importance=9
)
db.add(ContextSnippet(**decision))

Pattern 4: Track Blocker

blocker = create_context_snippet(
    "Redis connection failing in production",
    snippet_type="blocker",
    importance=10
)
db.add(ContextSnippet(**blocker))

Pattern 5: Update Relevance Scores

snippets = db.query(ContextSnippet).all()
for snippet in snippets:
    data = snippet.to_dict()
    snippet.relevance_score = calculate_relevance_score(data)
db.commit()

Pattern 6: Merge Agent Contexts

# Load contexts from multiple sources
conv_context = compress_conversation_summary(messages)
project_context = compress_project_state(project, work, files)
db_contexts = [s.to_dict() for s in db.query(ContextSnippet).limit(10)]

# Merge all
merged = merge_contexts([conv_context, project_context] + db_contexts)

Tag Categories

Technologies (Auto-detected)

fastapi, postgresql, redis, docker, nginx, python, javascript, sqlalchemy, alembic

Patterns

async, crud, middleware, dependency-injection, error-handling, validation, optimization, refactor

Categories

critical, blocker, bug, feature, architecture, integration, security, testing, deployment

Relevance Score Formula

Score = base_importance
        - min(2.0, age_days × 0.1)         # Time decay
        + min(2.0, usage_count × 0.2)      # Usage boost
        + (important_tags × 0.5)           # Tag boost
        + (1.0 if used_in_24h else 0.0)    # Recency boost

Clamped to [0.0, 10.0]

Important Tags

critical, blocker, decision, architecture, security, performance, bug

File Type Detection

Path Pattern	Type
*test*	test
*migration*	migration
*config*.{yaml,json,toml}	config
*model*, *schema*	schema
*api*, *route*, *endpoint*	api
.{py,js,ts,go,java}	impl
.{md,txt,rst}	doc
*docker*, *deploy*	infra

One-Liner Examples

# Compress and save conversation
db.add(ContextSnippet(**create_context_snippet(
    json.dumps(compress_conversation_summary(messages)),
    "state", 6
)))

# Load top contexts as prompt
prompt = format_for_injection(
    [s.to_dict() for s in db.query(ContextSnippet)
        .order_by(ContextSnippet.relevance_score.desc())
        .limit(20)],
    max_tokens=1000
)

# Extract and save decisions
for decision in extract_key_decisions(text):
    db.add(ContextSnippet(**create_context_snippet(
        f"{decision['decision']} because {decision['rationale']}",
        "decision",
        8 if decision['impact'] == 'high' else 6
    )))

# Auto-tag and save
snippet = create_context_snippet(content, "general", 5)
# Tags auto-extracted from content

# Update all relevance scores
for s in db.query(ContextSnippet):
    s.relevance_score = calculate_relevance_score(s.to_dict())
db.commit()

Token Budget Guide

Max Tokens	Use Case	Contexts
200	Critical only	3-5
500	Essential	8-12
1000	Standard	15-25
2000	Extended	30-50

Error Handling

All functions handle edge cases:

• Empty input → Empty/default output
• Invalid dates → Current time
• Missing fields → Defaults
• Malformed JSON → Graceful degradation

Testing

cd D:\ClaudeTools
python test_context_compression_quick.py

All 9 tests should pass.

Performance

• Conversation compression: ~1ms per message
• Tag extraction: ~0.5ms per text
• Relevance calculation: ~0.1ms per snippet
• Format injection: ~10ms for 20 contexts

Common Issues

Issue: Tags not extracted Solution: Check text contains recognized keywords

Issue: Low relevance scores Solution: Increase importance or usage_count

Issue: Injection too long Solution: Reduce max_tokens or limit contexts

Issue: Missing fields in snippet Solution: All required fields have defaults

Full Documentation

• Examples: api/utils/CONTEXT_COMPRESSION_EXAMPLES.md
• Summary: api/utils/CONTEXT_COMPRESSION_SUMMARY.md
• Tests: test_context_compression_quick.py