⚠️ PRE-ALPHA — EXPECT BREAKING CHANGES ⚠️

This is pre-alpha software under active, rapid development. Schemas, CLI commands, on-disk layouts, and APIs may change at any time without notice and without migration paths. If you run memhippo today, expect to rebuild your store across upgrades.

memhippo

The hippocampus for your AI agents.

memhippo gives every AI agent on your machine a shared, persistent memory. It captures every conversation verbatim into a permanent archive you own, distills those conversations into durable facts and session summaries with an LLM, and feeds that knowledge back to your agents — automatically at session start, mid-session when relevant, and on demand through search tools.

AI assistants forget. Every session starts from zero, and memory is siloed per tool: something you told one assistant is unknown to every other. memhippo fixes both:

1. Ambient continuity — sessions start already oriented and receive relevant memory as the conversation calls for it.

2. A cross-agent shared brain — one memory shared by Claude Code, OpenClaw, and any MCP-speaking agent.

Underneath both sits one principle: a verbatim raw archive you own forever. Summaries and indexes are opinions; the raw record is truth, and everything else can be re-derived from it.

Status

Early. Single-user, macOS-tested (the daemon and CLI are plain Node and should run elsewhere; the launchd safety net and install flow are macOS-specific). APIs and schemas may still change. Distillation currently calls the Claude API via the Claude Agent SDK; everything else is fully local.

Related MCP server: Memsolus MCP Server

Architecture

Claude Code hooks ─┐
OpenClaw watcher ──┼─▶ POST /events ─▶ RAW: append-only JSONL file tree (permanent)
backfill ──────────┘        │
                            ▼  chapter close (sweep: idle 15min / size cap)
                     distiller (LLM) ─▶ DISTILLED: summaries + reconciled facts
                            ▼
                     INDEX: SQLite FTS5 + local embeddings (fully rebuildable)
                            ▼
        card (SessionStart) · top-ups (per prompt) · MCP tools · CLI

Layer 1 — raw. Plain JSONL files under ~/.memhippo/raw/YYYY/MM/DD/HH/ (UTC), one file per source+session per hour. Append-only: nothing ever rewrites or deletes them. Any tool ever written can grep this tree.

Layer 2 — distilled. Per-session five-field summaries (request / investigated / learned / completed / next steps) and durable facts with provenance links back to their source sessions. Facts are reconciled semantically and never destructively: a new fact that supersedes an old one flips a status flag and leaves a pointer — old text is never rewritten or deleted, and the full supersession history stays queryable.

Layer 3 — index. SQLite (WAL) holding full-text indexes over both layers, fact embeddings (local MiniLM — no cloud), session bookkeeping, and the job queue. The entire database is derived state: memhippo reindex rebuilds it from the file tree.

The components:

• memhippod — a single daemon on 127.0.0.1:7337, the sole writer of both the raw tree and the database. Everything else talks to it over HTTP.

• Hooks — six tiny bundled scripts wired into Claude Code's hook events, POSTing events to the daemon. Governing rule: a hook may never hurt a session — short timeouts, every error swallowed, always exit 0, a hard watchdog.

• OpenClaw watcher — a poller inside the daemon that tails OpenClaw's session files, using idle-gap windowing to close synthetic sessions for distillation.

• MCP server — exactly four tools exposing memory to any MCP-speaking agent.

• memhippo CLI — ops verbs plus human query commands over both layers.

Quickstart

Requires Node >= 20. Install memhippo from npm (no cloning, no build step) and run the first-run setup:

npm install -g memhippo

# First-run setup: wires the six Claude Code hooks into ~/.claude/settings.json,
# initializes the default herd (herd/default) on a fresh home, installs the
# hourly rsync safety net (macOS only), and starts the daemon.
# --dry-run first to see the exact plan with no changes:
memhippo install --dry-run
memhippo install

# Verify
memhippo status

That's the whole story — npm i -g memhippo && memhippo install. Running a Claude Code session anywhere then checks it was captured:

memhippo sessions
memhippo search "something you said"

A brand-new install (on an empty ~/.memhippo) initializes a herd on first run: it writes the .herd-root marker and seeds herd/default/hippo.json (port 7337), with models/ hoisted to the herd root and shared by every hippo. So memhippo --hippo <name> and memhippo herd work from the start, and the live store resolves as the default hippo.

An existing pre-herd ~/.memhippo — a bare single-store home from before the herd layout (memhippo.db, raw/, logs/ directly under it, no .herd-root) — is never auto-promoted: memhippo install refuses it and prints the operator cutover checklist (stop the daemon, write .herd-root, move the store into herd/default, hoist models/, seed hippo.json, restart) rather than silently relocating the runtime path under your live data. See docs/design.md for the herd layout and how to add more named stores later.

To ingest your existing Claude Code history:

memhippo backfill --dry-run   # see what would be ingested
memhippo backfill

To register the MCP server with a client, point it at memhippo mcp (stdio transport).

If you'd rather build from a checkout (contributors, or pinning a branch), the npm i -g path above won't work without a published package:

git clone https://github.com/memhippo/memhippo && cd memhippo
npm install
npm run build        # compiles dist/ — REQUIRED before hooks can resolve
npm link             # puts `memhippo` and `memhippod` on your PATH
memhippo install

The one gotcha: memhippo install expects the bundled hook scripts under dist/hooks/*.mjs. After a fresh checkout you must npm run build first, or the installer refuses (it would otherwise wire settings.json to scripts that don't exist). The npm package ships that build prebuilt, so the global-install path never hits this.

What gets installed, and the binary dependencies

• memhippo (the CLI) and memhippod (the daemon) land on your PATH.

• better-sqlite3 is a native module. The published npm package ships prebuilt binaries for common platforms/architectures, so a clean npm i -g memhippo just works on a fresh machine with no compiler. If you're on an unsupported platform (or a very new Node), npm will try to compile it from source — that needs a C++ toolchain (Python + make + a C++ compiler, same as building any native Node addon). This is the one real "build toolchain" requirement, and it only applies off the prebuilt matrix.

• transformers.js / MiniLM — the semantic (embedding) top-ups need a local embedding model, Xenova/all-MiniLM-L6-v2 (~25MB of ONNX weights). It is not in the npm tarball; it's fetched from the Hugging Face Hub on first use (only the first time a semantic top-up actually fires), then cached under ~/.memhippo/models (or $MEMHIPPO_HOME/models) for all later runs. Offline? The daemon still runs and captures/serves memory — it simply falls back to BM25-only scoring and skips semantic top-ups until the model can be fetched. The verbatim raw archive and distillation never depend on it.

Distillation (the LLM step that turns captured conversations into facts and summaries) requires the Claude Code / Claude Agent SDK credentials already on your machine.

New here? docs/tutorial.md is a guided walkthrough of every command with real captured output, running against a demo corpus shipped in this repo — you can follow it before memhippo has captured anything of yours.

The three retrieval tiers

Tier 1: the orientation card. At SessionStart, the hook fetches a precomputed card (~2,000 characters): top global facts, the current project's facts and last session's next-steps, recent session one-liners, and a pointer to the search tools. A cache read — no LLM, sub-100ms — rebuilt lazily after each distillation.

Tier 2: threshold-gated top-ups. On each user prompt, the daemon scores the prompt against facts and summaries using a hybrid of BM25 rank and embedding cosine similarity. Only matches clearing a threshold (0.55) inject, capped at 500 characters, deduplicated per session, at most four per session. Deliberately silent-leaning: a missed top-up is recoverable via the tools; a noisy one erodes trust.

Tier 3: pull. Four MCP tools teaching agents a search-then-fetch protocol:

Every ambient claim is traceable: facts carry provenance to session IDs, and raw hits carry file:line receipts into the archive.

Trust properties

• Local only. The daemon binds 127.0.0.1. Nothing leaves the machine except distillation calls to the Claude API.

• Raw is sacred. Append-only, verbatim. No code path rewrites or deletes raw files.

• Never-destructive facts. Supersession is a status flip plus a pointer; fact text is never updated or deleted.

• Everything else is disposable. The database is rebuildable from the file tree; losing it loses nothing permanent.

• Single writer. Only the daemon writes; the CLI's offline fallback is provably read-only.

• Self-observation is fenced. The distiller's own LLM sessions are triple-guarded (SDK persistence off, working-directory isolation, prompt-signature exclusion in backfill) so the system never captures its own distillation prompts as memories.

CLI tour

memhippo status                 daemon health, pid, event/session counts
memhippo start / stop / logs    daemon lifecycle
memhippo search <query>         FTS across raw + distilled layers
memhippo sessions               list captured sessions
memhippo show <session-db-id>   replay a session's raw events
memhippo projects               distinct projects with session/fact counts and last activity
memhippo conversations          human list of conversations, newest first
memhippo read <n|id-prefix>     render a conversation as dialogue (paged)
memhippo summary <n|id-prefix>  the distilled 5-field summary
memhippo last                   shorthand for 'read 1'
memhippo facts                  active facts, or one fact's supersession history
memhippo me                     the global facts memhippo knows about you, in full
memhippo card                   print the ambient orientation card
memhippo distill <id>           enqueue a manual distill job
memhippo threads                list threads (id, status, last active, request one-liner)
memhippo threads merge <a> <b>  merge thread <b> (loser) into <a> (survivor); folds summaries
memhippo threads split <id> <t> split a thread at <t> (ISO date/time or epoch ms)
memhippo consolidate --run      enqueue a consolidation pass (merge/split/dormancy; --project scopes it)
memhippo consolidate --report   show the latest consolidation pass report
memhippo grep <pattern>         regex straight over the raw file tree
memhippo import <jsonl>         POST each line as an event
memhippo backfill               ingest historical Claude Code transcripts
memhippo reindex                rebuild the search index from the raw tree
memhippo install / uninstall    wire/remove Claude Code hooks
memhippo mcp                    run the MCP server over stdio

Add --json to any query command for machine-readable output. Query commands prefer the daemon but fall back to a direct read-only view of the local database when it's down.

For a guided walkthrough of these commands with real captured output, see docs/tutorial.md.

Environment reference

Development

npm run build       # tsc + esbuild hook bundles (tests exercise dist/)
npm run typecheck
MEMHIPPO_SKIP_MODEL=1 npm test

Tests run against temp data dirs and ephemeral ports; they never touch ~/.memhippo or a running daemon. MEMHIPPO_SKIP_MODEL=1 skips the one test that downloads the local embedding model; MEMHIPPO_REAL_LLM=1 enables the (off-by-default) tests that make real LLM calls.

See docs/design.md for the design notes and docs/roadmap.md for what's next.

License

MIT