Provides long-term, local-first memory for coding agents to prevent repetitive mistakes and maintain context across different AI tools.
Also known as kitfunso/hippo-memory
- Stars
- 792
- Tools
- —
- Downloads, 30 days
- —
- Latest version
- —
- Last commit
- Nov 15, 2026
- License
- MIT
What is Hippo MCP?
Hippo provides long-term, local-first memory for coding agents to prevent repetitive mistakes and maintain context across different AI tools.
Summary generated from the project's README
About Hippo MCP server
Hippo provides long-term, local-first memory for coding agents to prevent repetitive mistakes and maintain context across different development tools. It functions as a centralized intelligence layer that connects tools like Cursor, Claude Code, Codex, and OpenCode by storing information in a local SQLite database. This approach ensures your proprietary data remains on your machine while allowing memories to travel with you regardless of which AI client you use for a specific task.
Users set up the system by installing the package via npm and running the hippo init command within a project. This process creates a .hippo directory and installs necessary hooks for detected agents. The system uses BM25 for search out of the box without requiring network calls, though users can optionally install embeddings using local Transformers.js or API-based providers like OpenAI. It features a unique learning mechanism where memories strengthen with use and decay or rank lower if marked as incorrect, helping agents learn from outcomes rather than just storing text.
What you can do with it
- 1Preventing recurring coding errorsInstruct the agent to remember a specific failure so it does not repeat the same mistake in future sessions.
- 2Maintaining context across different toolsAsk the AI to recall project-specific rules or history learned in a different editor or agent.
- 3Managing incorrect or outdated informationTell the system to replace an old fact with a new one to ensure the agent uses the correct information.
Written from the project's README. Every use case is checked against a quote from it.
How to install Hippo MCP
Formats verified 10 Nov 2026Add to CursorAdd to GooseInstall Hippo MCP in Claude Code
$ claude mcp add hippo-memory -- npx -y hippo-memoryInstall Hippo MCP in Cursor
~/.cursor/mcp.json
{
"mcpServers": {
"hippo-memory": {
"command": "npx",
"args": [
"-y",
"hippo-memory"
]
}
}
}Install Hippo MCP in VS Code
.vscode/mcp.json
{
"servers": {
"hippo-memory": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"hippo-memory"
]
}
}
}Install Hippo MCP in VS Code CLI
$ code --add-mcp '{"name":"hippo-memory","type":"stdio","command":"npx","args":["-y","hippo-memory"]}'Install Hippo MCP in Claude Desktop
claude_desktop_config.json
{
"mcpServers": {
"hippo-memory": {
"command": "npx",
"args": [
"-y",
"hippo-memory"
]
}
}
}Install Hippo MCP in Codex
$ codex mcp add hippo-memory -- npx -y hippo-memoryInstall Hippo MCP in Codex config.toml
~/.codex/config.toml
[mcp_servers.hippo-memory] command = "npx" args = ["-y", "hippo-memory"]
Install Hippo MCP in Gemini CLI
$ gemini mcp add -s user hippo-memory npx -- -y hippo-memoryInstall Hippo MCP in Gemini settings.json
~/.gemini/settings.json
{
"mcpServers": {
"hippo-memory": {
"command": "npx",
"args": [
"-y",
"hippo-memory"
]
}
}
}Automated checks
Ran Nov 12, 2026Full report →Passed our automated checks. That is not a security audit: read the code and give the server the narrowest access it needs. How checks work
- Source repository linked and reachablePass
- Open source license (OSI)Pass
- Commit or release in the last yearPass
- Package name not close to a popular packagePass
- Remote endpoint uses HTTPSNot checked
- Destructive tools are labelledNot checked
- No hidden instructions to the modelPass
- No critical advisory in the package or its dependenciesNot checked
README
View on GitHub🦛 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.
- Correct your agent once, and with hippo it repeats that mistake about half as often. Z0 round 3, real Claude Code sessions on 29 repositories, hippo against built-in memory alone: 11 repeats in 100 against 21, 2 to 4 tasks after the correction, at no extra cost (ratio 1.006 [0.964, 1.049]). With no memory the agent repeats it 83 times in 100. Over every first chance to repeat, the pre-registered read is 14.9 points fewer [5.5, 24.3], adjusted p 0.006, against a full-win line of 15. The gain is the same with lesson capture switched off, so round 4 tests how much of it the stored lessons carry. (result; round 2, on 16 repositories, was inconclusive at -8.9 points)
- 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.fetchspy that throws on call, not a hardcoded zero. Recall makes no network call by default. One default does:hippo sleepsends memory text to Anthropic for fact extraction whenANTHROPIC_API_KEYis 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.jsonturns 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 errorand 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 askind='raw'memories with full provenance and GDPR-correct deletion. - Knows where every memory came from. Every row carries
kind,scope,owner, andartifact_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. A step-by-step version is on the website: hippo-memory.com/quickstart.
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 daily 6:15am run, a crontab line on Linux and macOS or a scheduled task on Windows. It adds no block to any repo's CLAUDE.md or AGENTS.md. --no-hooks, --no-schedule and --no-learn leave out the hooks, the daily run and the history import.
hippo init --scan ~
After setup, hippo sleep runs when a Claude Code or OpenCode session ends, and in the daily 6:15am job for every project. Codex runs it at session end only if you installed its wrapper. It does five things:
- Learns from today's git commits
- Imports what your coding agents remember, about this project and about you (Agent memories)
- Consolidates memories (decay, merge, prune)
- Deduplicates identical memories, keeping the stronger copy
- Shares high-value lessons to a global store so they surface in every project
# Manual usage
hippo remember "FRED cache silently dropped the tips_10y series" --tag error
hippo recall "data pipeline issues" --budget 2000
Full release history: CHANGELOG.md · GitHub Releases
What hippo init changes
Run hippo init inside one project. This is everything it writes, in the project and on your machine:
- The project's store. A
.hippo/folder: SQLite plus markdown mirrors. On the first run in a git repo it learns lessons from the last 30 days of commits. - Instruction files. A block between
<!-- hippo:start -->and<!-- hippo:end -->in the project'sCLAUDE.mdorAGENTS.md, only if that file already exists. Codex, Cursor, OpenClaw, OpenCode and Pi readAGENTS.md. - Claude Code, when the project has
CLAUDE.mdor.claude/settings.json: 7 hook entries in~/.claude/settings.json, one each on SessionEnd, UserPromptSubmit, PreCompact, PostCompact and PostToolUseFailure and two on SessionStart. Framework Integrations says what each one runs. - OpenCode, when the project has
.opencode/oropencode.json: a plugin at~/.config/opencode/plugins/hippo.ts. - Codex, when the project has
AGENTS.mdor.codexand Codex is installed ($CODEX_HOME, else~/.codex, exists): 2 hook entries in Codex'shooks.json, one on UserPromptSubmit that sends your pinned memories plus up to 5 that match the prompt with every prompt and one on SessionStart after a compaction. Codex runs them only after you trust them once in/hooks. Init also printshippo hook install codex, the opt-in that wraps the Codex launcher to capture sessions;hippo hook uninstall codexremoves hippo's hooks and the wrapper. - A daily run at 6:15am, one per machine: a crontab line on Linux and macOS, a scheduled task named
hippo-daily-runneron Windows. It runshippo learn --git --days 1and thenhippo sleepin every project listed in~/.hippo/workspaces.json, and init adds this project to that list. - Agent memories. On every run, the notes your coding agents keep about this project go into its store, and the ones about you go into the global store. Agent memories lists what is read.
cd my-project
hippo init
# Initialized Hippo at /my-project/.hippo
# Directories: buffer/ episodic/ semantic/ conflicts/
# Files: hippo.db stats.json
# Auto-installed claude-code hook in CLAUDE.md
# Auto-installed hippo session-end SessionEnd hook in claude-code settings
# (one line per hook entry)
# Scheduled machine-level daily runner (6:15am) via crontab
To leave parts out: --no-hooks skips the instruction files and hooks, --no-schedule the daily run, and --no-learn the git history and agent memory import. HIPPO_SKIP_AUTO_INTEGRATIONS=1 skips the same files and hooks that --no-hooks does, and HIPPO_SKIP_SCHEDULE=1 skips the daily run as --no-schedule does.
Agent memories
Most coding agents now keep their own notes between sessions. Hippo reads them, whatever the tool, so what one agent learned reaches the others. It reads files only and never writes to another tool's folders.
When: hippo init (every run), init --scan, init --global, hippo setup, every hippo sleep and the daily run. At session end a folder with its own store gets it through sleep; a folder without one sends its project's notes to the global store, marked with the project's name. After a Claude Code compaction, the session's own notes folder is read as well.
What is read, per tool (each tool's own environment variables and settings decide where its home is):
- Claude Code: the project's auto memory notes under
~/.claude/projects/<project>/memory/(front matter required,MEMORY.mdskipped), and theautoMemoryDirectoryfolder from your user settings. - Codex: the User Profile, preferences and tips in
~/.codex/memories/memory_summary.md. - Gemini CLI: the "Gemini Added Memories" section of
~/.gemini/GEMINI.md, and the project's auto memory folder when that feature is on. - GitHub Copilot Chat in VS Code: the memory tool's user memories and the repository memories of this project's workspace.
- OpenClaw: the workspace's
MEMORY.md. - Qwen Code: the project's auto memory folder and your user memories.
Each imported memory follows its note. It stays while the note exists, is replaced when the note changes, and is set aside as dormant when the note is deleted (hippo dormant lists it and can restore it). A note shorter than 10 characters, one that looks like it holds a secret (an API key, a password, an auth header or a token), and one whose text you rejected with hippo reject are skipped. Email addresses are stored masked, and notes are cut at 1,500 characters.
Not read: Windsurf (the file format is not documented, and Cascade reached end of life on 1 July 2026); Cursor, Copilot CLI and GitHub's Copilot Memory (the memories live on the vendor's servers); Kiro (the local store is not documented); Cline and Roo memory banks (files in the repository, which hippo import --markdown covers); Amp, Aider, Continue, OpenCode and pi (no memory feature found).
hippo import --agents runs the import by hand; in a folder without a store it does what session end does there. With --dry-run it shows each tool's home, the folders found and what would change, and writes nothing. To choose tools, set "agentMemories": { "tools": ["claude-code", "codex"] } in .hippo/config.json ([] turns the import off), or HIPPO_AGENT_MEMORY_TOOLS=claude-code,codex in the environment (none turns it off), which wins over config.
Cross-Tool Import
Your memories shouldn't be locked inside one tool. Hippo pulls them in from anywhere.
# ChatGPT memory export
hippo import --chatgpt memories.json
# Claude's CLAUDE.md (skips existing hippo hook blocks)
hippo import --claude CLAUDE.md
# Cursor rules
hippo import --cursor .cursorrules
# Any markdown file (headings become tags)
hippo import --markdown MEMORY.md
# Any text file
hippo import --file notes.txt
All import commands support --dry-run (preview without writing), --global (write to ~/.hippo/), and --tag (add extra tags). Duplicates are detected and skipped automatically.
Conversation Capture
Extract memories from raw conversation text. No LLM needed: pattern-based heuristics find decisions, rules, errors, and preferences.
# Pipe a conversation in
cat session.log | hippo capture --stdin
# Or point at a file
hippo capture --file conversation.md
# Preview first
hippo capture --file conversation.md --dry-run
Rules from follow-up turns (opt-in, uses a model)
Word patterns pin a later turn only when it holds a rule word (never, always, must, make sure) or a preference word that names code or limits a choice. Any other statement that names code or limits a choice, such as "Run the tests with pnpm test:unit, not the bare pnpm test", stays an unpinned note that only a matching prompt or hippo recall brings back. Patterns store nothing from "That file is generated, so changes belong in the template it comes from." With {"capture": {"followUpRules": "model"}} in .hippo/config.json and ANTHROPIC_API_KEY set, a session capture also asks a model which of your sentences state a lasting rule. Hippo stores those sentences, in your own words, as pinned rules.
- What it sends: your turns after the first one in the session, the last 20, each cut to 1,000 characters. Pasted blocks, fenced code and log lines are removed first, and secrets, email addresses and home paths are masked. The assistant's replies are never sent.
- To whom: Anthropic, with your
ANTHROPIC_API_KEY, in one call per session capture. A failed call logs one line and capture keeps its pattern rules. A session with no project never makes the call. - On and off: the default is
"off". Set"model"to turn it on; set"off"again, or unset the key, to turn it off. - A capture after each reply (
--turn, as VS Code's agent mode runs) never calls the model, so those runtimes gain little.
Slack ingestion (E1.3)
Hippo accepts Slack Events API webhooks at POST /v1/connectors/slack/events. Configure SLACK_SIGNING_SECRET (validated on every request) and point Slack at https://<your-host>/v1/connectors/slack/events. Messages land as kind='raw' memories with slack://team/channel/ts provenance and a slack:public:Cxxx or slack:private:Cxxx scope. Source deletions are honored (GDPR). To rotate the secret, put the new one in SLACK_SIGNING_SECRET and the old one in SLACK_SIGNING_SECRET_PREVIOUS, and set SLACK_SIGNING_SECRET_PREVIOUS_UNTIL to an ISO date (2026-12-01 means 00:00 UTC that day) or timestamp. From then on requests signed with the old secret are refused, with one warning in the log. Left unset, the old secret works for as long as it stays in the environment.
Backfill an existing channel: SLACK_BOT_TOKEN=xoxb-... hippo slack backfill --channel C0000. Inspect malformed events: hippo slack dlq list.
Multi-workspace deployments populate slack_workspaces (team_id, tenant_id) to route events per tenant; single-workspace falls back to HIPPO_TENANT.
Active task snapshots
Long-running work needs short-term continuity, not just long-term memory. Hippo can persist the current in-flight task so a later continue has something concrete to recover.
hippo snapshot save \
--task "Ship SQLite backbone" \
--summary "Tests/build/smoke are green, next slice is active-session recovery" \
--next-step "Implement active snapshot retrieval in context output"
hippo snapshot show
hippo context --auto --budget 1500
hippo snapshot clear
hippo context --auto prints the active task snapshot before long-term memories when the calling session saved it, so agents get both the immediate thread and the deeper lessons. A snapshot from another session prints as one line that names the command that shows it.
Session event trails
Manual snapshots are useful, but real work also needs a breadcrumb trail. Hippo can now store short session events and link them to the active snapshot so context output shows the latest steps, not just the last summary. The trail prints for the calling session's own snapshot; for another session's, the command in the pointer line prints it.
hippo session log \
--id sess_20260326 \
--task "Ship continuity" \
--type progress \
--content "Schema migration is done, next step is CLI wiring"
hippo snapshot save \
--task "Ship continuity" \
--summary "Structured session events are flowing" \
--next-step "Surface them in framework hooks" \
--session sess_20260326
hippo session show --id sess_20260326
hippo context --auto --budget 1500
Hippo mirrors the latest trail to .hippo/buffer/recent-session.md so you can inspect the short-term thread without opening SQLite.
Session handoffs
When you're done for the day (or switching to another agent), create a handoff so the next session knows exactly where to pick up:
hippo handoff create \
--summary "Finished schema migration, tests green" \
--next "Wire handoff injection into context output" \
--session sess_20260403 \
--artifact src/db/index.ts
hippo handoff latest # show the most recent handoff
hippo handoff show 3 # show a specific handoff by ID
hippo session resume # re-inject latest handoff as context
The per-prompt hook (Claude Code and Codex) prints only your own session's handoff. It no longer prints another session's handoff, not even as a pointer. To pick up another session's work, run hippo context --auto.
Hippo MCP questions
How do I add Hippo MCP to Claude Code?
Run claude mcp add hippo-memory -- npx -y hippo-memory in your terminal. Add --scope user to make it available in every project.
How do I add Hippo MCP to Cursor?
Open ~/.cursor/mcp.json and add the server under mcpServers, using the Cursor config shown in the install section above.
What tools does Hippo work with?
Hippo works with Claude Code, Codex, Cursor, OpenClaw, OpenCode, Pi, and any MCP client.
How is the memory stored?
Memories are kept in a local SQLite store on your machine, accompanied by markdown mirrors that are human-readable and git-trackable.
Does Hippo require a network connection for search?
No, search uses BM25 out of the box with no model or network calls required; embeddings are an optional installation.
How can I prevent an agent from repeating a mistake?
You can mark a memory as wrong to lower its rank, or use the 'hippo supersede' command to remove an old fact from recall.