Toolฟรี

Headroom – บีบอัด context ก่อนส่งให้ LLM ลดต้นทุน token ได้ 60–95%

เลเยอร์บีบอัด context สำหรับ AI agent ช่วยลด token ได้ 60–95% (JSON ใน tool call/API response) และ 15–20% (โค้ดไฟล์ .py/.ts/.js จาก TypeScript project benchmark) โดยคงคำตอบเหมือนเดิม แต่แลกมาด้วย latency เพิ่ม รองรับ library, proxy, agent wrapper, MCP server พร้อมบีบอัดแบบ reversible (CCR) เก็บต้นฉบับไว้ดึงกลับได้ ตัวอย่างจริง: ลดจาก 10,144→1,260 token (87.6%) ยังหา error ได้ครบ ไม่เหมาะกับ prompt สั้น <500 token

คัดมาจาก GitHub · อัปเดต 6 พ.ย. 2569

ดูโค้ดต้นทาง

GitHub

ส่วนประกอบ

agent · compression · local-first · cost-optimization · llm

Headroom คืออะไร

Headroom เป็นเลเยอร์บีบอัด context สำหรับ AI agent ที่ทำงานแบบ local-first ช่วยลด token ที่ส่งเข้า LLM ได้ 60–95% (สำหรับ JSON ในงาน tool call และ API response) และ 15–20% (สำหรับโค้ดไฟล์ .py/.ts/.js) โดยยังได้คำตอบเหมือนเดิม แต่ต้องแลกมาด้วย latency ที่เพิ่มขึ้นจากขั้นตอนบีบอัด/คลายข้อมูล รองรับการบีบอัดแบบ reversible (CCR) คือเก็บต้นฉบับไว้ดึงกลับมาได้ถ้า LLM ต้องการ

⚠️ ข้อควรระวัง: Headroom เหมาะกับ workload ที่มี JSON/log/repetitive text ขนาดใหญ่ ไม่แนะนำ สำหรับ prompt สั้นๆ (<500 token) หรือโค้ดที่ซับซ้อนต้องการ full context เพราะค่า overhead อาจมากกว่าประโยชน์

ทำไมต้องใช้

ลดต้นทุน token – ตัวอย่างจริง ลดจาก 10,144 เหลือ 1,260 token (ลด 87.6%) แต่ยังหา FATAL error ได้เหมือนเดิม
ใช้ง่าย – มี 4 รูปแบบ: library (compress(messages)), proxy (zero code change), agent wrapper, และ MCP server
Content-aware – แยก compressor ตามประเภท: SmartCrusher (JSON), CodeCompressor (AST), Kompress-v2-base (text)
Cross-agent memory – แชร์หน่วยความจำระหว่าง Claude, Codex, Gemini, Grok พร้อม auto-dedup
Local-first – ข้อมูลอยู่เครื่องคุณ ไม่ส่งออกไปไหน
Reversible (CCR) – เก็บต้นฉบับไว้ให้ดึงกลับได้ตามต้องการ

ตัวอย่างผลลัพธ์จริง (Before/After)

ก่อนบีบอัด (10,144 tokens):

{
  "timestamp": "2024-01-15T10:23:45Z",
  "level": "INFO",
  "message": "Request processed successfully",
  "user_id": "usr_12345",
  "duration_ms": 234,
  ...[repeats 500+ times]...
}

หลังบีบอัด SmartCrusher (1,260 tokens):

<compressed schema="{ts:ISO,lvl:str,msg:str,uid:str,dur:int}" count="500+" sample="2024-01-15T10:23:45Z|INFO|Request processed|usr_12345|234" />

→ LLM ยังตอบคำถาม "มี FATAL error ไหม" ได้ถูกต้องเหมือนเดิม

ข้อมูลเปรียบเทียบ Compressor

Compressor	Use Case	Compression Ratio	Speed	Quality Loss
SmartCrusher	JSON, logs, API response	60-95%	Fast (~50ms/10KB)	None (schema preserved)
CodeCompressor	Python/TS/JS code	15-20%	Medium (~200ms/10KB)	Minimal (AST-based)
Kompress-v2-base	Free text, markdown	30-50%	Slow (~500ms/10KB)	Low (semantic)

ตัวเลขจาก benchmark ใน repo: วัดจาก 1,000 real-world agent sessions (JSON-heavy workload สำหรับ SmartCrusher, TypeScript project สำหรับ CodeCompressor)

วิธีใช้งาน

ติดตั้ง

# แบบ CLI tool (แนะนำ)
uv tool install --python 3.13 "headroom-ai[all]"

# หรือ pip
pip install "headroom-ai[all]"

# TypeScript SDK
npm install headroom-ai

System Requirements:

Python ≥3.10 หรือ Node.js ≥18
RAM ≥2GB (สำหรับ Kompress-v2-base model)
ไม่รองรับ Windows ARM (ใช้ WSL แทน)

เริ่มใช้

แบบ Library (Python/TypeScript):

from headroom import compress
compressed = compress(messages)

แบบ Proxy (ไม่ต้องแก้โค้ด):

headroom proxy --port 8787
# ตั้งค่า agent ให้ชี้ที่ localhost:8787

แบบ Agent Wrapper (one-command):

# Wrap agent ที่ต้องการ
headroom wrap claude  # หรือ codex, grok, copilot, cursor, aider, cline, continue, goose, openhands ฯลฯ

# Undo
headroom unwrap claude

MCP Server (สำหรับ MCP client):

Tools: headroom_compress, headroom_retrieve, headroom_stats

ฟีเจอร์เสริม

headroom learn – วิเคราะห์ session ที่ล้มเหลว เขียน correction ลงไฟล์ CLAUDE.local.md (gitignored) หรือ CLAUDE.md / AGENTS.md / GEMINI.md / GROK.md
Output token reduction – ลด token ที่โมเดลเขียนกลับมา ตัดพิธีรีตัว, โค้ดที่ repeat และ reasoning ที่ไม่จำเป็น
CacheAligner – ปรับ prefix ให้ provider KV cache ทำงานได้ดีขึ้น

วิธีทำงาน

Agent/app ส่ง prompt, tool output, logs, RAG, files
Headroom (local) บีบอัดด้วย ContentRouter → เลือก compressor ที่เหมาะสม (SmartCrusher/CodeCompressor/Kompress-v2-base)
ส่ง compressed prompt + retrieval tool ให้ LLM
ถ้า LLM ต้องการต้นฉบับ เรียก headroom_retrieve (CCR)

รองรับทุก agent framework: LangChain, Agno, Strands และ agent ยอดนิยมอย่าง Claude Code, Cursor, Codex, Aider, Cline, Continue, Goose, OpenHands, Grok, Copilot, OpenCode, OpenClaw, Vibe, OMP, ZCode ฯลฯ