headroomlabs-ai/headroom

Kết luận: fit · Công nghệ: llm-compression · mcp · python · rag · context-engineering

headroom là thư viện/proxy/MCP server nén đầu vào cho LLM (tool output, log, file, RAG chunk) trước khi gửi vào context window — giảm 20% token cho coding agent, 60–95% cho JSON, không ảnh hưởng chất lượng câu trả lời. Hỗ trợ Python, TypeScript, tích hợp được với LangChain, Claude Code, Cursor, OpenAI, Anthropic.

📖 Giới thiệu chi tiết

🧩 Nó là gì?

headroom là một lớp nén thông minh đặt giữa agent AI của bạn và mô hình ngôn ngữ lớn (LLM — hiểu đơn giản là "bộ não AI" như GPT-4, Claude…). Nó tự động thu gọn những thứ dài dòng — log, kết quả tìm kiếm, file code, output của tool — trước khi gửi vào LLM, giúp tiết kiệm chi phí và tăng tốc mà không làm mất thông tin quan trọng.

---

🎯 Giải quyết vấn đề gì? Dành cho ai?

LLM có một giới hạn gọi là context window (cửa sổ ngữ cảnh) — tức là lượng văn bản tối đa nó có thể "đọc" trong một lần. Khi bạn cho agent đọc file log khổng lồ, kết quả JSON dài thườn thượt hay cả đống kết quả tìm kiếm, bạn đang:

• Tốn tiền vì phí API tính theo số token (token ≈ một từ hoặc một mảnh từ)
• Chậm hơn vì mô hình phải xử lý nhiều hơn
• Dễ bị tràn context vì thông tin quan trọng bị đẩy ra ngoài

headroom sinh ra để giải quyết đúng ba điều đó. Nó phù hợp với:

• Lập trình viên đang xây dựng agent AI (dùng LangChain, OpenAI, Anthropic…)
• Người dùng các công cụ AI như Claude Code, Cursor, Codex, Aider, Cline…
• Bất kỳ ai đang chạy AI trên dữ liệu lớn và thấy hóa đơn API leo thang

---

⚙️ Hoạt động ra sao?

Agent của bạn (Claude Code, Cursor, LangChain…)
        │  gửi: log, tool output, file, kết quả RAG...
        ▼
    ┌──────────────────────────────────────────┐
    │  Headroom  (chạy trên máy bạn, offline)  │
    │  ContentRouter → chọn đúng bộ nén        │
    │  ├─ SmartCrusher    (nén JSON)           │
    │  ├─ CodeCompressor  (nén code, dùng AST) │
    │  └─ Kompress-v2     (nén văn bản xuôi)   │
    │  CCR: lưu bản gốc để lấy lại khi cần    │
    └──────────────────────────────────────────┘
        │  prompt đã nén  (ngắn hơn nhiều)
        ▼
    LLM (Anthropic, OpenAI, Bedrock…)

• ContentRouter tự nhận diện loại nội dung (JSON? code? text?) rồi chọn đúng thuật toán nén.
• SmartCrusher xử lý JSON — giảm được 60–95% token vì JSON thường có rất nhiều phần lặp lại.
• CodeCompressor dùng AST (cây cú pháp — cách máy hiểu cấu trúc code) để nén source code.
• Kompress-v2-base là model AI nhỏ (chạy local, lấy từ HuggingFace) để nén văn bản thông thường.
• CCR (Compressed Content Retrieval) lưu bản gốc trên máy bạn; nếu LLM cần đọc đầy đủ, nó gọi tool headroom_retrieve để lấy lại — không mất dữ liệu.
• Toàn bộ quá trình nén diễn ra trên máy bạn — không có prompt hay file nào được gửi ra ngoài để nén.
• Tốc độ nén cực nhanh: ~0.2ms cho 10K token, không ảnh hưởng đến latency.

---

🆚 Khi nào nên dùng / không nên

Tình huống	Nên dùng headroom?
Agent đọc file log, JSON output dài	✅ Tiết kiệm 60–95% token
Coding agent (Claude Code, Cursor…) xử lý codebase lớn	✅ Tiết kiệm ~20–57%
Câu hỏi ngắn, hội thoại bình thường	⚠️ Ít lợi ích — văn bản ngắn và dày đặc nén được rất ít
Dữ liệu đã được tối ưu sẵn, không lặp lại	⚠️ Lợi ích thấp
Bạn dùng nhiều tool AI khác nhau và muốn một bộ nhớ chung	✅ Cross-agent memory hữu ích
Cần zero-code, không muốn sửa app	✅ Dùng chế độ proxy

So với việc tự viết logic rút gọn context: headroom đã làm sẵn phần khó (nhận dạng loại nội dung, nén thông minh, lưu bản gốc để retrieve), bạn không cần tự xây.

---

🚀 Bắt đầu nhanh

Cài đặt

# Cách 1: Cài CLI đầy đủ (khuyên dùng cho Python)
pip install "headroom-ai[all]"

# Cách 2: Cài trong môi trường độc lập (dùng uv)
uv tool install --python 3.13 "headroom-ai[all]"

# Cách 3: TypeScript/Node.js (chỉ là thư viện, không có CLI)
npm install headroom-ai

Chọn chế độ sử dụng

Chế độ 1 — Wrap (bọc tool AI của bạn, dễ nhất):

headroom wrap claude      # bọc Claude Code
headroom wrap cursor      # bọc Cursor
headroom unwrap claude    # gỡ ra khi không cần nữa

Chế độ 2 — Proxy (zero code change, dùng cho mọi ngôn ngữ):

headroom proxy --port 8787
# Trỏ OPENAI_BASE_URL hoặc ANTHROPIC_BASE_URL về http://localhost:8787

Chế độ 3 — Dùng thẳng trong Python:

from headroom import compress
from openai import OpenAI

messages = [{"role": "user", "content": "Phân tích kết quả này: " + rat_nhieu_du_lieu}]

# Nén trước khi gửi
result = compress(messages, model="gpt-4o")

client = OpenAI()
response = client.chat.completions.create(
    model="gpt-4o",
    messages=result.messages   # <-- dùng messages đã nén
)

print(f"Đã tiết kiệm {result.tokens_saved} token ({result.compression_ratio:.0%})")

Kiểm tra hoạt động:

headroom doctor       # kiểm tra cấu hình
headroom dashboard    # xem số token tiết kiệm được theo thời gian thực
headroom savings      # đo tiết kiệm trên traffic thực của bạn

---

✅ Điểm mạnh & ⚠️ Hạn chế

✅ Điểm mạnh

• Tiết kiệm đáng kể: 20–57% cho coding agent, 60–95% cho JSON/log — đã có benchmark công khai, tái tạo được
• Không ảnh hưởng chất lượng: Độ chính xác trên GSM8K, SQuAD v2, TruthfulQA giữ nguyên hoặc tốt hơn
• Linh hoạt 4-in-1: Dùng được dưới dạng thư viện, proxy, MCP server, hoặc lệnh wrap
• Dữ liệu ở lại máy bạn: Nén hoàn toàn local, không gửi prompt ra ngoài
• Không đổi code nếu dùng proxy: Chỉ cần đổi base URL
• Bộ nhớ chéo agent: Dùng chung state giữa Claude, Codex, Gemini, Grok
• headroom learn: Tự học từ session cũ để sinh ra file CLAUDE.md, AGENTS.md… sửa lỗi agent hay gặp

⚠️ Hạn chế

• Lợi ích thấp với văn bản ngắn hoặc đã dày đặc — nếu bạn chỉ chat bình thường, headroom không giúp nhiều
• CLI chỉ có trên PyPI — gói npm headroom-ai là thư viện TypeScript thuần, không có lệnh headroom
• Output token reduction (nén phần model trả lời) cần bật thêm: export HEADROOM_OUTPUT_SHAPER=1
• Phụ thuộc vào model local (Kompress-v2-base) cho nén text — cần tải model về lần đầu
• Còn khá mới — cần đánh giá thêm trong môi trường production thực tế của từng team