Installation

Installation has two steps. You have to configure the MCP server and add guidance into your global context that instructs the LLM to use it appropriately.

You may prefer to read the instructions for your client:

Choosing where to store your memories

Hippo stores its data in a directory structure with individual JSON files for each insight and metadata. You can put this directory anywhere, but I suggest you version it with git for backup purposes.

The easiest way to set up Hippo is using the automated setup tool:

# Clone the repository
git clone https://github.com/socratic-shell/hippo.git
cd hippo

# Automatic setup (production mode - installs to PATH)
cargo setup

# Or development mode (builds to target/ for fast iteration)
cargo setup --dev

# Custom memory location
cargo setup --memory-dir ~/my-project/hippo-memories

# See all options
cargo setup --help

This tool will:

  • Build/install the Rust Hippo server
  • Register Hippo as a global MCP server in your CLI tool
  • Create the memory storage directory
  • Provide instructions for adding the guidance context

Manual Setup (Alternative)

If you prefer to set up manually or need custom configuration:

Prerequisites

  • Rust and Cargo (install from rustup.rs)
  • Q CLI or Claude Code

Build the Server

# Clone the repository
git clone https://github.com/socratic-shell/hippo.git
cd hippo

# Build the Rust server
cargo build --release --manifest-path rs/Cargo.toml

The command to run hippo is:

/path/to/hippo/rs/target/release/hippo-server --memory-dir $HIPPO_MEMORY_DIR

Adding guidance to your context

Add something like this to your user prompt or system configuration:

You have access to a memory system called Hippo through MCP tools. Use it to:

1. **Record insights** during natural consolidation moments (when we checkpoint work, 
   say "make it so", or wrap up substantial conversations). Generate insights about 
   what we discovered, decided, or learned.

2. **Search for relevant insights** when users ask questions, when they seem to be 
   referencing past conversations, or when you want to verify information you're 
   about to share. Surface relevant insights naturally in your responses.

3. **Modify and generalize insights** when reusing them in new contexts. Feel free 
   to update the content to be more general or accurate, and expand the situational 
   context to include new scenarios where the insight applies.

4. **Suggest reinforcement** during consolidation - analyze which insights were 
   actually useful in our session and suggest upvotes/downvotes based on usage patterns.

The system embraces messiness - don't worry about perfect categorization. Use 
situational context (when/where insights occurred) rather than rigid categories. 
Let temporal scoring and user feedback naturally organize knowledge over time.

Per-client instructions

Claude Code instructions

Option 1: Use automated setup (recommended)

cargo setup --tool claude

Option 2: Manual setup

  1. Create directory for Hippo data:

    mkdir -p ~/.hippo

  2. Build the server:

    cargo build --release --manifest-path rs/Cargo.toml

  3. Add MCP server to Claude Code configuration:

    Add this to your Claude Code MCP configuration file (usually ~/.claude/mcp_servers.json):

    {
  "mcpServers": {
    "hippo": {
      "command": "/path/to/your/hippo/rs/target/release/hippo-server",
      "args": [
        "--memory-dir", 
        "~/.hippo"
      ],
      "env": {
        "HIPPO_LOG": "info"
      }
    }
  }
}

    Replace /path/to/your/hippo with the actual path where you cloned the repository.

  4. Add guidance to your context:

    Add @/path/to/your/hippo/guidance.md to your CLAUDE.md file.

Q CLI instructions

Option 1: Use automated setup (recommended)

cargo setup --tool q

Option 2: Manual setup

# Create directory for Hippo data
mkdir -p ~/.hippo

# Build the server
cargo build --release --manifest-path rs/Cargo.toml

# Add Hippo MCP server to Q CLI
q mcp add \
  --name hippo \
  --command "/path/to/your/hippo/rs/target/release/hippo-server" \
  --args "--memory-dir" \
  --args "~/.hippo" \
  --env "HIPPO_LOG=info" \
  --force

Also add @/path/to/your/hippo/guidance.md to your agent definition.

Frequently asked questions

Something isn't working, how do I debug?

By default, Hippo only logs ERROR level messages and above to minimize noise during normal operation. To enable full debug logging, set HIPPO_LOG=debug in your MCP server configuration and it will generate comprehensive debug logs. This includes all DEBUG, INFO, WARNING, and ERROR messages which can help diagnose issues.

What's the difference between production and development mode?

  • Production mode (cargo setup): Installs the binary to your PATH using cargo install. The binary is available system-wide and you can delete the source directory after installation.
  • Development mode (cargo setup --dev): Builds to the target/ directory. Faster for development iteration but requires keeping the source directory.