memory-compress

name

memory-compress

description

Compress natural language memory/doc files (.dev-squad/memory.md, gotchas.md, record.md, CLAUDE.md, or any project markdown) into lakonik-style dense prose to cut the INPUT-token cost of re-reading them every time they're injected. Preserves code blocks, URLs, paths, commands, and structure exactly. Compressed version overwrites the original; a full backup is kept outside the repo so it survives cleanup. Trigger: "/dev-squad memory-compress <filepath>" or "compress this memory file" / "compress gotchas.md".

Memory Compress

Adapted from JuliusBrussee/caveman (MIT License), plugins/caveman/skills/caveman-compress. Retargeted from "caveman-speak" to dev-squad's own dev-squad:lakonik compression rules, so a file compressed by this skill reads in the same register as an agent running in lakonik mode — one compression philosophy, applied to both live narration and static files.

Why this exists

hooks/inject-workflow-state.sh caps .dev-squad/{memory,gotchas,record}.md by line count (tail -N, shipped v4.41.0) to stop unbounded growth. That controls how many lines get shown on every SubagentStart — it does nothing about how many tokens each of those lines costs. Compressing the prose itself (same rules as dev-squad:lakonik) shrinks the per-line cost too, compounding with the line cap already in place. Same token-saving lever as lakonik, applied to files instead of live conversation.

Trigger

/dev-squad memory-compress <filepath> or when the user asks to compress a memory/doc 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 — pure heuristic)
   • refuse files that look like they hold secrets/credentials, or are too large (>500KB)
   • call Claude to compress (headless claude --print subprocess, or the anthropic SDK if ANTHROPIC_API_KEY is set — see Notes)
   • validate output (no tokens — structural diff only)
   • 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, restore the original untouched

4. Return result to user.

Compression Rules

Same rules as dev-squad:lakonik (full intensity), applied to file prose instead of conversation:

Remove

• Articles: a, an, the
• Filler: just, really, basically, actually, simply, essentially, generally
• Pleasantries: "sure", "certainly", "of course", "happy to", "I'd recommend"
• Hedging: "it might be worth", "you could consider", "it would be good to"
• Redundant phrasing: "in order to" → "to", "make sure to" → "ensure", "the reason is because" → "because"
• Connective fluff: "however", "furthermore", "additionally", "in addition"

Preserve EXACTLY (never modify)

• Code blocks (fenced ``` and indented)
• Inline code (backtick content)
• URLs and links (full URLs, markdown links)
• File paths (/src/components/..., .dev-squad/gotchas.md)
• Commands (npm install, git commit, docker build)
• Technical terms (library names, API names, protocols, algorithms)
• Proper nouns (project names, people, companies)
• Dates, version numbers, numeric values
• Environment variables ($HOME, NODE_ENV)
• YAML frontmatter (stripped before compression, re-prepended verbatim after — never sent to the LLM at all)

Preserve Structure

• All markdown headings (keep exact heading text, compress body below)
• Bullet point hierarchy (keep nesting level)
• Numbered lists (keep numbering)
• Tables (compress cell text, keep structure)

Compress

• Short synonyms: "big" not "extensive", "fix" not "implement a solution for", "use" not "utilize"
• Fragments OK: "Run tests before commit" not "You should always run tests before committing"
• Drop "you should", "make sure to", "remember to" — just state the action
• Merge redundant bullets that say the same thing differently
• Keep one example where multiple examples show the same pattern

Boundaries

• ONLY compress natural language files (.md, .txt, .markdown, .rst, extensionless prose like CLAUDE.md)
• NEVER modify: .py, .js, .ts, .json, .yaml, .yml, .toml, .env, .lock, .css, .html, .xml, .sql, .sh, and other code/config extensions
• If a file mixes prose + code, compress ONLY the prose sections — code blocks pass through untouched
• If unsure whether something is code or prose, leave it unchanged
• Refuses filenames/paths that look like secrets or credentials (.env, credentials.*, id_rsa, .ssh/, etc.) — compression ships file contents to the Anthropic API, a third-party boundary
• Original is backed up outside the project tree before overwriting (survives project cleanup / .gitignore), and the backup is read back and byte-verified before the source file is touched

Notes

• call_claude() prefers the anthropic SDK when ANTHROPIC_API_KEY is set; otherwise it falls back to claude --print (a headless subprocess using the CLI's own desktop/subscription auth — no API key required for that path). This is a deliberate, narrow exception to dev-squad's general "no headless automation" stance (see feedback_dev_squad_automation_no_headless — that stance is about the autonomous build/audit/ship swarm, not a one-shot maintenance tool like this one).
• Best candidates in a dev-squad project: .dev-squad/memory.md, .dev-squad/gotchas.md, .dev-squad/record.md once they've grown large enough that the tail -N cap in inject-workflow-state.sh is regularly cutting content — compressing first buys more real history inside the same line budget.