headroomlabs-ai/headroom

🗜️ Headroom: Lớp nén ngữ cảnh cho AI agents

Nén tool output, logs, RAG chunks, files và conversation history trước khi tới LLM — giảm 60-95% token, giữ nguyên đáp án.

Headroom là một công cụ nén ngữ cảnh chạy cục bộ (local-first), giúp các AI agents và LLM nhận được thông tin tương đương với ít token hơn. Dự án hỗ trợ nhiều dạng triển khai: dưới dạng thư viện (library), proxy trung gian, hoặc server MCP. Nó sử dụng sáu thuật toán nén khác nhau nhằm xử lý JSON, code (AST) và văn bản tự nhiên.

✨ Điểm nổi bật

• Library: Hàm compress(messages) hỗ trợ Python và TypeScript, dùng trực tiếp trong ứng dụng.
• Proxy: Chạy qua lệnh headroom proxy --port 8787, hỗ trợ bất kỳ ngôn ngữ nào mà không cần thay đổi code.
• Agent wrap: Tích hợp nhanh với các agent như Claude, Codex, Cursor, Aider, Copilot, OpenCode bằng một lệnh.
• MCP server: Cung cấp các công cụ như headroom_compress, headroom_retrieve, headroom_stats cho mọi client MCP.
• Cross-agent memory: Lưu trữ trí nhớ chung giữa các agent (Claude, Codex, Gemini), tự động loại bỏ trùng lặp.
• headroom learn: Phân tích session thất bại, ghi chú khắc phục vào CLAUDE.md hoặc AGENTS.md.
• Output token reduction: Giảm token model trả về bằng cách loại bỏ nội dung không cần thiết như lặp lại code hay suy nghĩ sâu không cần thiết.
• Reversible (CCR): Lưu trữ bản gốc cục bộ, hỗ trợ truy xuất khi cần.

💡 Vì sao đáng chú ý

Headroom không chỉ nén dữ liệu một cách ngẫu nhiên — nó dùng ContentRouter để phân biệt loại nội dung (JSON, code, văn bản) và áp dụng thuật toán nén phù hợp. Điều này giúp tiết kiệm tối đa token mà không mất thông tin quan trọng. Với công nghệ CacheAligner, Headroom còn tối ưu cả hiệu suất KV cache của nhà cung cấp LLM.

Nhờ thiết kế local-first, dữ liệu của người dùng luôn được kiểm soát, an toàn và tuân thủ quyền riêng tư. Đây là lựa chọn lý tưởng cho các nhóm phát triển muốn tối ưu chi phí và tốc độ khi làm việc với các mô hình lớn.

#AI #ContextCompression #LLM #MCP #OpenSource #TiniX