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.

Architecture

Claude Code hooks ─┐
OpenClaw watcher ──┼─▶ POST /events ─▶ RAW: append-only JSONL file tree (permanent)
backfill ──────────┘        │
                            ▼  session end
                     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. Distillation requires the Claude Code / Claude Agent SDK credentials already on your machine.

git clone https://github.com/memhippo/memhippo && cd memhippo
npm install
npm run build
npm link          # puts `memhippo` and `memhippod` on your PATH

# Wire the six hooks into ~/.claude/settings.json, install the hourly rsync
# safety net (launchd), and start the daemon. --dry-run first to see the plan:
memhippo install --dry-run
memhippo install

# Verify
memhippo status

Then run a Claude Code session anywhere and check it was captured:

memhippo sessions
memhippo search "something you said"

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).

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:

Tool	Purpose
search_memory	Query with optional filters; returns a compact index (IDs, titles, scores — never full content)
timeline	Chronological context around a hit
get_details	Full content for chosen IDs, including raw-archive receipts as file:line pointers
remember	Explicit writes routed through the fact store

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 card                   print the ambient orientation card
memhippo distill <id>           enqueue a manual distill job
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.

Environment reference

Variable	Default	Purpose
MEMHIPPO_HOME	~/.memhippo	Data dir (raw tree, db, logs)
MEMHIPPO_PORT	7337	Daemon port (localhost only)
MEMHIPPO_DISTILL_MODEL	sonnet	Model for session distillation
MEMHIPPO_RECONCILE_MODEL	haiku	Model for fact-reconcile verdicts
MEMHIPPO_DISTILL_CONCURRENCY	3	Max distill LLM calls in flight
MEMHIPPO_DISTILL_GRACE_MS	3600000	Idle grace before a session is considered ended
MEMHIPPO_SWEEP_INTERVAL_MS	600000	Stale-session sweep interval
MEMHIPPO_MAX_FACTS_PER_SESSION	60	Per-session fact budget
MEMHIPPO_MAX_RECONCILE_CALLS_PER_SESSION	40	Per-session reconcile-LLM budget
MEMHIPPO_DEDUP_WINDOW_MS	120000	Ingest content-hash dedup window
MEMHIPPO_TOPUP_THRESHOLD	0.55	Min hybrid score for a mid-session top-up
MEMHIPPO_OPENCLAW_DIR	~/.openclaw/agents	OpenClaw session dir to watch
MEMHIPPO_OPENCLAW_IDLE_MS	1800000	Idle gap that closes an OpenClaw window
MEMHIPPO_OPENCLAW_POLL_MS	60000	OpenClaw poll interval
MEMHIPPO_PAGER / MEMHIPPO_NO_PAGER	less -R / unset	Pager for read/last
MEMHIPPO_HOOK_DEBUG	unset	Hooks flush buffered debug output to stderr
MEMHIPPO_SKIP_MODEL	unset	Tests: skip the local embedding-model download
MEMHIPPO_REAL_LLM	unset	Tests: enable gated real-LLM smoke tests

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