mirror of
https://github.com/headroomlabs-ai/headroom.git
synced 2026-08-27 14:17:10 -04:00
9c9bb30ded
Features: - with_fast_memory(): Zero-latency inline extraction (Letta-style) - Memory extracted as part of LLM response, no extra API calls - Semantic retrieval with local embeddings (sub-50ms) - with_memory(): Background extraction for non-blocking memory - SQLite + FTS5 storage with vector similarity search - Multi-user isolation by user_id Memory enables temporal compression - extract key facts instead of carrying full conversation history (4000 tokens → 50 tokens). Includes: - Comprehensive test suite (71 new tests) - Documentation (docs/memory.md) - Benchmark examples comparing approaches - E2E test with LLM-as-judge evaluation |
||
|---|---|---|
| .. | ||
| langchain_demo | ||
| mcp_demo | ||
| anthropic_example.py | ||
| basic_usage.py | ||
| ccr_demo.py | ||
| fast_memory_e2e.py | ||
| inline_memory_demo.py | ||
| langchain_before_after.py | ||
| memory_e2e_test.py | ||
| memory_latency_benchmark.py | ||
| README.md | ||
| real_world_eval.py | ||
| real_world_openai_eval.py | ||
| smart_vs_naive_eval.py | ||
| streaming_example.py | ||
Headroom Examples
This directory contains examples demonstrating Headroom's capabilities.
Quick Start Examples
basic_usage.py
Basic integration with OpenAI client:
export OPENAI_API_KEY='your-key'
python examples/basic_usage.py
anthropic_example.py
Integration with Anthropic Claude:
export ANTHROPIC_API_KEY='your-key'
python examples/anthropic_example.py
streaming_example.py
Streaming responses with optimization:
export OPENAI_API_KEY='your-key'
python examples/streaming_example.py
Evaluation Examples
smart_vs_naive_eval.py
Compare SmartCrusher against naive truncation:
export OPENAI_API_KEY='your-key'
python examples/smart_vs_naive_eval.py
real_world_eval.py
Comprehensive evaluation with Anthropic models:
export ANTHROPIC_API_KEY='your-key'
python examples/real_world_eval.py
real_world_openai_eval.py
Comprehensive evaluation with OpenAI models:
export OPENAI_API_KEY='your-key'
python examples/real_world_openai_eval.py
Demo Directories
langchain_demo/
Full LangChain agent integration demo:
# No API key needed for compression demo
PYTHONPATH=. python -m examples.langchain_demo.show_compression
# Full comparison (requires API key)
export OPENAI_API_KEY='your-key'
PYTHONPATH=. python -m examples.langchain_demo.run_comparison
See langchain_demo/README.md for details.
mcp_demo/
MCP (Model Context Protocol) integration demo:
export OPENAI_API_KEY='your-key'
PYTHONPATH=. python -m examples.mcp_demo.run_agent_eval
Running Examples
All examples can be run from the repository root:
# Install dependencies
pip install -e ".[dev]"
# Run any example
python examples/<example_name>.py
Expected Results
| Example | Token Savings | Notes |
|---|---|---|
| basic_usage | 50-70% | Simple tool output compression |
| langchain_demo | 70-85% | Real agent with multiple tools |
| mcp_demo | 60-80% | MCP tool outputs |
| real_world_eval | 50-90% | Varies by scenario |
Troubleshooting
ModuleNotFoundError: No module named 'headroom'
Run from the repository root with PYTHONPATH:
PYTHONPATH=. python examples/basic_usage.py
Or install in development mode:
pip install -e .
API Key Errors
Ensure your API keys are set:
export OPENAI_API_KEY='sk-...'
export ANTHROPIC_API_KEY='sk-ant-...'