UltraTokenStack

UltraTokenStack configures the official Mem0, Headroom, and Caveman integrations as one coding-agent workflow.

headroom wrap codex|claude
    ├─ Headroom compresses context and tool output before the model sees it
    ├─ Mem0 plugin hooks retrieve memory before prompts and save learnings after work
    └─ Caveman skill directs the agent to emit terse prose with code unchanged

Features

• One command configures the official integrations for Codex or Claude Code.
• Official Mem0 plugin and lifecycle hooks for automatic persistent memory.
• Official Headroom wrapper for provider-safe context compression.
• Official Caveman skill for terse agent-generated prose.
• JSONL token-savings metrics, unit tests, CI, and Docker Compose support.

Installation

Python 3.10+, Node.js/npm, Docker, and Git are required. On Windows run:

Set-ExecutionPolicy -Scope Process Bypass
.\scripts\install_windows.ps1

On macOS or Linux:

chmod +x scripts/*.sh
./scripts/install_linux.sh       # macOS: ./scripts/install_macos.sh

The installers use the official Headroom Python package, install Mem0 from its Git repository, install the Caveman npm package, start Mem0's official Docker stack, and launch headroom proxy --port 7007. See installation.md for details.

Usage

python -m src.pipeline.orchestrator "Summarize this tool output" --agent codex

Or call an integration directly:

from src.agents.codex import process_message

print(process_message("Explain this failing test."))

For the real agent workflow, follow the Codex quick start. scripts/run_all.* and the Python adapters remain useful for app-level experimentation, but they are not the recommended way to configure an interactive coding agent.

For containers, run the platform installer once to clone Mem0, then use docker compose up -d headroom and docker compose --profile cli run --rm pipeline "your message". See agent integration for wiring individual tools.

Token savings

Headroom reports typical reductions of 60–95% for JSON-heavy material and 15–20% for coding agents. Actual savings depend on content, model, cache behavior, and compression configuration; measure them in your own workloads with Headroom's dashboard and headroom perf.

Contributing

Keep pipeline stages independent, preserve graceful fallbacks, add docstrings to public functions, and never mutate fenced code in the Caveman stage. Run python -m compileall src before opening a pull request.

License

MIT. See LICENSE.