git:20260928.575b1fc to git:20260928.0195e54

5 added, 5 removed. Audit A to A.

# 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: in hippo's mechanism audit, outcome marks, supersession and retrieval strengthening measured helping; decay and sleep have not been shown to make recall better. The published numbers measure retrieval, not whether agents do better work with hippo.

+ What is measured: in hippo's mechanism audit, outcome marks and retrieval strengthening measured helping; supersession is not measured yet; decay and sleep have not been shown to make recall better. The published numbers measure retrieval, not whether agents do better work with hippo.

- Retrieval, corpus first: on LongMemEval-S (500 questions, each scored against its own ~48-session haystack), using the benchmark scripts rather than `hippo recall`, best of five settings, R@5 is 98.0% with the free local MiniLM embedder and 99.8% with voyage-3-large (opt-in, paid). On the older LongMemEval oracle split with pooled retrieval, BM25 only and no embeddings (v0.11), R@5 was 74.0%.

+ Retrieval, corpus first: on LongMemEval-S (500 questions, each scored against its own ~48-session haystack), using the benchmark scripts rather than `hippo recall`, best of five settings, R@5 is 98.0% 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 a project. It creates the project's store and adds hippo's instructions to the agent files it finds there (CLAUDE.md, and AGENTS.md, which Codex, Cursor, OpenClaw, OpenCode and Pi read), plus Claude Code's session hooks. `hippo init --scan ~` registers every git repo under your home directory at once, each with a store seeded from its git history. `npx -y hippo-memory mcp` runs the MCP server without a global install.

+ Install: `npm install -g hippo-memory`, then `hippo init` in a project. It creates the project's store and adds hippo's instructions to the agent files it finds there (CLAUDE.md, and AGENTS.md, which Codex, Cursor, OpenClaw, OpenCode and Pi read), plus Claude Code's session hooks. `hippo init --scan ~` registers every git repo under your home directory at once, each with a store seeded from its git history; it installs Claude Code's hooks and the OpenCode plugin but patches no instruction files. `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, Cline and Claude Desktop

+ - [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 coding agent with its own memory; hippo is memory for the agents you already use

+ - [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 table](https://github.com/kitfunso/hippo-memory#comparison): hippo against nine other memory tools, row by row

## 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