---
name: headroom
version: 1.0.0
description: "Use Headroom context compression and cross-agent memory for every Research Stack session." 
trigger_patterns:
  - "Research Stack"
  - "headroom"
  - "compress"
  - "context"
  - "memory"
  - "AGENTS.md"
  - "lean"
  - "Semantics"
  - "Q16_16"
  - "BraidStorm"
  - "RRC"
  - "PIST"
  - "Finsler"
  - "compression"
  - "token"
  - "receipt"
  - "capability"
  - "probe"
platforms: [linux, macos, windows]
metadata:
  priority: high
---

# Headroom skill — auto-loaded for Research Stack

Every Research Stack session should use Headroom for context compression and
shared memory. The Headroom MCP server is registered in `.mcp.json` as
`headroom` and exposes `headroom_compress`, `headroom_retrieve`, and
`headroom_stats`.

## When to compress

- Before sending long tool outputs (lake build logs, grep results, diffs) to
the user or to another model.
- When conversation history exceeds ~50k tokens.
- Before storing a receipt, decision, or lesson in ContextStream / ENE.

## How to use the MCP tools

1. `headroom_compress` — pass raw text; receive compressed text + a retrieval key.
2. Send the compressed text onward (to user, to LLM, to ContextStream).
3. If the consumer needs the original, call `headroom_retrieve` with the key.

## Cross-agent memory

Headroom shares a local store across Claude Code, Codex, Cursor, and OpenCode.
When you capture a decision or lesson, consider compressing the rationale with
`headroom_compress` before writing it to ContextStream, then store the retrieval
key in the memory entry.

## Learning from failures

`headroom learn --project . --apply` mines recent failed sessions and writes
corrections to the nearest AGENTS.md. Run it after a debugging or proof session
that surfaced a recurring mistake.

## Constraints

- Do not compress secrets or API keys.
- Do not treat compressed text as the source of truth; always keep the retrieval
key alongside it.
- Headroom is a compression layer, not a decision layer. Lean still owns formal
and routing decisions.