Headroom: nén context cho AI agent, giảm token

Vấn đề: vì sao session agent càng dài càng tốn token

Dùng coding agent một buổi là thấy ngay: mỗi lần agent chạy lệnh, đọc file, tra cứu code, toàn bộ output lại được gửi kèm vào prompt tiếp theo. Log build vài nghìn dòng, kết quả tìm kiếm code hàng trăm mục — tất cả đều tính token, và phần lớn là nội dung lặp lại: cùng một khung JSON, cùng một dòng log, cùng một đoạn boilerplate.

Cắt bớt thì sợ mất đúng dòng quan trọng. Giữ nguyên thì hóa đơn token phình lên và context window nhanh đầy. Compaction của riêng từng agent có giúp, nhưng nó là tính năng của từng hãng, không đi theo bạn khi đổi agent, và bạn khó kiểm soát nó nén cái gì.

Headroom đi vào đúng khe hở này: một lớp nén độc lập, chạy trên máy của bạn, đặt giữa agent và LLM. Nó không thay agent, không thay model — nó chỉ làm cho thứ agent đọc gọn hơn trước khi gửi đi.

Headroom là gì?

DỮ KIỆN TỪ REPO: Headroom là dự án mã nguồn mở, giấy phép Apache 2.0, tại headroomlabs-ai/headroom (trước đây là chopratejas/headroom, đường dẫn cũ vẫn chuyển hướng tới repo mới). Theo README, Headroom nén mọi thứ agent AI đọc — tool output, log, RAG chunk, file và lịch sử hội thoại — trước khi tới LLM. Việc nén chạy trên máy người dùng; README khẳng định không có nội dung prompt hay file nào được gửi đi nơi khác chỉ để nén.

ĐÁNH GIÁ CÁ NHÂN: Điểm đáng tiền nhất không phải tỉ lệ nén, mà là tính độc lập: một lớp duy nhất dùng chung cho nhiều agent.

Headroom nén như thế nào?

ContentRouter và 3 bộ nén

Luồng đi qua Headroom có thể hình dung như sau: agent gửi prompt, tool output, log và file vào; Headroom nhận, phân loại rồi nén; LLM chỉ nhận bản đã nén cộng một công cụ để lấy lại bản gốc khi cần.

• ContentRouter phát hiện loại nội dung và chọn bộ nén phù hợp, thay vì áp một kiểu nén cho mọi thứ.
• SmartCrusher xử lý JSON: gộp các mảng lặp, rút gọn cấu trúc lặp lại mà vẫn giữ đủ thông tin.
• CodeCompressor nén code theo AST cho Python, JS/TS, Go, Rust, Java, C/C++, C#, PHP — tức là hiểu cấu trúc code chứ không chỉ cắt chuỗi ký tự.
• Kompress-v2-base là model nén văn bản cho phần còn lại, chạy local.

CCR — nén nhưng lấy lại được bản gốc

Đây là chi tiết quyết định Headroom có dùng được trong công việc thật hay không. CCR (bộ nhớ đệm nội dung gốc) lưu bản gốc ngay trên máy của bạn. Khi model thấy bản nén thiếu chi tiết cần thiết, nó gọi headroom_retrieve để lấy lại đúng đoạn gốc. Bản gốc vẫn có thể lấy lại trong khoảng TTL đã cấu hình, theo README — README không công bố một giá trị TTL cụ thể, nên đừng suy ra con số này từ nơi khác.

Nói cách khác, Headroom giấu phần thừa đi và để cửa mở cho model quay lại lấy khi cần.

CacheAligner và prompt cache

Nếu mỗi lần nén ra một prefix khác nhau, prompt cache của nhà cung cấp sẽ trượt liên tục. CacheAligner đánh dấu nội dung dễ thay đổi có thể phá vỡ prefix KV-cache, nhưng theo README nó không viết lại prompt của bạn — chi tiết đáng giá với session dài, nơi cache hit ảnh hưởng trực tiếp tới chi phí.

ĐÁNH GIÁ CÁ NHÂN: Thiết kế “nén + giữ bản gốc + giữ cache” cho thấy tác giả đã chạy agent thật với hóa đơn thật. Nhưng thiết kế hay vẫn phải đo trên lưu lượng của chính bạn.

Con số của dự án nói gì — và đọc chúng ra sao

LƯU Ý MINH BẠCH: Bài này tổng hợp và đối chiếu từ README và tài liệu chính thức của dự án, chưa trình bày kết quả chạy thực tế của tác giả. Mọi con số dưới đây đều là số liệu do dự án công bố, không phải số đo độc lập.

Demo log: 10.144 xuống 1.260 token

Ảnh demo đầu README cho thấy một log dump 10.144 token được nén còn 1.260 token, và dòng FATAL vẫn được tìm thấy nguyên vẹn — trường hợp log lặp nhiều, không phải mức trung bình.

Bảng Proof: 4 kịch bản đo bằng tokenizer của provider

README công bố phương pháp đo: 4 kịch bản dựng từ định dạng output thật của MCP server, đo bằng tokenizer của provider và hàm compress() đi kèm, có seed cố định để tái lập. Kết quả:

README cũng nói rõ quy luật: tiết kiệm tăng theo độ lặp của payload. Mảng JSON lặp và dòng log lặp có thể vượt 90% trong benchmark độ trễ của dự án; văn xuôi và output đã dày đặc thì nén rất ít. Độ trễ nén theo README là dưới 1 mili-giây trong phần lớn trường hợp: 0,21 ms ở phân vị 50 cho kết quả tìm kiếm JSON 10K token, 1,4 ms ở 100K token — tức là chi phí nén gần như không hiện ra trong độ trễ của agent.

Mô tả tổng thể của repo tóm tắt: giảm khoảng 20% token cho coding agent, 60–95% cho JSON. Đừng đọc đó như cam kết cho mọi session; đó là hai đầu của phổ: JSON lặp nén rất sâu, session code thực tế nén vừa phải.

Độ chính xác: đừng đọc quá mức

README chạy bộ đánh giá với lệnh python -m headroom.evals suite --tier 1, mỗi benchmark 100 mẫu. GSM8K giữ nguyên 0,870; TruthfulQA tăng từ 0,530 lên 0,560 nhưng chính README cảnh báo: với N = 100, mức chênh 0,03 nằm trong khoảng tin cậy, nên không thể kết luận là cải thiện. SQuAD v2 và BFCL đạt 97% ở mức nén lần lượt 19% và 32%.

ĐÁNH GIÁ CÁ NHÂN: Cách dự án tự hạ thấp kết quả TruthfulQA của chính mình là tín hiệu tốt về độ tin cậy. Một dự án chỉ khoe số đẹp mà giấu khoảng tin cậy thì không đáng tin bằng một dự án nói rõ đâu là nhiễu thống kê.

Cài đặt Headroom

Yêu cầu: Python 3.10 trở lên. Khuyến nghị dùng uv để CLI nằm trong môi trường ứng dụng riêng, tránh xung đột với Python hệ thống:

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

Hoặc dùng pip nếu bạn đã quen quản lý môi trường Python:

pip install "headroom-ai[all]"

Kiểm tra CLI đã vào PATH chưa:

headroom --version

Bẫy tên package: npm không có CLI

Đây là lỗi dễ mắc nhất khi cài Headroom. Gói npm headroom-ai chỉ là TypeScript SDK — một thư viện để import, không cung cấp lệnh headroom. CLI chỉ đi kèm gói PyPI. Nếu bạn cài bằng npm rồi gõ headroom mà báo không tìm thấy lệnh, đó không phải lỗi — đó là bạn đã cài nhầm dạng gói cho nhu cầu dùng CLI.

Gói [all] bao phủ lõi nhưng không bao gồm adapter framework; ví dụ dùng LangChain thì cài thêm riêng headroom-ai[langchain], tương tự cho Agno, Strands, Bedrock. Người cần chạy bằng container có thể lấy image ghcr.io/headroomlabs-ai/headroom:latest.

MẸO DÙNG AI: Đừng vội bật cho mọi project. Bật cho một project nặng log nhất, đo một tuần bằng headroom savings rồi mới nhân rộng.

4 cách dùng thực tế

1. Wrap agent — cách nhanh nhất để bắt đầu

headroom wrap claude

Lệnh này khởi động proxy local, cấu hình agent đi qua proxy đó rồi mở agent lên; mỗi session đã wrap cần chạy lại lệnh. Hoàn tác bằng:

headroom unwrap claude

Danh sách wrap gồm Claude Code, Codex, Grok CLI, Copilot CLI, Aider, OpenCode, Cline, Continue, Goose, OpenHands, OpenClaw, Mistral Vibe, Oh My Pi, Kimi CLI, ZCode và Cursor — nhưng cần đọc kỹ hai ngoại lệ ở phần lưu ý: Cursor chỉ là thiết lập thủ công, Cortex Code chỉ dùng dạng thư viện.

2. Proxy — không đổi code, dùng cho mọi client

headroom proxy --port 8787

Chế độ này phù hợp khi bạn có app riêng hoặc client tương thích OpenAI: trỏ base URL về proxy local, mọi request đi qua nén mà không sửa code.

3. Thư viện — nhúng vào app Python hoặc TypeScript

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%})")

Dạng thư viện cho bạn kiểm soát từng lần gọi: chỉ nén message thực sự nặng và đo tokens_before, tokens_after ngay trong code.

4. MCP server và headroom learn

Headroom cung cấp MCP server với ba công cụ headroom_compress, headroom_retrieve và headroom_stats, cài bằng headroom mcp install.

Riêng headroom learn khai thác session thất bại và ghi bài học vào CLAUDE.local.md (đã gitignore) hoặc CLAUDE.md, AGENTS.md, GEMINI.md nếu bạn chỉ định.

Kiểm chứng sau khi bật

Hãy đo của mình:

headroom doctor
headroom perf
headroom dashboard

• headroom doctor xác nhận routing đã đúng; headroom perf đo hiệu năng nén; headroom dashboard hiển thị tiết kiệm trực tiếp khi proxy đang chạy; headroom savings đo trên chính lưu lượng của bạn — đây mới là con số để quyết định giữ hay gỡ.

Ngoài ra còn có tính năng giảm token đầu ra: Headroom rút gọn phần model viết lại bằng ghi chú “viết ngắn gọn, đừng nhắc lại context” ở cuối system prompt để không phá cache. Tính năng này tắt mặc định, bật bằng HEADROOM_OUTPUT_SHAPER=1, và số tiết kiệm mà headroom output-savings báo cáo được gắn nhãn là ước tính kèm khoảng tin cậy — vì không ai biết model “đáng lẽ” đã viết bao nhiêu. Muốn số đo, giữ 10% hội thoại làm đối chứng bằng HEADROOM_OUTPUT_HOLDOUT=0.1.

Ưu điểm và nhược điểm

Ưu điểm: chạy local, không gửi prompt hay file đi nơi khác chỉ để nén; nén có thể đảo ngược qua CCR; một lớp dùng chung nhiều agent; không sửa code ở dạng proxy; hoàn tác sạch bằng unwrap; tự công bố giới hạn và khoảng tin cậy của benchmark.

Nhược điểm và giới hạn: văn xuôi, output đã dày đặc và hội thoại ngắn gần như không tiết kiệm được gì; thêm một proxy local là thêm điểm lỗi cần giám sát; beacon ẩn danh bật mặc định; wrap cài kèm Serena nếu bạn không chủ động tắt; Cursor và Cortex không được wrap đầy đủ như các agent còn lại.

So sánh: Headroom với các cách khác

ĐÁNH GIÁ CÁ NHÂN: Nếu bạn chỉ dùng một agent và đã hài lòng với compaction của nó, Headroom là thừa. Headroom đáng tiền khi bạn dùng nhiều agent hoặc chạy session dài với log nặng.

Use-case thực tế cho sysadmin và developer

• Debug sự cố production: log incident dài, stack trace lặp, output monitoring — đúng loại payload mà bảng Proof cho thấy tiết kiệm tới 57%. Đây là use-case đầu tiên nên thử.
• Tìm kiếm và khám phá codebase: hàng trăm kết quả tìm kiếm code có cấu trúc lặp — nén tốt mà vẫn giữ tên hàm, file và dòng quan trọng.
• Phân loại issue và triage: template, log đính kèm, bình luận lặp — giảm token mà không mất ngữ cảnh issue.
• Chạy nhiều agent song song: một lớp nén chung giúp so sánh chi phí giữa Claude Code, Codex hay OpenCode trên cùng một thước đo.

Bài toán này liên quan tới hai công cụ đã có trên blog: XERJ giúp agent tìm đúng tài liệu local thay vì đọc cả codebase, còn Graphify biến codebase thành knowledge graph để truy vấn. XERJ và Graphify giảm lượng dữ liệu agent phải đọc ngay từ đầu; Headroom giảm token của lượng dữ liệu đã đọc đó trước khi gửi đi.

Bảo mật và những lưu ý không được bỏ qua

Beacon ẩn danh bật mặc định

README nêu rõ: beacon ẩn danh bật mặc định, báo cáo tỉ lệ nén, bộ đếm, ID provider và model, hệ điều hành và kiến trúc. Nó không gửi prompt, completion, code hay đường dẫn file. Dù vậy, nếu môi trường của bạn cấm mọi telemetry đi ra ngoài, hãy tắt ngay từ đầu bằng một trong các cách: HEADROOM_BEACON=off, HEADROOM_TELEMETRY=off, quy ước DO_NOT_TRACK=1, hoặc HEADROOM_OFFLINE=1.

Wrap cài kèm Serena — kiểm tra trước khi đồng ý

headroom wrap không chỉ bật proxy; nó còn cài Serena, MCP server điều hướng code theo ngữ nghĩa. Với Claude Code, Serena chỉ đăng ký cho project đã wrap, dưới dạng MCP server phạm vi local trong ~/.claude.json. Muốn dùng cho mọi project thì thêm --code-memory-scope user; muốn bỏ qua thì thêm --code-memory none. headroom unwrap gỡ cả hai dạng đăng ký.

Upstream mặc định khi dùng OpenAI-compatible

Đây là lưu ý quan trọng nhất cho người dùng OpenCode với provider bên thứ ba. headroom wrap định tuyến lưu lượng OpenAI-compatible tới upstream mặc định là https://api.openai.com/v1. Nếu bạn dùng DeepSeek, Together, OpenRouter hay gateway tự host mà không chỉ định upstream, key có thể bị gửi tới OpenAI và nhận lỗi 401 Incorrect API key provided. Cách đúng: truyền --openai-api-url https://api.deepseek.com/v1 hoặc đặt OPENAI_TARGET_API_URL trước khi wrap.

Cursor và Cortex không giống các agent còn lại

Cursor với Headroom chỉ là thiết lập thủ công: Headroom khởi động proxy và in ra base URL để bạn tự điền vào cài đặt Cursor. Cortex Code chỉ dùng được dạng thư viện, không có wrap, với mức tiết kiệm trong chế độ library mà README ghi là 60–65%. Nếu bài viết nào đó nói “wrap mọi agent chỉ bằng một lệnh” mà không nhắc hai ngoại lệ này, thì bài đó đang đơn giản hóa quá mức.

Đừng nhầm với headroom-desktop

Trên GitHub còn có repo headroom-desktop: ứng dụng tray với mô hình trả phí riêng, không phải dự án mã nguồn mở trong bài này. Khi cài đặt, hãy kiểm tra đúng repo và đúng gói PyPI headroom-ai.

Vì Headroom cho agent chạy proxy local và đọc output của bạn, hãy rà soát xem agent có thể chạm tới những credential nào. Bài Heldkeys hướng dẫn liệt kê đúng thứ đó trước khi mở rộng quyền cho agent.

Khi nào không nên dùng Headroom

README tự nêu hai trường hợp nên bỏ qua: bạn chỉ dùng compaction sẵn có của một provider và không cần bộ nhớ cross-agent, hoặc bạn làm việc trong sandbox mà tiến trình local không chạy được. Hội thoại ngắn, văn xuôi thuần túy và payload đã nén sẵn cũng không mang lại lợi ích đáng kể.

Kết luận và khuyến nghị

Headroom không phải phép màu làm token biến mất. Nó là một lớp kỹ thuật nghiêm túc cho một vấn đề có thật: agent đọc quá nhiều, lặp quá nhiều, và bạn trả tiền cho phần lặp đó. Thiết kế nén có thể đảo ngược, chạy local và dùng chung nhiều agent là ba lý do chính đáng để thử — với điều kiện bạn đo trên lưu lượng của mình, tắt beacon nếu cần, kiểm tra Serena đi kèm và xác nhận upstream trước khi dùng provider bên thứ ba.

Cách thử an toàn nhất: cài bằng uv, wrap một agent trên một project log nặng, chạy headroom doctor rồi headroom savings sau vài ngày, và chỉ giữ lại nếu con số của bạn — không phải con số của README — chứng minh nó đáng giữ.