# Compress Memory Files

Compresses a memory file like CLAUDE.md into terse form and keeps a readable backup.

- Repository: https://github.com/JuliusBrussee/caveman (116680 stars)
- Category: AI and agents
- License: Apache-2.0
- Last updated: 2026-11-01
- Runs scripts: yes, review before use

## Install

Claude Code: `npx skills add JuliusBrussee/caveman --skill caveman-compress -g -a claude-code -y`
Codex: `npx skills add JuliusBrussee/caveman --skill caveman-compress -g -a codex -y`
Cursor: `npx skills add JuliusBrussee/caveman --skill caveman-compress -g -a cursor -y`
Gemini CLI: `npx skills add JuliusBrussee/caveman --skill caveman-compress -g -a gemini-cli -y`
Claude Code plugin marketplace: `/plugin marketplace add JuliusBrussee/caveman`

## Description

Compress a memory file such as CLAUDE.md or a todo list into caveman format to save input tokens, keeping a readable backup. Sends the file's text to the configured model provider. Trigger: /caveman-compress.

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

# Caveman Compress

## Purpose

> **Data leaves the machine.** Compression sends the file's full text to the model provider that `scripts/compress.py` is configured for: the `claude` CLI, the Anthropic API, or an OpenAI-compatible endpoint. Files whose names look like secrets (`.env`, `credentials`, `secrets`, `.netrc`, …) are refused before they are read. Don't compress a file the provider shouldn't see.

Compress natural language files (CLAUDE.md, todos, preferences) into caveman-speak to reduce input tokens. Compressed version overwrites original. Human-readable backup saved as `<filename>.original.md`, but NOT beside the source file, it lives in an out-of-tree data dir (`$XDG_DATA_HOME/caveman-compress/backups/<parent-dir-name>/`, or `%LOCALAPPDATA%\caveman-compress\backups\<parent-dir-name>\` on Windows) so skill auto-loaders don't re-ingest it as a live file.

## Trigger

`/caveman-compress <filepath>` or when user asks to compress a memory file.

**Requires an explicit filepath.** If the user pastes raw text instead of naming a file, do NOT improvise an inline compression, ask them for the filepath to compress, or offer to save the pasted text to a file first. Writing your own reasoning/commentary about the request into the compressed output (e.g. "User passed text directly, not a filepath...") is the exact failure this guards against, never let that leak into a saved file.

## Process

1. The compression scripts live in `scripts/` (adjacent to this SKILL.md). If the path is not immediately available, search for `scripts/__main__.py` next to this SKILL.md.

2. From the directory containing this SKILL.md, run:

python3 -m scripts <absolute_filepath>

3. The CLI will:
- detect file type (no tokens)
- call Claude to compress
- validate output (no tokens)
- if errors: cherry-pick fix with Claude (targeted fixes only, no recompression)
- retry up to 2 times
- if still failing after 2 retries: report error to user, leave original file untouched

The rest: https://github.com/JuliusBrussee/caveman/blob/HEAD/plugins/caveman/skills/caveman-compress/SKILL.md