Installation

Watercooler can be installed using several methods. Choose the one that best fits your workflow.

Requirements

Python Version

Python 3.10 or later is required

Git

Git must be installed and configured

Watercooler requires Python 3.10+ due to PEP 604 usage (union type syntax). Check your version with python --version.

Installation methods

uv (Recommended)
pip
From source

Using uv

The fastest and recommended installation method using the uv package manager.

Install uv

If you don’t have uv installed, install it first:

curl -LsSf https://astral.sh/uv/install.sh | sh

Install Watercooler

Install from the main branch (stable release):

uv tool install --from git+https://github.com/mostlyharmless-ai/watercooler@main watercooler-cloud

This installs:

watercooler - CLI for terminal use
watercooler-mcp - MCP server (run on-demand by clients)

The main branch is the stable release branch. Installing from @main ensures you get the latest stable version.

Using pip

Install directly from the GitHub repository using pip:

pip install git+https://github.com/mostlyharmless-ai/watercooler.git@main

This installs the watercooler package with all core dependencies.

When using pip, the package name is watercooler. The PyPI package is not yet available, so installation is directly from the GitHub repository.

From source

For development or contributing to Watercooler:

Clone the repository

git clone https://github.com/mostlyharmless-ai/watercooler.git
cd watercooler

Install in development mode

Using uv (recommended for development):

uv pip install -e .

Or using pip:

pip install -e .

The -e flag installs in editable mode, so changes to the source code are immediately reflected.

Install development dependencies

uv pip install -e ".[dev]"

This includes testing tools like pytest, mypy, and jsonschema.

Optional dependencies

Watercooler supports several optional feature sets. Install them as needed:

pip install 'watercooler[baseline]'

Feature descriptions

baseline - LLM-based knowledge graphs

Provides LLM-based summarization for knowledge graphs.Dependencies: httpx>=0.25Usage: watercooler baseline-graph build

local - Local model support

Downloads GGUF models with llama-server binary auto-downloaded at runtime.Dependencies: huggingface_hub>=0.20, httpx>=0.25Usage: Run local models for memory features without external APIs

visualization - Interactive graphs

Interactive graph visualization for baseline graphs.Dependencies: pyvis>=0.3.0, networkx>=3.0Usage: scripts/visualize_graph.py

http - HTTP server

FastAPI-based HTTP server for Railway deployment.Dependencies: fastapi>=0.100, uvicorn[standard]>=0.20Note: These dependencies are included in the core installation by default.

dev - Development tools

Testing and type-checking tools for contributors.Dependencies: pytest>=7.0, mypy>=1.0, jsonschema>=4.0, tqdm>=4.0

Verification

After installation, verify that Watercooler is installed correctly:

Check CLI availability

watercooler --help

You should see the command-line interface help with available commands.

Check version

python -c "import watercooler; print(watercooler.__version__)"

This displays the installed version (e.g., 0.2.6).

Verify MCP server

The MCP server binary should be available:

watercooler-mcp --help

The MCP server is typically run by your MCP client (Claude Code, Codex, Cursor) via uvx, not directly from the command line.

Package information

Package Details

Package name: watercoolerVersion: 0.2.6 (as of latest stable)License: Apache 2.0Repository: github.com/mostlyharmless-ai/watercoolerPython support: 3.10, 3.11, 3.12+

Core dependencies

Watercooler includes these core dependencies:

fastmcp>=2.0,<3
python-ulid>=2.0
GitPython>=3.1.0
pydantic>=2.0
tomli>=2.0  # Python <3.11 only
tomlkit>=0.12
fastapi>=0.100
uvicorn[standard]>=0.20

The tomli package is only required for Python versions before 3.11, as Python 3.11+ includes TOML support in the standard library.

Updating

To update to the latest version:

uv
pip
From source

uv cache clean watercooler-cloud
uv tool install --from git+https://github.com/mostlyharmless-ai/watercooler@main watercooler-cloud

pip install --upgrade git+https://github.com/mostlyharmless-ai/watercooler.git@main

cd watercooler
git pull origin main
uv pip install -e .

After updating, restart your MCP client so the server picks up the new version.

Uninstalling

To remove Watercooler:

uv tool uninstall watercooler-cloud

pip uninstall watercooler

Uninstalling Watercooler does not remove your thread data or configuration files. These are stored separately in your repository’s orphan branch and ~/.watercooler/ directory.

Troubleshooting

Python version error

Error: Watercooler CLI requires Python 3.10+Solution: Upgrade your Python installation to 3.10 or later. Check your version with python --version.

Command not found

Error: watercooler: command not foundSolutions:

If using uv: Ensure ~/.local/bin is in your PATH
If using pip: Ensure your Python scripts directory is in your PATH
Try running with full path: python -m watercooler

Import errors

Error: ModuleNotFoundError: No module named 'watercooler'Solutions:

Verify installation: pip list | grep watercooler
Reinstall: pip install --force-reinstall git+https://github.com/mostlyharmless-ai/watercooler.git@main
Check Python environment: Ensure you’re using the correct virtual environment

Git authentication issues

Error: Authentication failures during thread operationsSolution: Complete the authentication setup. See the Authentication guide or run:

gh auth login
gh auth setup-git

Next steps

Quickstart

Get up and running with your first thread in under 10 minutes.

Authentication

Set up GitHub authentication for thread synchronization.

MCP Clients

Connect Claude Code, Codex, Cursor, or other MCP clients.

Configuration

Customize Watercooler settings and environment variables.

Get Started

Core Concepts

Setup & Configuration

Guides

Requirements

Python Version

Git

Installation methods

Using uv

Using pip

From source

Optional dependencies

Feature descriptions

Verification

Package information

Package Details

Core dependencies

Updating

Uninstalling

Troubleshooting

Next steps

Quickstart

Authentication

MCP Clients

Configuration

Build docs developers (and LLMs) love

Get Started

Core Concepts

Setup & Configuration

Guides

​Requirements

Python Version

Git

​Installation methods

​Using uv

​Using pip

​From source

​Optional dependencies

​Feature descriptions

​Verification

​Package information

Package Details

​Core dependencies

​Updating

​Uninstalling

​Troubleshooting

​Next steps

Quickstart

Authentication

MCP Clients

Configuration

Build docs developers (and LLMs) love

Requirements

Installation methods

Using uv

Using pip

From source

Optional dependencies

Feature descriptions

Verification

Package information

Core dependencies

Updating

Uninstalling

Troubleshooting

Next steps