Hippo
Local-first knowledge capture daemon for macOS. Hippo watches your shell activity, Claude Code sessions, and Firefox browsing, redacts known secret formats, enriches events with a local LLM, and builds a searchable second brain with local inference by default. LLM inference runs against any OpenAI-compatible local server on your machine — defaults target oMLX ↗ (continuous batching + tiered KV cache for Apple Silicon), and LM Studio ↗ works as a drop-in alternative. Telemetry is off by default and points at localhost when on. See Privacy and Security for the full data-flow story.
Why hippo
Hippo solves a problem that shell history (~/.zsh_history, fish history, Atuin) and consumer “memory” tools (Rewind, Apple Continuity) don’t:
- Cross-source recall. Your shell command from Tuesday, the Claude Code conversation that produced it, and the StackOverflow tab you had open are all linked into one searchable knowledge graph.
- Semantic + lexical retrieval. Ask
hippo ask "how did I fix that build error?"and get a synthesized answer with cited sources, not agrepover command strings. - Local-only by default. See Privacy and Security for local inference and opt-in external data flows.
- MCP-native. Claude Code can query your knowledge base mid-conversation through the MCP server, so the model can look up “what was I just doing” without you re-explaining.
If you want a faster ^R, use Atuin. If you want hippo’s setup, keep reading.
Quick Install (Apple Silicon)
curl -fsSL https://github.com/stevencarpenter/hippo/releases/latest/download/install.sh | bash
The release binaries are arm64-only. Intel Macs need to build from source — see Manual Installation.
The installer downloads the daemon and brain with checksum verification, writes LaunchAgent plists, and prints a hippo doctor summary on completion. Brain upgrades stage and verify a locked, relocatable environment before replacement; tested ordinary failures restore prior components and receipts. Backup cleanup failures warn without undoing a committed upgrade. Crash-atomic replacement and concurrent installers are not supported guarantees. See the install script source at the link above for what it touches.
Verify it’s working
After install, generate ~5 minutes of shell + browser activity, then:
hippo doctor # green across the board?
hippo events --since 30m # are events landing?
hippo ask "what have I been working on" # synthesized answer + cited sources
If hippo events returns nothing, see Troubleshooting below — the most common cause is the shell hook not being sourced.
Architecture
+-----------+ +--------------+ +--------------+
| zsh | Unix socket | | SQLite (WAL) | |
| shell | ---------------> | | <------------> | hippo-brain |
+-----------+ | | | (Python) |
+-----------+ FSEvents | hippo-daemon | +------+-------+
| Claude | watcher | (Rust) | |
| Code | ---------------> | | +------+-------+
+-----------+ | | | hippo-mcp |
+-----------+ Native Msg | | | (MCP server) |
| Firefox | ---------------> | | +--------------+
| ext. | | | ^ |
+-----------+ +--------------+ stdio | SQLite |
(JSONL) | sqlite-vec |
| LM API |
Claude Code / Desktop
| Component | Language | Role |
|---|---|---|
| hippo-daemon | Rust | Captures events via Unix socket and Native Messaging. Applies secret redaction, stores to SQLite, serves CLI queries. |
| hippo-brain | Python | Polls enrichment queues, calls the local inference server for summarization, correlates browser research with shell activity, writes knowledge nodes + vector embeddings to SQLite via sqlite-vec. |
| hippo-mcp | Python | MCP server exposing the knowledge base over stdio. Claude Code queries your personal knowledge base mid-conversation. |
Five core LaunchAgents run under gui/$(id -u):
| Agent | Role |
|---|---|
com.hippo.daemon | Long-lived Rust daemon (KeepAlive) |
com.hippo.brain | Long-lived Python brain server (KeepAlive) |
com.hippo.claude-session-watcher | FSEvents watcher on ~/.claude/projects/**/*.jsonl (KeepAlive); ingests Claude Code sessions |
com.hippo.watchdog | Capture-reliability monitor; runs every 60 s, asserts I-1..I-12 invariants, writes capture_alarms rows |
com.hippo.probe | Synthetic canary probes; runs every 5 min, round-trips a real event through each capture path and records latency in source_health |
hippo daemon install --force writes the plists and bootstraps all five. The capture-reliability stack (source health, invariants, watchdog, probes, alarms) is documented in docs/capture/ — start with architecture.md. For an end-to-end trace of how a shell command, Claude session segment, or browser visit becomes a knowledge node, see docs/lifecycle.md. Review-blocker rules every contributor must follow live in docs/capture/anti-patterns.md.
If Hippo is configured to use the oMLX macOS app, mise run install:omlx
installs an optional com.hippo.omlx keeper LaunchAgent. Every 60 s it checks
[inference].base_url. If the server answers, or oMLX.app is not running, it
does nothing. If the app is running without a server, it runs
omlx-cli start --no-wait. It never reopens a quit app, so Cmd+Q stays quit.
Because of this, login start relies on oMLX’s own Launch-at-Login setting
(~/Library/LaunchAgents/com.omlx.app.plist); install:omlx warns when it is
off. After a quit or a crash, reopen oMLX.app yourself
(open -gj /Applications/oMLX.app or mise run omlx:start).
mise run omlx:start|stop|restart|status|logs manage the app from the
repo; omlx:stop also unloads the keeper so the server stays stopped.
Prerequisites
| Dependency | Required | Notes |
|---|---|---|
| macOS Apple Silicon (arm64) | Yes for binaries | Intel needs to build from source. Uses launchd for service management. |
| Rust ↗ | Yes | Edition 2024 via the shipped rust-toolchain.toml (1.99). mise.toml enables Rust idiomatic version-file management. |
| Python ↗ | Yes | 3.15+ |
| uv ↗ | Yes | 0.13.7+; verifies the pinned Python build dependencies during source installation. |
| oMLX ↗ or LM Studio ↗ | Yes | Local OpenAI-compatible LLM server. Default config targets oMLX on :8000 and the Qwen3.6-35B-A3B-UD-MLX-4bit chat model + nomicai-modernbert-embed-base-8bit embeddings (768d MLX). Plan on 32 GB+ unified memory for the default chat model; smaller models work with smaller machines — adjust the [models] section. LM Studio users: change [inference].base_url to http://localhost:1234/v1 and use LM Studio’s model IDs (e.g. qwen3.6-35b-a3b-ud-mlx, text-embedding-nomic-embed-text-v2-moe). |
| mise ↗ | Recommended | Task runner; all workflows are defined in mise.toml |
| glow ↗ | Recommended | Renders hippo ask markdown output in the terminal |
| Firefox Dev Edition ↗ | Optional | Browser activity capture (allowlisted developer domains) |
Manual Installation
# Clone hippo and enter the repo
git clone https://github.com/stevencarpenter/hippo.git
cd hippo
# Build and install everything (release binary, LaunchAgents, config, symlink)
mise run install
# Add shell hooks to your zsh config
echo "source $(pwd)/shell/hippo-env.zsh" >> ~/.zshenv
echo "source $(pwd)/shell/hippo.zsh" >> ~/.zshrc
exec zsh # reload
# Configure your inference server + models
hippo config edit
# Optional: make oMLX start through launchd for Hippo
mise run install:omlx
In the config editor, set the [models] section to match models loaded on your inference server. To list loaded models (default is omlx on :8000; LM Studio users use :1234):
curl -s http://localhost:8000/v1/models | python3 -m json.tool
Then edit:
[inference]
base_url = "http://localhost:8000/v1" # omlx default; LM Studio uses :1234
[models]
enrichment = "your-chat-model"
enrichment_bulk = "your-chat-model"
query = "your-chat-model"
embedding = "your-embedding-model" # 768d; e.g. nomicai-modernbert-embed-base-8bit (omlx) or text-embedding-nomic-embed-text-v2-moe (LM Studio)
Verify everything is wired up:
hippo doctor
If anything is red, run hippo doctor --explain for CAUSE / FIX / DOC per failure.
Usage
hippo status # Daemon status
hippo sessions --today # List today's sessions
hippo events --since 2h # Recent shell events
hippo ask "how did I fix that build error" # RAG query (synthesized answer)
hippo query --raw "cargo build" # Raw lexical search (no brain needed)
hippo entities # Known projects, tools, files, env vars
hippo agents report --since 30d # Per-agent scorecards (needs the brain)
hippo export-training --since 30d --out ./export # Export training data
hippo redact test "password=hunter2" # Test redaction patterns
Operational:
hippo doctor # Run diagnostic checks; non-zero exit on any [!!]
hippo doctor --explain # Same, with CAUSE/FIX/DOC for each failure
hippo alarms list # Unacknowledged capture alarms (exit 1 if any)
hippo alarms ack <id> --note "..." # Acknowledge an alarm
hippo probe --source claude-session # Run a synthetic probe for one source
hippo ingest claude-session <path> # Manual one-shot import of a JSONL (recovery)
hippo enrichment pause # Stop LLM enrichment; capture keeps running
hippo enrichment resume # Start LLM enrichment again
hippo enrichment status # Pause state, time of last change, pending count per queue
Pausing enrichment: hippo enrichment pause writes enrichment-state.json in the data directory. The brain reads it on each loop iteration (default 5 s) and stops enrichment for the shell, agentic, browser, workflow, and auto-memory sources. A batch already in flight finishes. Capture, embeddings, queries, MCP tools, and Jev classification keep running, and every queue keeps growing without loss. The state survives restarts and reinstalls. Run hippo enrichment resume and the brain works through the backlog, then keeps enriching new work. This pause is separate from the bench pause below, and neither one clears the other.
Brain API and enrichment control:
mise run brain:api:health # Brain health, queue depths, pause state
mise run brain:api:pause # Pause enrichment; ingestion keeps queueing
mise run brain:api:resume # Resume enrichment
mise run brain:api:query -- "cargo build"
mise run brain:api:ask -- "how did I fix that build error?"
mise run brain:api:openapi # Print OpenAPI contract without a server
mise run brain:api:openapi:live # Fetch /openapi.json from the running brain
mise run brain:api:openapi:write # Write OUT, default brain/openapi.json
brain:api:pause keeps health and resume available but rejects new HTTP knowledge
queries with 503 and stops new background inference. Existing queries, enrichment,
classification, and embedding reaper work drain asynchronously; repeat the pause
request until in_flight_finished is true before using the inference slot.
Standalone MCP processes are not paused by this HTTP control. The daemon and
ingest agents continue writing events and queue rows. Pause does not unload models.
Capture-reliability operator runbook (recipes for “I ran a command but it’s not in hippo events”, “doctor shows red”, “schema mismatch”, etc.): docs/capture/operator-runbook.md.
Troubleshooting
Common first-day failures, in rough order of frequency:
| Symptom | Likely cause | Fix |
|---|---|---|
hippo events returns nothing after several minutes of shell activity | Shell hook not sourced — ~/.zshrc / ~/.zshenv weren’t reloaded after install. | exec zsh or open a new terminal. Verify with grep -l 'hippo.zsh' ~/.zshrc ~/.zshenv ~/.config/zsh/*.zsh 2>/dev/null. |
hippo ask returns “I don’t have enough information” | Brain hasn’t enriched yet, or the configured chat model isn’t loaded. | hippo doctor to confirm. Open omlx (or LM Studio) and load the model in [models].enrichment. |
hippo doctor says inference server isn’t reachable | omlx/LM Studio isn’t running, or it’s serving on a non-default port. | Start the server. For oMLX, run mise run install:omlx; for LM Studio, start it manually. Check the API base URL in ~/.config/hippo/config.toml ([inference].base_url). The legacy [lmstudio] section is rejected with a migration error — rename it to [inference]. |
Daemon won’t start; hippo doctor says schema mismatch | Daemon and brain have different EXPECTED_SCHEMA_VERSION constants — happens after partial upgrades. | mise run install --clean brings everything to the same version. |
| Brain queue backs up | Configured chat model unloaded, enrichment is paused, com.hippo.brain is stopped, or the loaded model is not in [models].enrichment. | Check mise run brain:api:health if brain is running. Use mise run brain:api:resume to clear a soft pause, or load the configured model/start brain when you want the queue to drain. The reaper handles transient locks; persistent backlog is operator-visible. See docs/brain-watchdog.md. |
| Firefox extension shows no recent visits | Native messaging manifest missing, or extension not loaded. | hippo daemon install --force rewrites the manifest. Reload the extension in about:debugging. See extension/firefox/README.md ↗. |
For anything not in this table, run hippo doctor --explain and follow the DOC link in each failure block. The full operator runbook lives at docs/capture/operator-runbook.md.
MCP Server
The MCP server lets Claude Code (or any MCP client) query your knowledge base mid-conversation.
| Tool | Description |
|---|---|
ask | RAG query — synthesizes an answer from relevant knowledge nodes |
search_knowledge | Semantic or lexical search over enriched knowledge nodes |
search_hybrid | Hybrid sqlite-vec + FTS5 search with score fusion |
search_events | Search raw events (shell commands, Claude sessions, browser visits) |
get_entities | List extracted entities (projects, tools, files, env vars, concepts) |
list_projects / get_context / get_ci_status / get_lessons | Discovery + auxiliary lookups |
get_agent_scorecard | Per-agent aggregates: usage, review findings, verdict rates, escapes, benchmarks (no finding text) |
Full reference with arguments, return shapes, examples, and selection guide: docs/mcp-reference.md.
Add to your Claude Code MCP config (e.g., ~/.claude/settings.json or your MCP config file):
{
"mcpServers": {
"hippo": {
"type": "stdio",
"command": "uv",
"args": ["run", "--no-sync", "--project", "/path/to/home/.local/share/hippo-brain", "hippo-mcp"]
}
}
}
Replace /path/to/home with your absolute home directory (MCP configs do not expand ~). Point the server at the installed brain, not at a git checkout: a branch switch in a checkout then cannot change the server your agent sessions use, and the server stays the same version as the brain service. mise run install refreshes that copy, including the hippo-mcp entry point. hippo doctor warns when the installed hippo-mcp version differs from the running brain.
The MCP server reads SQLite directly (vectors live in the same DB via sqlite-vec; no dependency on the brain HTTP server).
For MCP telemetry configuration, dashboards, and corpus coverage signals, see Observability. For optional Jev reranking credentials, see the Jev operator reference.
Trust boundary. Granting Claude Code MCP access to hippo gives the model — and any prompt injection that reaches it through code or documents you ask Claude to read — read access to your shell history, Claude transcripts, and browser data. Grant deliberately.
Firefox Extension (Optional)
# Build + install in one step (also called by `mise run install`)
mise run install:ext
This builds the extension and side-loads the .xpi into your Firefox Dev Edition dev-edition-default profile. For development / hot-reload, extension/firefox/README.md covers the manual about:debugging flow.
The native messaging host is installed by hippo daemon install --force (also called by mise run install).
Configuration
| File | Purpose |
|---|---|
~/.config/hippo/config.toml | Runtime config (models, ports, browser allowlist, telemetry, GitHub token) |
~/.config/hippo/redact.toml | Secret redaction patterns (regex-based) |
Created automatically by mise run install. Use hippo config init to create a missing config.toml without opening an editor; existing valid files are preserved. Edit with hippo config edit. See config/config.default.toml ↗ and config/redact.default.toml ↗ for the templates and inline documentation of each key.
The [models] section must be configured for enrichment to work. Set the model name to whatever your inference server exposes — verify with curl -s http://localhost:8000/v1/models | python3 -m json.tool (or :1234 for LM Studio).
Privacy and Security
Hippo captures shell commands (with opt-in stdout/stderr capture), Claude Code session transcripts, and browser visits from allowlisted domains. All data is stored locally in ~/.local/share/hippo/hippo.db (SQLite, unencrypted — use macOS FileVault for full-disk encryption). Default inference stays local. Opting into Jev reranking or classification sends bounded, redacted query/candidate or node evidence to TypeSafe’s cloud API. See the Jev operator reference for configuration and request limits.
Enrichment and answer synthesis use the configured inference server. Enrichment and RAG queries go to whichever local OpenAI-compatible server you configure ([inference].base_url, default http://localhost:8000/v1 for omlx). If you point that URL at a remote backend, your shell history and session transcripts travel that path.
Redaction is best-effort. Hippo filters known secret formats before storage on supported capture paths and before Jev dispatch. Treat it as a noise filter, not a security guarantee. Test patterns with hippo redact test "your candidate string". Full reference (default rules, evaluation model, custom patterns, known false-negatives, browser URL redaction): docs/redaction.md.
The SQLite database is accessible to any process running as your user. Daemon, brain, and MCP startup restrict the configured Hippo data directory to mode 0700. The daemon creates database and socket files with mode 0600. Use a dedicated data directory; startup rejects the home directory and its ancestors.
MCP access is broad. Adding hippo to Claude Code’s MCP config grants the model read access to your shell history, Claude transcripts, and browser history — including via prompt injection through code or documents you ask Claude to read.
Telemetry is off by default. The OTel stack (otel/) is optional, points at localhost:4317, and only emits when [telemetry] enabled = true. See otel/README.md ↗ for setup and docs/observability.md for dashboards and alert rules.
Network exposure. The brain HTTP server binds 127.0.0.1:9175 and rejects non-loopback Host headers and cross-origin browser requests. Native local clients may omit Origin; any supplied Origin must match the request scheme and Host authority. These checks prevent browser cross-origin access and DNS rebinding; they do not authenticate local users. Other accounts and processes on the machine can still call the HTTP API. Hippo currently requires a trusted single-user host. The daemon’s Unix socket lives at ~/.local/share/hippo/daemon.sock.
Uninstall. Stop services with mise run stop, remove ~/.local/share/hippo/, ~/.config/hippo/, and unload the LaunchAgents (launchctl bootout gui/$(id -u) ~/Library/LaunchAgents/com.hippo.*.plist, then delete the plists).
Development
With mise (recommended)
mise run build # Build Rust crates (debug)
mise run build:release # Build Rust crates (release)
mise run build:brain # Sync Python dependencies
mise run test # Full test suite (Rust + Python + lint + format check)
mise run lint # clippy + ruff check
mise run fmt # Format all code
mise run doctor # Diagnostic checks
Run mise tasks for the complete list.
Without mise
# Rust
cargo build # default features include `otel`
cargo build --no-default-features # build without OTel instrumentation
cargo test --workspace --locked --no-fail-fast # matches CI
cargo clippy --all-targets --locked -- -D warnings
cargo fmt --check
# Python
uv sync --project brain
uv run --project brain pytest brain/tests -v
uv run --project brain ruff check brain/
uv run --project brain ruff format --check brain/
# MCP server
uv run --project brain hippo-mcp
HippoGUI (separate repository)
The native macOS GUI lives in its own repo: stevencarpenter/hippo-gui ↗. It’s a standalone Swift/Xcode app that talks to the daemon over the local socket and the brain over HTTP — build and release it from there.
Service management
mise run start # Start daemon + brain via launchd
mise run stop # Stop both services
mise run restart # Stop + start
mise run nuke # SIGKILL everything (preserves data)
mise run install:omlx # Optional: install the oMLX keeper LaunchAgent
mise run omlx:status # oMLX app/server/keeper state + loaded models
To keep ingestion running while enrichment is fully stopped, do not use
mise run stop; it unloads the capture side too. Boot out only the brain agent:
launchctl bootout "gui/$(id -u)" ~/Library/LaunchAgents/com.hippo.brain.plist
If the daemon is not already loaded, bootstrap
~/Library/LaunchAgents/com.hippo.daemon.plist separately. Then verify with
mise run status: daemon should be reachable, queue depth should be nonzero or
growing, and brain should be unreachable until restarted.
Contributing
See CONTRIBUTING.md — setup, test strategy, dev loop, cross-language coupling, CI, PR conventions, and where to ask. Review blockers for the capture layer are codified in docs/capture/anti-patterns.md (AP-1 through AP-12); read them before your first capture-layer PR.
Project Structure
crates/
hippo-core/ Shared library (types, config, storage, redaction; SQL schema in src/schema.sql)
hippo-daemon/ Binary (daemon + CLI + native messaging host)
brain/ Python enrichment, query server, and MCP server
extension/
firefox/ Firefox WebExtension for browser activity capture
shell/ zsh hooks (preexec/precmd integration)
config/ Default config templates
launchd/ macOS LaunchAgent plist templates
scripts/ Utility scripts (bulk enrich, re-embed, monitor, dedup-entities)
otel/ OpenTelemetry observability stack (docker-compose)
docs/ Live reference docs (capture/, release.md, eval-harness-design.md, brain-watchdog.md)
docs/superpowers/ In-flight feature plans + designs
docs/archive/ Historical plans, design records, post-mortems
tools/ Developer utilities (SQL formatting)
Data Storage
Runtime data and configuration follow XDG defaults. XDG_DATA_HOME overrides the default runtime data root; XDG_CONFIG_HOME overrides the configuration root for the daemon, brain HTTP server, MCP server, and installer. Unset or empty values use the HOME defaults below. An explicit [storage].data_dir overrides the default data directory. Generated LaunchAgents preserve the resolved XDG roots from installation; changing shell variables does not update existing services.
| Store | Path | Purpose |
|---|---|---|
| SQLite | ~/.local/share/hippo/hippo.db | Events, sessions, browser visits, enrichment queue, knowledge nodes, entities, vector embeddings (sqlite-vec). Schema lives at crates/hippo-core/src/schema.sql ↗. |
| Config | ~/.config/hippo/config.toml | User configuration |
| Logs | ~/.local/share/hippo/*.log | Daemon and brain logs |
| Fallback | ~/.local/share/hippo/*.fallback.jsonl | Last-resort durability backstop when the daemon socket is unreachable; replayed on next daemon start |
Schema uses PRAGMA user_version = N; the authoritative version is in crates/hippo-core/src/schema.sql. Daemon and brain handshake on their expected version at startup. See docs/schema.md for the per-version changelog, table map, and version-mismatch recovery; see docs/release.md for the lockstep release workflow.
Event outputs and environment references expire 90 days after ingestion.
hippo gc-event-payloads --confirm explicitly clears expired payloads, retains
ledger rows and metadata, and appends deletion receipts. The same sweep clears
expired agent-evaluation finding text and verdict notes, except for accepted
findings and escapes. It is destructive;
startup and migration do not run it automatically. See
event payload retention for evidence
pins, shared snapshots, checkpoint outcomes and the limits of erasure.
Sponsor
Hippo is free and MIT-licensed. If it is useful to you, you can support its development through GitHub Sponsors ↗.