How and when to dehydrate

What dehydrate does

hydrate dehydrate reads CLAUDE.md plus any docs/*.md you point it at, extracts atomic facts into Hydrate's project-scoped store, and rewrites CLAUDE.md into a lean summary (or a stub, or leaves it alone — you pick).

It is a one-way operation. There is no rehydrate. Once the facts are in Hydrate, the always-on UserPromptSubmit hook injects them into every Claude Code session. The original prose never needs to be reconstituted — that's the whole point. You can revert the CLAUDE.md rewrite via --revert, but it's meant to be a safety net, not a workflow.

Why it exists

CLAUDE.md files grow. Decisions accumulate, conventions get written down, notes become sections become chapters. By month three of a serious project nobody reads it any more, but Claude Code still does — and pays the token cost every turn.

Dehydrate extracts the durable knowledge into atomic facts that Hydrate can inject selectively, relevance-scored, at prompt time. The source file shrinks to a human-readable summary (or a stub) while every bit of knowledge it carried stays available to the agent.

The honest benchmark number

In our civichub.uk benchmark (2026-04-18), a properly dehydrated project got the same Hydrate-tier cost savings as the un-dehydrated equivalent (−22% vs vanilla Claude Code). Dehydrate did not add a new saving; it preserved the Hydrate saving at 82% less CLAUDE.md length.

That's the whole number. Dehydrate is a hygiene feature, not a performance amplifier. If you were hoping for compounding savings, I'm sorry to disappoint. The saving comes from Hydrate's memory injection; dehydrate lets you keep that saving at a lighter CLAUDE.md weight.

That's still useful. A lean markdown file is easier to review, easier to keep in sync, easier to hand to a new teammate. But if anyone (including us) pitches it as a cost multiplier on top of Hydrate, they're factually wrong. Correct them.

When to dehydrate

Reach for dehydrate when both of these are true:

• Your CLAUDE.md is more than ~300 lines (rough threshold).
• It contains prose content — decisions, conventions, narrative notes — alongside operational content like build commands or hook configs.

Those are the cases where the prose is paying a token tax every session but could live as structured facts instead. The operational content (commands, env vars, hook settings) gets preserved verbatim in the rewrite — it's the prose that collapses into facts + summary.

When not to dehydrate

• Lean CLAUDE.md files. A 50-line file is already close to the floor. Dehydrating it removes very little and adds a sidecar (HYDRATE.md) plus a backup you don't need.
• Mostly-operational CLAUDE.md files. If your file is 90% build commands and hook configs, dehydrate preserves all of that verbatim. The shrink is negligible — there's no prose to extract.
• Projects with strict CI that greps the markdown. If a build step checks that CLAUDE.md contains specific strings, the rewrite will break it. Run in --mode=full if you want the facts in Hydrate without touching the source.

The three modes

The big knob is --mode. Facts get ingested either way; the difference is what happens to CLAUDE.md afterwards:

• stub — CLAUDE.md becomes a ~5-line pointer to Hydrate plus any operational content preserved verbatim. Shortest useful form. Right when you're the only reader.
• summary (default) — CLAUDE.md becomes a compressed summary of the original prose plus preserved operational content. Colleagues, reviewers, and CI bots still see a useful overview. The right default.
• full — CLAUDE.md is untouched. Facts still land in Hydrate. Use for A/B testing Hydrate on top of an unchanged baseline, or when CI is fussy about the file contents.

What happens on re-run

Dehydrate is idempotent. It writes a HYDRATE.md ledger recording each ingested file's SHA256 and the fact IDs it produced. Re-running on an unchanged repo is a no-op; re-running after editing one file re-extracts only that file, because the other sources' hashes still match the ledger.

That makes dehydrate safe to run on a schedule — a post-commit hook, a nightly cron, whatever. It only does work when something has actually changed.

$ hydrate dehydrate . --apply
Scanning /Users/seamus/Documents/Dev/go/civichub (mode=summary)
  CLAUDE.md            1204 lines   47.1KB  [changed]
  docs/UI_PATTERNS.md   584 lines   21.5KB  [unchanged]
  docs/DATABASE.md      318 lines   11.2KB  [unchanged]

  3 sources (1 to ingest, 2 unchanged)

Extracted 8 new facts, 2 updated, 0 removed.
Rewrote CLAUDE.md: 1204 lines → 94 lines (92% smaller).
Ledger: HYDRATE.md updated.
Backup: CLAUDE.md.pre-hydrate.bak preserved from first run.

What dehydrate does not do

• It doesn't replace backup / restore. Per-project portable bundles are a separate Pro feature for moving a whole project's memory between machines. Dehydrate is about ingesting source markdown into a single machine's Hydrate store.
• It doesn't add new Claude Code performance beyond plain Hydrate. Re-read the benchmark number above. Dehydrate lets you keep Hydrate's saving with a lean CLAUDE.md; it doesn't compound on top of it.
• It isn't reversible beyond --revert. Revert restores the backup and drops the ledger-attributed facts. There's no fancier undo; there doesn't need to be.

# Dry run (default — nothing is written)
hydrate dehydrate .

# Commit
hydrate dehydrate . --apply