🦛 Hippo

Stop re-teaching your agent.

Make your agent's memory work like a brain. Hippo is long-term memory for coding agents. It's a critical layer for your AI harness that connects across your different tools (Cursor, Claude Code, Codex). It keeps your proprietary data completely local, and it actually learns over time. By strengthening memories each time they are recalled, Hippo preserves what works, lets mistakes decay, and continuously compounds your agents' intelligence.

Hippo keeps your coding agents' memories in a SQLite store on your machine, with markdown mirrors you can read and commit. Search is BM25 out of the box, with no model and no network call; embeddings are an optional install. hippo init installs hooks for Claude Code and OpenCode, adds 2 hooks to Codex's hooks.json when Codex is installed (Codex runs them once you trust them in /hooks), and adds instructions to an existing AGENTS.md for Codex, Cursor, OpenClaw and Pi. Any MCP client can connect. Mark a memory wrong and it ranks lower; run hippo supersede and the old fact leaves recall. Zero runtime deps.

Install it, then run hippo init inside one project. Init creates the project's .hippo/ store and adds a block to the CLAUDE.md or AGENTS.md already there. On your machine it adds hooks for the agents it finds, such as Claude Code's in ~/.claude/settings.json, and a daily 6:15am run. What hippo init changes lists all of it and the flags that skip each part.

npm install -g hippo-memory && hippo init

Setting up every git repo under a folder in one go is a second step. The Quick start says what it changes, then gives the command.

Package installation alone does not enable automatic preservation on every agent. Complete the documented setup and required host trust; capture and compaction coverage depend on the integration.

Having an AI agent install it? Point it at llms-install.md: it installs, wires hippo into the agents it finds, and verifies with hippo doctor.

Works with:    Claude Code, Codex, Cursor, OpenClaw, OpenCode, Pi, any MCP client
Imports from:  ChatGPT, Claude (CLAUDE.md), Cursor (.cursorrules), Slack, markdown
Storage:       SQLite backbone with markdown mirrors. Git-trackable, human-readable.
Dependencies:  Zero runtime deps. Node.js 22.16+. Optional embeddings: bring-your-own local Transformers.js (`npm i @huggingface/transformers`, or legacy `@xenova/transformers`) or an opt-in API embedder (OpenAI/Voyage/Cohere). Nothing is auto-installed.

Contents: Why · Receipts · Quick start · Agent setup · MCP server · How it works · Features · CLI · Comparison · Benchmarks · FAQ · Contributing

Why this exists

Most "AI memory" systems save everything and search later. That's storage with search on top. A note that turned out wrong ranks the same as one that held up, and an old fact sits beside the one that replaced it.

Hippo learns from outcomes. When a recalled memory turns out wrong, mark it bad and it drops out of the top results. Memories you keep using get stronger. Those two are the parts we measured helping retrieval, on a synthetic test (mechanism audit, round 2). When a fact changes, run hippo supersede and the old version leaves recall; we have not measured whether that helps. The design borrows from the hippocampus (decay, three layers, sleep consolidation), but that is inspiration. In our tests, decay tied with decay switched off and sleep lowered recall (Benchmarks).

It also fixes the portability problem. Your ChatGPT memories don't travel to Claude. Your .cursorrules don't travel to Codex. Hippo is one store behind every agent. CLAUDE.md, Cursor rules, ChatGPT exports, Slack history, all in one SQLite store, all queryable from any tool that speaks MCP or HTTP.

Receipts

Numbers, not adjectives. Every claim links to the benchmark or the test that proves it. Every measurement we have ever published is indexed in docs/evals/, pre-registrations kept next to their results, including the runs that failed and the one claim we retracted.

• Sequential Learning Benchmark. benchmarks/sequential-learning/. 50 tasks, 10 buried traps. Measures whether agents learn from past mistakes, not just retrieve text. v0.11.0 informal magnitude RETRACTED v1.7.9; mechanism remains shipped. See CHANGELOG.md v1.7.9 entry.
• LongMemEval oracle split, all 500 questions in one pooled store, BM25 only, no embeddings, v0.11: R@5 = 74.0% (benchmarks/README.md, scripts in benchmarks/longmemeval/). A different setup from the per-haystack results under Benchmarks, so the two are not a before and after.
• On a private 300-query developer store, R@1 0.41 to 0.62 with hippo recall "<query>" --reranker jev, the free local cross-encoder against Jev (full eval). The opt-in TypeSafe Jev reranker, off by default, about 0.0004 USD a recall. 2000-draw paired bootstrap; the margin held in 20 of 20 seeds and a permutation null reached it in 0 of 200 runs. Ranking only: three graded tests on one 150-question LongMemEval set did not show a better answer rate than the free local cross-encoder, and that negative result is in the same doc. What it buys today is a shorter context: on that set, 2 memories ranked by Jev answered as well as 5 ranked by the cross-encoder.
• Staged Slack corpus, 10 incident scenarios: recall beat transcript replay in 10 of 10 (benchmarks/e1.3/). The answers sit mid-channel by design. In every scenario hippo's top 10 results held all the answer messages, and the channel's last 10 messages held none.
• Slack connector, 1000-event ingestion smoke: 0 outbound HTTP (benchmarks/e1.3/). Proven by a globalThis.fetch spy that throws on call, not a hardcoded zero. Recall makes no network call by default. One default does: hippo sleep sends memory text to Anthropic for fact extraction when ANTHROPIC_API_KEY is set. Sleep runs at the end of every Claude Code and OpenCode session and in the daily job, so with the key set the call happens without you asking. {"extraction":{"enabled":false}} in .hippo/config.json turns that off. Opt-in features such as the Jev reranker above, the LLM reranker and the API embedders also call out.
• 3,500+ tests on a real database. No module mocks and no mocked store; only paid network calls are stubbed. Project rule. The one mocks-vs-prod divergence that bit us early is now the constraint that kept the next ten releases honest.
• 3-cluster fixture where BM25 alone cannot discriminate: dlPFC goal-conditioned cluster discrimination passes 3 of 3 queries. Full goal stack with policy weighting and lifespan-windowed outcome propagation, one query per goal; deterministic test in benchmarks/micro/results/b3-depth.json.

What it does for your agent

• Keeps errors longer. Tag a failure with --tag error and it gets twice the half-life of an ordinary memory, so the lesson is still in the store the next time a recall matches it. In Claude Code, a hook stores failed tool calls as error memories for you.
• Survives tool switches. Use Claude Code on Monday, Cursor on Tuesday, Codex on Wednesday. They all read the same .hippo/ store, so the memories come with you.
• Ingests systems of record. Slack and GitHub today (POST /v1/connectors/slack/events, POST /v1/connectors/github/events). Jira and Notion next. Webhooks land as kind='raw' memories with full provenance and GDPR-correct deletion.
• Knows where every memory came from. Every row carries kind, scope, owner, and artifact_ref. Right-to-be-forgotten is a single API call, not an audit nightmare.
• Plays nice with multi-tenant. API keys, scrypt-hashed. Audit log on every mutation. Tenant A literally cannot see tenant B's memories. Proven by negative test.

Quick start

Start in one project. What hippo init changes lists everything the second command writes.

npm install -g hippo-memory

# In a project: create its store and wire in the agents it uses
hippo init

Optional: many repos at once. Read what it changes first. hippo init --scan <folder> looks for git repos in the folder and up to three levels below it, skipping dot-folders and node_modules. Each repo gets a .hippo/ store, seeded with lessons from the last 365 days of its commits and with its agent memories, and is added to the daily run's list. For the agents it finds, it installs the same user-level hooks as hippo init: 7 Claude Code hook entries in ~/.claude/settings.json and the OpenCode plugin. It also sets up the