Hydrate for Claude Code — install in five minutes

After this page: every Claude Code session opens with relevant memory injected, every session end is captured to your local store, and /hydrate-last returns a real briefing from your history.

Prerequisites

• Hydrate installed (hydrate doctor all-green). See Free install.
• Claude Code installed (claude --version).

Install

hydrate install-hooks

This is idempotent — re-running it will not duplicate entries. Output:

✓ UserPromptSubmit hook installed  (~/.claude/settings.json)
✓ Stop hook installed              (~/.claude/settings.json)
✓ PreCompact hook installed        (~/.claude/settings.json)
✓ SessionStart hook installed      (~/.claude/settings.json)
✓ MCP server hydrate configured    (~/.claude/settings.json)
✓ Slash commands installed         (~/.claude/commands/)

To preview changes without writing:

hydrate install-hooks --dry-run

To also wire tool-use guardrails (blocks destructive tool calls you have not confirmed):

hydrate install-hooks --with-tool-guard

Verify

Open Claude Code in any project directory and run:

/hydrate-last

Expected: a briefing covering open questions, decisions, and entities from your most recent session on this project. If this is a new project, the response will say so — no prior history yet.

Check from the shell that hooks are wired:

hydrate doctor

All six checks below should be green:

✓ UserPromptSubmit hook installed
✓ Stop hook installed
✓ PreCompact hook installed
✓ SessionStart hook installed
✓ MCP server "hydrate" configured
✓ MCP reachable with configured api.key

What each hook does

UserPromptSubmit → claude-context

Fires after you submit every prompt. Queries your local Hydrate store for facts relevant to the current prompt text and injects them as additionalContext before the request reaches the model. The injected text is not shown in the Claude Code UI but is present in the conversation transcript at ~/.claude/projects/<hash>/*.jsonl.

Timeout: 1500 ms. On timeout or error, the hook exits 0 and the prompt goes through unmodified (fail-open invariant).

Stop → claude-capture

Fires when the session ends (natural exit or /exit). Posts the full JSONL transcript to your local hydrate-server, which:

1. Upserts a session row in ~/.hydrate/data.db
2. Runs a micro-consolidation (fact extraction + embedding, ~3 s)
3. Updates working memory with open goals and entities from the session

Known gap: /clear may not trigger this hook. If you use /clear frequently, run hydrate distill before clearing to manually capture the session state.

PreCompact → claude-precompact

Fires just before Claude Code auto-compacts a long context window. Saves a recovery snapshot to ~/.hydrate/last-precompact.json.

SessionStart → claude-session-start

Fires at the start of each new session. Reads the precompact snapshot and re-injects it as additional context so the model has orientation even after compaction wiped the history.

MCP server → hydrate-mcp

A stdio MCP server exposing 22 tools to Claude Code. Powers the slash commands and allows the model to read/write memory during a session without going through the hook mechanism.

Slash commands installed:

The additionalContext field

After a few sessions, you can inspect what is being injected:

# Show the last injected context for this project
tail -1 ~/.claude/projects/$(python3 -c "
import sys, urllib.parse, hashlib, os
cwd = os.getcwd()
print(urllib.parse.quote(cwd, safe='').replace('%', '-').lstrip('-'))
")/*.jsonl | python3 -c "
import sys, json
for line in sys.stdin:
    obj = json.loads(line)
    ctx = obj.get('additionalContext')
    if ctx:
        print(ctx[:2000])
"

Empty output means the hook ran but had nothing relevant to inject — common on fresh projects or after the first few sessions.

Fail-open invariant

Every hook shim exits 0 on all error paths. If hydrate-server is down, if the database is locked, or if the network times out, the hook writes a diagnostic to ~/.hydrate/hook-selfcheck.log and lets Claude Code continue normally. Sessions are never blocked.

To verify fail-open behaviour:

hydrate server stop
claude     # open a session — hook should still fire and exit silently

Advanced: skip MCP, hooks only

If you are in an environment where MCP servers cause slowdown (rare), install without the MCP entry:

hydrate install-hooks --no-mcp

You lose the slash commands but keep the automatic context injection and capture.

What changed on your machine

Troubleshooting

Next steps

• Codex integration — memory shared between Claude Code and Codex
• Vibe integration — same memory layer in Mistral Vibe
• Free install — if you skipped the base install