Research-Stack/.opencode/skills/headroom/SKILL.md

name	version	description	trigger_patterns	platforms	metadata
headroom	1.0.0	Use Headroom context compression and cross-agent memory for every Research Stack session.	Research Stack headroom compress context memory AGENTS.md lean Semantics Q16_16 BraidStorm RRC PIST Finsler compression token receipt capability probe	linux macos windows	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.