mirror of https://github.com/headroomlabs-ai/headroom.git synced 2026-08-27 14:17:10 -04:00

History

chopratejas da74341858 Add hierarchical memory system with graph + vector storage Implement comprehensive memory system supporting: - Local backend (SQLite + FTS5 + HNSW) for zero-dependency operation - Mem0 backends (Neo4j + Qdrant) for production graph memory - DirectMem0Adapter for optimized pre-extracted data (bypasses LLM) - Memory extraction with facts, entities, and relationships - Proxy integration with --memory flag for automatic memory injection Key components: - headroom/memory/backends/: LocalBackend, Mem0Backend, DirectMem0Adapter - headroom/memory/system.py: MemorySystem with tool-based interface - headroom/memory/extraction.py: Entity and relationship extraction - headroom/proxy/memory_handler.py: Proxy integration layer - headroom/prediction/feature_extractor.py: Content analysis features Testing: - 217 new memory system tests covering all backends - LoCoMo evaluation framework for memory quality assessment - Integration tests for proxy memory functionality Also removes deprecated example files in favor of focused test coverage.		2026-01-26 21:58:47 -08:00
..
deployment/macos-launchagent	fix(deployment): correct port placeholder in LaunchAgent plist template	2026-01-19 13:44:30 -08:00
langchain_demo	Fix all ruff lint and format errors for CI	2026-01-10 15:33:44 -08:00
mcp_demo	Fix all ruff lint and format errors for CI	2026-01-10 15:33:44 -08:00
README.md	Prepare for OSS release v0.2.0	2026-01-07 11:36:44 -08:00

README.md

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-...'