How to use Hydrate

The problem Hydrate solves

Claude Code forgets between sessions. Each new invocation starts with a blank mind, which is fine for a one-shot prompt and a disaster for a real project you're building across days or weeks.

The obvious workaround is to paste @CLAUDE.md at the top of every session. This scales right up until CLAUDE.md becomes a 1,000-line file and you're paying to re-ingest your entire project history on every turn. The model starts spending its attention budget rereading your prose instead of writing code.

Hydrate's answer is episodic memory. Two hooks capture what happened in each session, extract atomic facts, and inject the relevant ones into the next session's context — scored for relevance, not pasted wholesale. You get continuity without the bloat.

What installing Hydrate actually does

The install script puts one binary on your $PATH and runs hydrate init. That command does three small things:

1. Starts a local daemon, hydrate-server, listening on localhost:8089. This owns the SQLite store and serves the dashboard.
2. Writes two hooks into ~/.claude/settings.json — UserPromptSubmit for the read path, Stop for the write path. Both are just curl calls to the daemon; there's no magic.
3. Runs hydrate doctor to verify the round-trip works end-to-end.

After that, the hooks fire on every claude invocation. You don't need to do anything different at the prompt.

$ hydrate status
✓ hydrate-server running on :8089
✓ Claude Code hooks installed (UserPromptSubmit, Stop)
✓ SQLite store at ~/.hydrate/db.sqlite (147 MB, 3,412 facts, 287 sessions)
  license: Free (local)
  active projects: 2 / 2  (pulse, civichub)

The five patterns that make it pay off

Hydrate is quiet by default — it just runs. But a few deliberate habits turn a reliability tool into an economic one. The short version is in the guide; briefly:

1. Start with architecture. The first session seeds your memory store. A well-scoped s1 with Sonnet or Opus seeds high-quality facts; Haiku carries those facts across every session afterwards.
2. Scope your projects. cd into a project directory scopes Hydrate automatically. Cross-project contamination is solved by the database, not by discipline.
3. Trust the injection, but verify. Weekly hydrate facts review catches stale facts before they turn into false claims the model believes.
4. Dashboard as thermometer. Cache-hit ratio is the number to watch. When it drops below 60%, the fact store has drifted and it's time to prune.
5. Back up before handoff. Pro's per-project backup bundles move an entire project's memory between machines in one encrypted file.

How to know it's working

Open localhost:8089/dashboard. You'll see spend broken down by input / output / cache-read / cache-creation, an estimated savings line, and a per-project table sorted by activity.

For the per-session detail, the CLI is faster:

$ hydrate facts diff --last-session
injected (12 facts):
  fact_7f3a  "product name is Pulse"                    [confirmed 4x]
  fact_8b21  "tech stack: plain HTML / CSS, no JS"      [confirmed 2x]
  fact_c482  "layout: hero + three features + footer"   [confirmed 3x]
  fact_d319  "accent colour is #89b4fa"                 [confirmed 1x]
  [8 more...]

extracted (3 new facts):
  fact_e991  "pricing section has 3 tiers: Free / Pro / Team"
  fact_f042  "FAQ uses 
 elements with the '+' marker pattern"
  fact_f1a8  "dark mode reads prefers-color-scheme and persists in localStorage"

If you see injections on the read side and new facts on the write side, it's working. If you see an empty result, check hydrate status — the daemon is probably down.

When not to use Hydrate

Hydrate isn't universal. Three cases where you should explicitly leave it off:

• One-off scripts. If the entire task fits in one session and nothing downstream depends on it, there's nothing for Hydrate to inject. The hook overhead is tiny, but the fact-store clutter isn't nothing.
• Throwaway repos. Tutorial follow-alongs, scratch exploration, deliberate experimentation. Memory is liability when the project is meant to be discarded.
• Greenfield exploration where you want a blank mind. Sometimes you genuinely want Claude to approach a problem without prior context — brainstorming, when you're about to throw all previous assumptions out. Set HYDRATE_DISABLE=1 for that session.

curl -fsSL gethydrate.dev/install | sh