llms.txt@website/public git:20260929.57c87f2A

Immutable. This exact content never changes and is served at /api/v1/blob/95758175d44686c0.

# hippo-memory

> hippo is an open-source (MIT), local-first memory layer for AI agents. Claude Code, Codex, Cursor, OpenClaw, OpenCode, Pi and any MCP client share one SQLite store on your machine. A memory marked wrong drops out of the top results, a newer fact supersedes the old one, memories you use get stronger, and every memory records where it came from.

hippo is the npm package `hippo-memory`; the CLI is `hippo` and `hippo mcp` is its MCP server. It needs Node.js 22.16+ and has zero runtime dependencies. Recall uses BM25 out of the box; hybrid search with a local or an API embedder is optional, and nothing is auto-installed. 3,500+ tests run against a real database, with no module mocks and no mocked store.

Where data lives: `.hippo/hippo.db` in each project, plus a global store in `~/.hippo/`, with markdown mirrors you can read and commit. Recall makes no network call by default. Text goes to an outside provider only through features that use one: an API embedder, the Jev or LLM reranker, `hippo refine`, and the fact extraction `hippo sleep` runs through Anthropic's API when `ANTHROPIC_API_KEY` is set (`{"extraction":{"enabled":false}}` in `.hippo/config.json` turns that off).

What is measured: decay and sleep are design choices. In hippo's mechanism audit, decay had no measurable effect against decay switched off (-0.7 points [-1.4, 0.1] on a 20-session synthetic test, too short for a 365-day half-life to act), and sleep lowered LongMemEval hit@5 by 3.6 points [-5.8, -1.4] under the audit's declared scorer (https://github.com/kitfunso/hippo-memory/blob/master/docs/evals/2026-09-23-mechanism-audit-round2-result.md). On that synthetic test, outcome marks and retrieval strengthening measured helping; supersession is not measured yet. hippo has not been shown to improve agent task success: the published numbers measure retrieval.

Retrieval, corpus first: on LongMemEval-S (500 questions, each scored against its own ~48-session haystack), `hippo recall` on a default install puts an answer session in its top 5 for 85.6% of questions inside its default 4,000-token budget, and 87.6% with the optional MiniLM embedder. With the budget lifted it scores 96.8%, but then it returns every candidate, so that figure measures the ranking (https://github.com/kitfunso/hippo-memory/blob/master/docs/evals/2026-09-28-recall-cli-longmemeval-result.md). The benchmark scripts, which are not `hippo recall`, reach R@5 98.0% at their best of five settings with the free local MiniLM embedder, and 99.8% with voyage-3-large (opt-in, paid), counting a hit when any answer session is in the top 5. Counting a hit only when every answer session is in the top 5, over the 470 questions that have an answer, MiniLM scores 86.8 to 88.5%. On the older LongMemEval oracle split with pooled retrieval, BM25 only and no embeddings (v0.11), R@5 was 74.0%.

Install: `npm install -g hippo-memory`, then `hippo init` in one project. It creates the project's `.hippo/` store, seeded from the last 30 days of git history, and adds hippo's instructions to the agent files already there (CLAUDE.md, and AGENTS.md, which Codex, Cursor, OpenClaw, OpenCode and Pi read); it never creates either file. When the project uses Claude Code it adds 7 hook entries to `~/.claude/settings.json`, and when it uses OpenCode, a plugin in `~/.config/opencode/plugins/`. It sets up a daily 6:15am run (crontab on Linux and macOS, a scheduled task on Windows), and its first run imports the project's Claude Code auto memory. `--no-hooks`, `--no-schedule` and `--no-learn` leave those parts out. An optional second step sets up many repos at once: every git repo in a folder and up to three levels below it gets its own store, seeded from a year of its git history, plus the same user-level hooks and the daily run, and no instruction file is patched. That command is `hippo init --scan ~`. `npx -y hippo-memory mcp` runs the MCP server without a global install.

## Docs

- [README](https://github.com/kitfunso/hippo-memory#readme): install, agent setup, CLI reference, how memory works, comparison, benchmarks and FAQ
- [README as one text file](https://hippo-memory.com/llms-full.txt): the full README in markdown, with absolute links
- [Agent install guide](https://github.com/kitfunso/hippo-memory/blob/master/llms-install.md): for an AI agent installing hippo: install, wire it in, verify with `hippo doctor --json`
- [Quickstart](https://hippo-memory.com/quickstart/): install, `hippo init` and the memory loop
- [How it works](https://hippo-memory.com/how-it-works/): decay, strengthening, outcome marks, supersession, conflicts and sleep, with what each one measured
- [FAQ](https://hippo-memory.com/faq/): the README FAQ, 14 questions

## Agents

- [Claude Code](https://hippo-memory.com/claude-code/): memory between sessions through a CLAUDE.md block and session hooks
- [Cursor](https://hippo-memory.com/cursor/): memory between sessions through the MCP server and the project's AGENTS.md
- [Codex CLI](https://hippo-memory.com/codex/): memory across sessions through AGENTS.md, with optional session capture
- [MCP server](https://hippo-memory.com/mcp/): `hippo mcp`, 13 tools over stdio for Claude Code, Cursor, Windsurf (now Devin Desktop), Cline and Claude Desktop
- [Pi extension](https://github.com/kitfunso/hippo-memory/tree/master/extensions/pi-extension): session hooks for Pi

## Compare

- [hippo vs mem0](https://hippo-memory.com/vs/mem0/): a local, open-source mem0 alternative, feature by feature
- [hippo vs Zep](https://hippo-memory.com/vs/zep/): Zep is a managed service and its self-hosted Community Edition is deprecated
- [hippo vs Letta](https://hippo-memory.com/vs/letta/): Letta Code is a stateful agent harness with its own memory; hippo is memory for the agents you already use
- [CLAUDE.md vs memory](https://hippo-memory.com/vs/claude-memory/): what CLAUDE.md, Claude Code's auto memory and hippo each hold
- [Comparison tables](https://github.com/kitfunso/hippo-memory#comparison): hippo against nine other memory tools, plain facts first, then design bets

## Benchmarks

- [Benchmarks](https://hippo-memory.com/benchmarks/): LongMemEval retrieval, LoCoMo evidence recall and the Jev reranker, each with its setting and its limits
- [LongMemEval reproduction](https://github.com/kitfunso/hippo-memory/blob/master/docs/evals/2026-09-23-longmemeval-reproduction.md): how to re-measure the MiniLM figure
- [Eval index](https://github.com/kitfunso/hippo-memory/blob/master/docs/evals/README.md): every published measurement, including failed runs and one retracted claim

## Optional

- [Teams](https://hippo-memory.com/teams/): Enterprise hippo, in development: shared memory run inside your network
- [npm package](https://www.npmjs.com/package/hippo-memory): versions and install
- [Changelog](https://github.com/kitfunso/hippo-memory/blob/master/CHANGELOG.md): release history
- [License](https://github.com/kitfunso/hippo-memory/blob/master/LICENSE): MIT