CLI reference

Quick reference for every Hydrate command. Each entry shows the CLI form, when to reach for it, and the equivalent MCP tool (where one exists) for use inside Claude Code.

Memory

Record a fact (retrieved when relevant)

The everyday way to record knowledge. Hydrate surfaces it automatically when future prompts are related.

# In Claude Code
record as a fact for this project: the task queue uses BullMQ with Redis on port 6379

Record a canonical fact (always injected)

The fact must be present on every session, not just when relevant. Use for non-negotiable rules: API contracts, naming conventions, architecture decisions that must never drift.

# In Claude Code
pin as canon for this project: all API responses are wrapped in {"data": ..., "error": ...}

List canonical facts

Audit what is always being injected into your sessions.

# In Claude Code
show my canonical facts for this project

Remove a canonical fact

A pinned fact is outdated or wrong. Get the ID from canon list first.

# In Claude Code
remove canonical fact abc12345 from this project

Recall facts manually

Explicitly query Hydrate's memory mid-session, or use in an environment where the UserPromptSubmit hook is not running.

# In Claude Code
recall what you know about the auth system for this project

Extract facts from a document

You have existing documentation (README, spec, architecture doc) and want Hydrate to learn from it without running a session. Run once on project setup. Full dehydrate docs →

hydrate dehydrate [DIR] [--mode=stub|summary|full] [--apply]
                  [--include=<glob,glob>] [--exclude=<glob,glob>]
hydrate dehydrate [DIR] --revert   # restore CLAUDE.md and drop ledger facts

Session lifecycle

Distill before clearing

You are about to /clear and want to preserve session knowledge. Run this, then /clear.

# In Claude Code
/hydrate-distill

Load context from past sessions

Manual recall at session start, or when the hook is not running.

/hydrate

Load context from the last session only

/hydrate-last

Load context scoped to this week

Longer-running work where you want the last 7 days of sessions, not just the most recent one.

/hydrate-week

Load context scoped to this project

All memory for the current project, regardless of recency.

/hydrate-project

Handovers (v0.6.0)

The handover file at .hydrate/HANDOVER.md is the primary high-fidelity channel for resuming a session after /clear. The CLI owns the file layout (including the per-session archive) so slash commands and agents never need to know about archive paths. Full handover docs →

Print the handover path

Absolute path to .hydrate/HANDOVER.md in the current project.

Read the current handover

Exits 0 when the file is present and 2 when absent, so it composes cleanly in shell pipelines. --archive=FILE reads a specific archive entry instead of the latest pointer.

Write a new handover

Atomic. By default also copies into the per-session archive at .hydrate/handovers/<UTC-ISO-compact>-<6hex>.md. --touch bumps mtime without changing content; --no-archive skips the archive copy.

# Used by /hydrate-distill
cat <<'EOF' | hydrate handover write --stdin
# Outgoing session notes
... markdown body ...
EOF

Clear the current handover

Removes .hydrate/HANDOVER.md. Archive entries are untouched.

List archive entries

Every entry under .hydrate/handovers/ with timestamp and size. --json for piping.

Grep the archive

Searches every archive entry. Exits 0 on a hit and 2 on no matches, like a well-behaved grep.

Prune the archive

Trim the archive: keep the most recent N, or drop anything older than DUR (e.g. 30d, 720h).

Project wiki (v0.6.0)

Curate or recurate the autonomous project wiki under <project>/HYDRATE-wiki/. The same worker runs automatically every six hours via claude-session-start; this is the manual trigger. Full Files docs →

Curate the wiki

Re-authors any page whose cited source SHAs have changed, plus pages older than 60 days. --max-pages-per-cycle caps one run's LLM budget; the rest queue for the next cycle. --dry-run prints the authoring queue without writing. Single-instance file lock at ~/.hydrate/auto-wiki/<slug>.lock.

# Re-curate the current project, cap this run at 20 pages
hydrate wiki curate --max-pages-per-cycle=20

# Preview what would be re-authored, no LLM calls
hydrate wiki curate --dry-run

Hydration packs

Create a pack

Export your session's pinned facts for sharing with a teammate or for use as a resume pack across a /clear.

hydrate pack create --project=myproject --name=session-2026-04-25 --out=~/packs/myproject-latest.hpack

Import a pack

Load a pack a teammate created, or reload your own resume pack. Add --queue to guarantee the facts are injected on the very next prompt (useful after a /clear).

# Queue for immediate injection on next prompt
hydrate pack import ~/packs/myproject-latest.hpack --project=myproject --queue

# Or in Claude Code
/hydrate-pack-load

Inspect a pack

Preview what facts are inside a pack before importing it.

hydrate pack inspect ~/packs/myproject-latest.hpack

List packs

hydrate pack list [--dir=path]

Import canon from a Markdown file

You maintain a Markdown bullet list of authoritative facts (character sheets, API contracts, architecture decisions). Import them in bulk rather than one at a time.

hydrate canon import --project=myproject --from=docs/architecture-canon.md

Export canon to Markdown

Generate a Markdown snapshot of all pinned facts for version control or sharing.

hydrate canon export --project=myproject > docs/architecture-canon.md

Projects

hydrate project list                          # all known projects (fact counts, last-used dates, active cap)
hydrate project activate <slug>              # mark a project as current; hooks default to it without --project flags
hydrate project deactivate <slug>            # stop counting against your active project cap (keeps data)
hydrate project touch <slug>                 # update last-used timestamp
hydrate project check <slug>                 # show a project's current status
hydrate project rename <old> <new>
hydrate project forget <slug>                # delete all data for a project (prompts to confirm)

MCP equivalents: hydrate_list_projects / hydrate_project_activate.

Project management (v0.1.0-beta.5)

Cross-project memory operations for when one project needs to spin off from another, when two projects want to converge, or when a fact turns out to be useful everywhere.

hydrate project fork <src> <dst> [--force]
    # copy every project-scoped fact + session summary from src into a new project dst.
    # the two projects diverge from the fork instant. dst records forked_from=src for lineage.
    # --force overwrites dst if it already exists.

hydrate project merge <target> <source> [--strategy=merge-union] [--apply]
    # fold source's facts into target. session summaries stay with their original project.
    # dry-run by default. strategies: reject | replace | merge-newer | merge-union (default).
    # --apply commits inside a SQLite transaction; errors roll back cleanly.

hydrate project discover-common [--threshold=3] [--apply]
    # find facts whose content_hash matches across N or more active projects.
    # interactive walk-through: y = promote to user-scope, N = skip, s = skip one, a = skip all.
    # items whose slugs share a prefix (e.g. civichub-brent, civichub-newham) are flagged;
    # those usually want 'hydrate project merge' first, so flagged items always confirm
    # individually even under --apply.

hydrate project promote <fact-id> --to=<user|org|project> [--project=<slug>] [--apply]
    # change a fact's scope. promoting to user|org dedupes identical-content project rows.
    # demoting to project requires --project=<slug>. dry-run by default.
    # writes a provenance line to ./HYDRATE.md when one exists.

All four verbs operate on the local SQLite store and never call the network. They are CLI-only; the daemon and capture hooks are unchanged.

Team sync

See the full team docs for setup, repository layout, and conflict resolution. Quick reference:

hydrate team push --project=myproject       # push your local canon to the shared team git repo
hydrate team pull --project=myproject       # pull facts teammates have pushed into your local store
hydrate team status --project=myproject     # how many local facts are unpushed, how many teammate facts waiting
hydrate team sync                           # pull + push in one step
hydrate team init ...                       # manager: create the team repo (see /docs/team)
hydrate team clone ...                      # teammate: join an existing team

MCP equivalents: hydrate_team_push / hydrate_team_pull / hydrate_team_status.

Diagnostics

Health check

Something isn't working. Doctor checks every component (injection, capture, hooks, store) and tells you what's wrong. Add --report for a paste-ready diagnostic block.

# In Claude Code
run hydrate doctor

List configured providers

Confirm which LLM and embedding providers are active. API keys are masked.

# In Claude Code
show hydrate providers

Config

hydrate config get [key]            # inspect a specific value, or dump the full config
hydrate config set key=value        # change a config value
hydrate config list
hydrate config path                 # print the TOML path

Useful keys:

• embed.provider / embed.model / embed.dim: embedding config
• extract.provider / extract.model: fact-extraction LLM
• inject.max_tokens: soft budget for UserPromptSubmit injection
• inject.max_facts: max fact count per prompt
• storage.path: SQLite location (default ~/.hydrate/db.sqlite)

MCP equivalent: hydrate_config_get. Set is CLI-only.

hydrate config get embed.model
hydrate config set embed.model=text-embedding-3-small

Cognitive layer

The cognitive layer runs automatically; no commands needed for normal use. The inner monologue fires on every Claude turn; a micro dream cycle fires at session end. The entries below are for explicit control or inspection.

Inner monologue (automatic)

Runs on every Stop hook. Extracts goals, open questions, active entities, and uncertainty markers from each turn, evaluates seven suggestion rules, and queues high-priority thoughts for the next session's UserPromptSubmit drain. No user action required.

Read working memory

At the start of a new session, check what goals and open questions carried over from the previous one.

# In Claude Code
show my working memory from the last session

Write to working memory

Actions: add_goal · add_question · add_entity · add_uncertainty

# In Claude Code
add to working memory: finish the rate limiter before the standup
add to working memory as a question: should we use refresh tokens or short-lived JWTs?

Trigger a dream cycle

micro runs automatically at every session end. standard scans the recent fact corpus for contradictions and themes. deep scans the entire store. All cycles are rule-based with no LLM calls.

# From terminal
hydrate dream --type=standard

# In Claude Code
trigger a deep dream cycle

The response includes tone, shape, themes, inputs considered, and contradiction count. A warning note appears when contradictions are found.

Read dream reports

Reports start [FUZZY], decay to [VAGUE] after 1 hour, and disappear at 24 hours.

# In Claude Code
show my dream reports

Cross-tool ingestion (v1.x)

Ingest a Claude.ai conversation export

You have a conversations.json from a claude.ai export bundle and want years of past conversation history searchable in future Claude Code sessions.

# Dry-run preview (default: counts conversations, does not write)
hydrate ingest --source=claude-export ~/Downloads/data-2026-04/

# Commit
hydrate ingest --source=claude-export ~/Downloads/data-2026-04/ --apply

# Re-running --apply against unchanged input is a no-op (per-conversation
# ledger at ~/.hydrate/ingest.ledger). Re-export the bundle and re-run
# to pick up new conversations.

# Undo
hydrate ingest --source=claude-export ~/Downloads/data-2026-04/ --revert --apply

Ingest a ChatGPT export

hydrate ingest --source=chatgpt-export ~/Downloads/chatgpt-export/conversations.json
hydrate ingest --source=chatgpt-export ~/Downloads/chatgpt-export/conversations.json --apply

Same as the claude-export path but for OpenAI exports. Hydrate handles the different schema and linearisation automatically.

Ingest a directory of saved transcripts

hydrate ingest --source=dir ./old-transcripts/ --project=myproject --apply

LLM-backed ingest has a 30 minute cap per --apply run. Long exports are normally fine; if you hit the cap, split the bundle into directories and run several smaller ingests. The per-conversation ledger means the second run skips anything the first one already processed.

Accepts .md, .txt, or .jsonl transcripts. Each file becomes one conversation.

Taxonomy: areas (v1.x)

User-curated topic tags applied to facts. Project-scoped and global coexist and are shown together in list output.

# List areas
hydrate area list [--scope=both|project|global] [--project=<slug>]
hydrate area list --global

# Show facts in an area
hydrate area facts auth --limit=20

# Tag a fact into an area
hydrate area move <fact-id> --to=auth

# Rename / merge / delete
hydrate area rename auth authentication       # rename in current scope
hydrate area merge auth authentication        # fold src into dst
hydrate area delete authentication            # clears the tag (does NOT delete facts)

# Auto-tag untagged facts (heuristic, no LLM call)
hydrate area auto-tag                         # dry-run preview
hydrate area auto-tag --apply                 # apply (matches by token overlap with existing area names)

Architectural decisions: inline marker extraction (v1.x)

Walks source files for # WHY: / # DECISION: / # TRADEOFF: markers and inserts them as facts. Pure regex extraction with no LLM call in any code path. With --pin, the markers land in canon and propagate to CLAUDE.md's authoritative tier through hydrate sync.

Scan a repo for decisions

# Dry-run: list every marker found
hydrate decisions scan

# Insert as ordinary facts
hydrate decisions scan --apply

# Promote to authoritative canon
hydrate decisions scan --apply --pin
hydrate sync

Re-running --apply against unchanged source is a no-op (per-marker ledger at ~/.hydrate/decisions.ledger).

# List previously-extracted decisions
hydrate decisions list --project=myproject

# Revert decision extraction for a directory
hydrate decisions revert ./repo --apply

Knowledge-graph timeline (v1.x · experimental)

Chronological story of an entity across sessions. Ships behind --experimental; every endpoint failure mode exits 0 with a stderr note so the matching slash command is fail-safe.

# Formatted text grouped by month
hydrate timeline auth --experimental

# JSON for piping
hydrate timeline auth --experimental --json

# Restrict to project and date range
hydrate timeline auth --experimental --project=billing --since=2026-01-01

Slash command: /hydrate-timeline <entity> (installed by hydrate install-hooks).

Auto-sync hooks (v1.x)

Install a post-commit hook for decisions and ingest

# Install (chains alongside any existing post-commit hook by default)
hydrate install-hooks --git

# Overwrite an existing hook instead of chaining
hydrate install-hooks --git --force

# Preview without writing
hydrate install-hooks --git --dry-run

# Uninstall (restores the original chained hook if there was one)
hydrate install-hooks --git --remove

The hook is fail-safe by construction (set +e, exit 0 unconditional); a broken Hydrate install never blocks a commit.

If a project's .hydrate.yaml declares an ingest_dir, the hook also runs hydrate ingest --source=dir <path> --apply after each commit:

# .hydrate.yaml
post_commit:
  ingest_dir: ./transcripts

Maintenance

Re-embed facts

hydrate reembed [--project=myproject]         # preview first
hydrate reembed --project=myproject --apply   # then apply

You have changed your embedding model and want to recompute vectors for existing facts so semantic search stays accurate.

Sync facts to a directory

hydrate sync --project=myproject [--dir=path]

Export facts as Markdown files to a directory for version control or external tooling. Also writes canon changes from decisions scan --pin into CLAUDE.md's authoritative tier.

Backup / restore (Pro)

hydrate backup --project=<slug> [--passphrase=<pass>] [--out=<path>]
hydrate restore <bundle> [--passphrase=<pass>] [--merge=<strategy>] [--dry-run] [--yes]
hydrate inspect <bundle>   # read metadata trailer (no passphrase needed)

Merge strategies: reject (default), replace, merge-newer, merge-union. Full backup docs →

hydrate backup --project=myproject --out=~/backups/myproject-2026-04-25.hbak
hydrate restore ~/backups/myproject-2026-04-25.hbak --dry-run
hydrate restore ~/backups/myproject-2026-04-25.hbak --yes

Account

# Store an API key in the OS keychain
hydrate login openai
hydrate login anthropic
hydrate login voyage

# Remove a stored key
hydrate logout openai

# Activate a paid plan
hydrate register --edition=pro [email protected]

# Check your current plan and active project count against your cap
hydrate plan show

Server

hydrate server start [--port=8089]   # run the daemon in the foreground
hydrate server stop
hydrate server logs [--follow]

hydrate setup starts the daemon as a launchd / systemd service automatically. The server commands are there for debugging and one-off foreground runs.

Skills (mined workflows)

Mine session JSONLs for repeated workflows

Walks every ~/.claude/projects/*/*.jsonl and ~/.codex/sessions/*, clusters by prompt-template or tool-sequence, and writes patterns to skill_patterns. View results at /skills in the dashboard.

Draft a skill markdown from a mined pattern

LLM-drafts a SKILL.md from the pattern's sample prompts. Use --list to see all candidate IDs first.

Install a drafted skill into Claude Code

Copies the drafted skill into Claude Code's skills directory. Defaults are sniffed from the pattern's project-dominance verdict.

Orchestrator

Pin a key/value scoped to an orchestration

Records facts under project_id='orchestrator:<orch>' so they're scoped to the orchestration and surface on its dashboard view.

Read a pinned key

Dispatch a task to a named pane

Sends a brief to a tmux pane in the orchestration's session, with optional eta and acceptance-gate metadata. See the dashboard Orchestration page for the Build form that scaffolds all of this.

Narrative

Generate NARRATIVE.md for a project

Weaves session JSONLs + git history + project docs into a chapterised NARRATIVE.md. First run is the most expensive; use --update from then on to append new chapters incrementally. --dry-run previews the chapter structure without calling the LLM.

Global flags

• --help, -h: full help for any subcommand
• --json: emit machine-readable JSON (most commands support this)
• --quiet: suppress progress chatter
• HYDRATE_DISABLE=1: env var to no-op both hooks for a session
• HYDRATE_DB=/path/to/db.sqlite: point the CLI at an alternate store

Summary table