Hippo: AI-Generated Insights Memory System

An experiment in collaborative memory through reinforcement learning.

Hippo is a memory system designed to let insights emerge organically through usage patterns. It supplies the LLM with tools to record insights and then later to indicate which ones are useful via up/down-voting (similar to reddit or stack overflow) and to make edits.

Prerequisites

• Python 3.10+
• uv (Python package manager) - Install from uv installation guide

Quick Start

1. Clone and Setup

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

# Install dependencies
uv sync

# For development, also install dev tools (mypy, pytest, ruff)
uv sync --extra dev

# Test the installation
uv run python -m hippo.server --help

2. Quick Development Setup

For Q CLI users, use the automated setup tool:

# Automatic setup with defaults (production mode)
cargo setup

# 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 Q CLI
• Create the memory storage directory
• Provide instructions for adding the guidance context

3. Manual Setup (Alternative)

For Q CLI (Manual):

# Create data directory
mkdir -p ~/.hippo

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

# Add server (replace /path/to/hippo with your actual path)
q mcp add \
  --name hippo \
  --command /path/to/hippo/rs/target/release/hippo-server \
  --args --memory-dir \
  --args ~/.hippo \
  --env HIPPO_LOG=info \
  --force

# Add guidance to your agent definition
# @/path/to/hippo/guidance.md

For Claude Desktop (Manual): Add to claude_desktop_config.json:

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

Then add @/path/to/hippo/guidance.md to your CLAUDE.md file.

3. Alternative: Docker/Podman

# Build and run
podman build -t hippo-server .
mkdir -p ./data
podman run -d --name hippo -p 8080:8080 -v ./data:/data:Z hippo-server

Documentation

See the md/ directory for comprehensive documentation:

• Installation Guide - Complete setup instructions
• Introduction - What is Hippo and why
• Docker Usage - Container deployment guide
• Design Document - Deep concepts and philosophy

Development

# Run type checking
uv run mypy py/hippo/

# Run tests
uv run pytest py/hippo/

# Run the server locally
uv run python -m hippo.server --memory-dir ./test-data

Status

Prototype implementation.