claudetools/api/utils/CONTEXT_COMPRESSION_QUICK_REF.md

# Context Compression - Quick Reference

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

## Quick Import

```python
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

```python
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

```python
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

```python
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

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

### Pattern 5: Update Relevance Scores

```python
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

```python
# 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

```python
# 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

```bash
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`