AgentIndex icon
AgentIndex
ToolsMCP ServersHOTCategoriesTrendingNewBest ListsCompareGuides
Submit Tool
ToolsMCP ServersHOTCategoriesTrendingNewBest ListsCompareGuides
Home/
Memory & Context/
Headroom
Headroom logo

Headroom

Active·★ 79.2k·Apache-2.0·Updated 2026-11-10
★ Most Popular★ Essential

Headroom is a local context-compression layer for tool outputs, logs and structured data. Its Python library can shorten representations before a separate model call, while optional MCP and proxy integrations expose other entry points. Default compression and the verified lossless agent mode have different retention behavior.

On November 7, 2026, we ran 18 library cases and 12 real stdio MCP tool calls with published version 0.43.1. Repetitive logs and uniform arrays shrank, selected structured outputs decoded to exact canonical JSON, and a dedicated SQLite workspace recovered original Unicode content after process restart. A compact sample of 80 real catalog records saved nothing in either mode, while lossless mode returned an unshortened log.

The release requires Python 3.11+. Our tested environment used x86_64 Python 3.13.1 on macOS and a binary-only dependency install after a native-build failure. Tokenizer vocabularies were prepared separately, the ML compressor was disabled, and runtime used offline settings. We did not measure model answers, provider bills, prompt-cache savings, agent wrapping or TypeScript integration; recoverability depends on the backend and entry lifetime.

Read the full review, verification scope and sources →

Hands-on tested · Tested on 2026-11-07 with headroom-ai 0.43.1; tiktoken 0.14.0; MCP SDK 2.3.0.

Setup: macOS 26.6.2, Apple M1 Pro, x86_64 Python 3.13.1. Published macOS x86_64 wheel, fixed dependency lock, offline runtime and ML disabled. Artificial logs/arrays plus frozen public AgentIndex catalog and article; no model/provider requests.

Commands run

python -m pip install --only-binary=:all: -r requirements-lock.txt
python -m pip check
python prepare_tokenizers.py <tokenizer-cache>
python verify_headroom.py <empty-work-dir> <tokenizer-cache> <results.json>

What we saw

  • 18 library runs and 12 real MCP calls across four server processes. Selected JSON decoded to exact canonical data, covering type edges and all 80 real catalog records.
  • Content-token counts: uniform formatted JSON 20,514→5,029 by default; the same minified array 11,015→5,031. Already minified real catalog data 4,501→4,501 in both modes after inflation-guard fallback.
  • Default logs retained the tested FATAL/Chinese/traceback markers, 15,022→109 content tokens. Lossless mode restored all 15,022 and reported one reverted message. ML-disabled explanatory prose did not shrink.
  • MCP original retrieval matched exact Unicode bytes and survived restart with default SQLite. An explicit memory backend missed after restart. A separate one-second store TTL expired after 1.2 seconds; MCP one-hour expiry was not waited out.
  • Unknown hashes and empty content returned JSON error fields with protocol isError=false. Five Python socket audits recorded no TCP attempts. No model-answer equivalence, provider billing, prompt-cache savings, proxy wrapping or TypeScript behavior was measured.

Data as of 2026-11-07.

License
Apache-2.0
Latest release
v0.43.1 · 2026-11-05
Last commit
2026-11-07
Contributors
399
Forks
6,180
Open issues and PRs
288
First published
2026-01-07
npm package
headroom-ai 0.43.1 · 34,610 downloads last week

Source: GitHub, npm and PyPI public APIs.

#Context Compression#Token Optimization#AI Agents#LLM Integration#Local-first#Reversible#Proxy#Developer Tooling
$ Install
$ python -m pip install --only-binary=:all: "headroom-ai[mcp]==0.43.1"
↗ Visit site★ GitHub
01

Features

01Local Python compression and verified lossless agent mode
02Content routing, final token counts and compression diagnostics
03MCP compression, original retrieval and statistics tools
04SQLite-backed originals with configurable storage and entry lifetimes
02

Why choose it

+Selected structured outputs round-tripped exactly, including typed edge cases and all 80 real catalog records; uniform JSON still shrank beyond simple minification.
+Lossless mode restored the original log when its shorter form failed verification, exposing the final result and a revert count.
+All three standard MCP tools were exercised; SQLite-backed original retrieval survived a second process and preserved exact Unicode bytes.
03

Trade-offs

!Already minified real catalog data saved nothing in either mode, and the explanatory article stayed unchanged with ML disabled.
!Default log compression omitted information, while lossless fallback eliminated its savings. Neither token reduction nor recoverability establishes equal model answers.
!Original retrieval depends on storage and TTL; the memory backend lost its entry across restart. Unknown hashes and empty content returned JSON errors with isError=false.
05

Maintenance check

ActiveChecked: 2026-11-04
Last commit
2026-11-04
Commits, last 90 days
100+
Releases, last 90 days
14
Latest release
v0.42.0 (2026-10-26)
Open issues
392
Recent issues with at least one comment
2/7
Commits per week, last 12 weeks
Commits per week, last 12 weeks: 77, 32, 30, 46, 24, 134, 141, 180, 54, 59, 61, 90

Oldest week on the left; the latest four weeks are orange. Source: GitHub commit activity.

Status rule: archived on GitHub = Archived; last commit within 90 days = Active; 91 to 365 days = Slowing; older = Stale. All figures come from the GitHub API on the date shown.

04

Who it fits

Pick it if
  • Your actual serialized tool output contains repetitive logs or uniform arrays, and you can compare both compression modes against minified baselines.
  • You can retain originals in an appropriate backend, inspect application-level errors and verify the data needed by your task.
Look elsewhere if
  • You require demonstrated answer equivalence or a guaranteed billing reduction; this offline review measured neither.
  • Your payloads are already compact heterogeneous JSON, or you require permanent recovery from an in-memory session; our controls exposed limits in those cases.
06

How it differs

ref-tools-mcp logovs ref-tools-mcp★ 1.2k

Ref trims documentation it fetches from its hosted index. Headroom processes supplied content locally; this review tested logs and structured tool results.

Full comparison →
jcodemunch-mcp logovs jcodemunch-mcp★ 2.8k

jCodeMunch avoids reading whole code files by fetching symbols. Headroom compresses tool output, logs and JSON after they are produced.

Full comparison →
07

Compatibility

Python 3.11+
Tested 3.13.1 x86_64
Verified via docs
macOS
Tested library and MCP
Verified via docs
stdio MCP
SDK 2.3.0 verified
Verified via docs
Linux / Windows
Published wheels; untested
Verified via docs
TypeScript
Proxy integration; untested
Verified via docs
08

Quick start

1
$ python -m pip install --only-binary=:all: "headroom-ai[mcp]==0.43.1"
09

Use cases

↳Compare context representations for real API results and logs before a model call
↳Validate exact structured-data recovery and conservative lossless fallback
↳Expose local compress/retrieve tools with tested storage and restart behavior
10

Alternatives

⚡Top VS:
VSjcodemunch-mcp★2.8k→VSref-tools-mcp★1.2k→VSCopilotKit★38.6k→
jcodemunch-mcp logo
jcodemunch-mcp★ 2.8k
Cut AI token costs 95%+ on code exploration. The leading MCP server for precise, symbol-level GitHub code retrieval via tree-sitter AST. Works with Claude Code, Cursor & any MCP client. 313B+ tokens saved.
VSCompare→
ref-tools-mcp logo
ref-tools-mcp★ 1.2k
Helping coding agents never make mistakes working with public or private libraries without wasting the context window.
VSCompare→
projectmem logo
projectmem★ 879
Local-first AI coding memory for AI agents. Records issues, attempts, fixes and decisions, then warns your agent before it repeats an approach that already failed. Native MCP server for Claude Code, Cursor, Antigravity and Codex. 100% local, no cloud, no telemetry. MIT.
caura logo
caura★ 553
Caura (formerly MemClaw) — governed shared memory for AI agent fleets. Multi-agent, multi-tenant, MCP-native. Trust tiers, keystone policies, audit trails, knowledge graph, self-improving retrieval. Apache 2.0.
engrim logo
engrim★ 305
The Universal Cross-Model Episodic Memory Standard. Local-first, project-scoped SQLite engine for Google Antigravity, Claude Code, Cursor, Codex CLI, and OpenCode. Zero cloud lock-in.
mcp-local-memory logo
mcp-local-memory★ 62
A lightweight, powerful local memory server for AI agents supporting text, entities, and relations. Enables persistent codebase understanding and user preference management.
fava-trails logo
fava-trails★ 26
🫛👣 FAVA Trails — Git-native, curated memory for AI agents via MCP. Draft isolation, promotion gate, thought lifecycle hooks, memory curation protocols, supersession chains.
CopilotKit logo
CopilotKit★ 38.6k
React UI + elegant infrastructure for AI Copilots, AI chatbots, and in-app AI agents. The Agentic Frontend.
VSCompare→
See all alternatives →

Featured in these lists

  • Best Memory Tools for AI Agents and Coding Assistants
  • Best MCP Servers for Up-to-Date Docs and Code Context

Comments

Log in to leave a comment

No comments yet. Be the first!

On this page
01Features02Why choose it03Trade-offs05Maintenance check04Who it fits06How it differs07Compatibility08Quick start09Use cases10Alternatives
headroomlabs-ai /
headroom
↗

Local context compression with lossless verification and original retrieval

79.2k6.2kApache-2.0
Last commit1d ago
StatusActive
CategoryMemory & Context
Contributors399
Latest releasev0.43.1
Links
Documentation↗Discussion↗Issues↗Releases↗
Cloud Infrastructure
Ad

Deploy on DigitalOcean

Host your MCP servers, Docker containers, and AI agents with $200 free credit over 60 days.

Claim $200 Free Credit
© 2026 AgentIndex.app|Built by a 10-year iOS Developer.
Best by use caseAboutContactAdvertisePrivacy PolicyTerms of UseQYSGitHubBuy me a coffee ☕

Browse by Category

MCP ServersCode AssistantWorkflow AutomationRAG / Knowledge BaseMulti-AgentBrowser AutomationLLM InfraDev ToolingObservability

Not affiliated with Anthropic, OpenAI or Microsoft.