Headroom: lớp nén ngữ cảnh giúp AI agent tiết kiệm token

Headroom là gì

Nếu bạn dùng Claude Code, Codex, Cursor hay các coding agent khác mỗi ngày, có lẽ bạn đã thấy token tiêu hao nhanh thế nào khi agent đọc log, kết quả tìm kiếm hay những file JSON dài. Headroom (headroomlabs-ai/headroom) là dự án mã nguồn mở viết bằng Python, đóng vai trò một lớp nén ngữ cảnh: nó nén kết quả công cụ, log, file, đoạn RAG và lịch sử hội thoại trước khi chúng tới LLM.

Theo mô tả của dự án, coding agent có thể dùng ít hơn khoảng 20% token, còn với JSON con số là 60 đến 95%, trong khi câu trả lời vẫn như cũ. Điểm đáng chú ý là việc nén chạy ngay trên máy bạn, nội dung prompt hay file không bị gửi đi đâu để nén. Dự án hướng tới lập trình viên làm việc nhiều với AI agent và những ai muốn giảm chi phí token mà không phải sửa nhiều code.

Các tính năng chính

Headroom có nhiều cách dùng khác nhau, tùy bạn muốn can thiệp sâu đến đâu:

• Thư viện: gọi compress(messages) trong Python hoặc TypeScript, chèn thẳng vào ứng dụng.
• Proxy: chạy headroom proxy --port 8787, không cần đổi code, dùng được với mọi ngôn ngữ.
• Bọc agent: lệnh headroom wrap hỗ trợ claude, codex, grok, copilot, aider, opencode, cline, continue, goose, openhands và nhiều công cụ khác. Muốn gỡ thì dùng headroom unwrap <tool>.
• MCP server: cung cấp các công cụ headroom_compress, headroom_retrieve, headroom_stats cho mọi MCP client.
• Bộ nhớ dùng chung giữa các agent: một kho chung cho Claude, Codex, Gemini và Grok, tự động loại trùng lặp.
• headroom learn: phân tích các phiên làm việc thất bại và ghi phần sửa lỗi vào CLAUDE.local.md, CLAUDE.md, AGENTS.md, GEMINI.md hoặc GROK.md.
• Giảm token đầu ra: cắt bớt cả phần model viết trả lại, không chỉ phần bạn gửi đi.
• Nén có thể đảo ngược (CCR): bản gốc được lưu cục bộ, model có thể lấy lại khi cần.

Cách Headroom hoạt động

Bên trong, Headroom có một chuỗi xử lý rõ ràng:

• ContentRouter nhận diện loại nội dung và chọn bộ nén phù hợp.
• SmartCrusher xử lý JSON. Nó giữ lại các mục lỗi, các giá trị bất thường và phần đầu, cuối của mảng, dựa trên thống kê thay vì danh sách từ khóa.
• CodeCompressor nén mã nguồn dựa trên AST, hỗ trợ Python, JS/TS, Go, Rust, Java, C/C++, C#, PHP.
• Kompress-v2-base là model trên HuggingFace do nhóm phát triển, dùng để nén văn bản.
• CacheAligner đánh dấu nội dung hay thay đổi có thể làm hỏng cache phía nhà cung cấp, nhưng không bao giờ viết lại prompt.
• CCR lưu bản gốc để model gọi headroom_retrieve khi cần toàn văn.

README cũng nhắc tới cơ chế nén vùng mới: chỉ phần dữ liệu mới (kết quả công cụ vừa có, lượt hội thoại mới nhất) được nén, phần đầu prompt giữ nguyên từng byte để cache của nhà cung cấp vẫn hoạt động.

Số liệu dự án công bố

Nhóm phát triển đưa ra bốn kịch bản dựng từ định dạng đầu ra của MCP server thật. Ví dụ, kịch bản gỡ lỗi sự cố SRE giảm từ 55.957 xuống 24.340 token (tiết kiệm 57%), khám phá codebase tiết kiệm 42%, phân loại issue GitHub tiết kiệm 30% và tìm kiếm code tiết kiệm 21%. Bạn có thể tự chạy lại bằng lệnh benchmark có trong repo.

Dự án cũng nói rõ: mức tiết kiệm phụ thuộc vào độ lặp lại của dữ liệu. Văn xuôi và dữ liệu vốn đã cô đọng gần như không nén được bao nhiêu. Về tốc độ, việc nén mất khoảng 0,21 ms (p50) với kết quả JSON 10K token và 1,4 ms với 100K token.

Giảm cả token đầu ra

Ngoài phần gửi đi, Headroom có thể giảm phần model trả về thông qua proxy, mặc định tắt:

• Verbosity steering: thêm một ghi chú ngắn yêu cầu trả lời gọn vào cuối system prompt, nên cache prompt vẫn trúng.
• Effort routing: giảm mức suy luận khi lượt đó chỉ là model tiếp tục sau một kết quả công cụ, như đọc file hay test đã qua. Câu hỏi mới và lỗi vẫn giữ mức đầy đủ.

export HEADROOM_OUTPUT_SHAPER=1
headroom proxy --port 8787

Khi nào nên dùng

Theo README, Headroom phù hợp nếu bạn chạy coding agent hằng ngày và muốn tiết kiệm mà không đụng vào code, làm việc với nhiều agent và cần bộ nhớ chung, hoặc cần cơ chế nén có thể lấy lại bản gốc. Nó phát huy tốt nhất trong các phiên agent dài với nhiều đầu ra công cụ.

Ngược lại, bạn có thể bỏ qua nếu chỉ dùng tính năng nén có sẵn của một nhà cung cấp và không cần bộ nhớ chung, hoặc làm việc trong môi trường không cho chạy tiến trình cục bộ. Các cuộc trò chuyện ngắn cũng gần như không được lợi gì.

Bắt đầu sử dụng

Các bước dưới đây lấy từ phần hướng dẫn nhanh trong README:

1. Cài đặt. CLI headroom chỉ có trong gói PyPI, còn gói npm là SDK TypeScript, không kèm CLI:

   uv tool install --python 3.13 "headroom-ai[all]"
   pip install "headroom-ai[all]"
   npm install headroom-ai

2. Chọn một chế độ dùng:

   headroom deploy
   headroom wrap claude
   headroom proxy --port 8787

3. Kiểm tra và theo dõi mức tiết kiệm:

   headroom doctor
   headroom perf
   headroom dashboard

Nếu muốn dùng trực tiếp trong Python, đoạn mã mẫu trong README như sau:

from headroom import compress
from openai import OpenAI

messages = [{"role": "user", "content": "Analyze these results"}]
result = compress(messages, model="gpt-4o")

client = OpenAI()
response = client.chat.completions.create(model="gpt-4o", messages=result.messages)
print(f"Saved {result.tokens_saved} tokens ({result.compression_ratio:.0%})")

Lưu ý: headroom wrap sẽ khởi động proxy cục bộ và mặc định cài thêm Serena để điều hướng code theo ngữ nghĩa. Bạn có thể bỏ qua bằng tùy chọn --code-memory none.

Một vài lưu ý

• Giấy phép: Apache 2.0. Ngoài bản mã nguồn mở còn có bản Enterprise cho doanh nghiệp, nhưng mọi thứ trong repo vẫn mở theo Apache 2.0.
• Yêu cầu: Python 3.10 trở lên. README cho biết có wheel dựng sẵn cho Windows, Linux và macOS, ngoài ra có image Docker.
• Telemetry: một beacon ẩn danh được bật mặc định, gửi tỷ lệ nén, bộ đếm, ID model, hệ điều hành, không gửi prompt hay code. Bạn tắt bằng HEADROOM_TELEMETRY=off hoặc DO_NOT_TRACK=1.
• Độ trưởng thành: phiên bản mới nhất là v0.41.0 và dự án có hơn 77 nghìn sao trên GitHub.

Kết luận

Headroom là lựa chọn đáng thử nếu bạn đang tốn nhiều token cho coding agent, nhất là với log và JSON dài. Việc nén chạy cục bộ, có thể đảo ngược và tích hợp được theo nhiều cách, từ thư viện, proxy đến MCP server. Bạn có thể xem mã nguồn và tài liệu chi tiết tại kho GitHub của Headroom.