海马记忆系统

Auto-installed claude-code hook in CLAUDE.md

Auto-installed hippo session-end SessionEnd hook in claude-code settings

Output: "Previously observed (2026-03-10): deploy takes ~3 min"

hippo context --framing suggest

Output: "Consider: deploy takes ~3 min"

hippo context --framing assert

Output: "Deploy takes ~3 min"

```

Three modes: observe (default), suggest, assert. Choose based on how directive you want the memory to be.

---

next time an agent asks about build issues, the memory is there

```

The command runs with no shell, so each argument reaches the program as written. To run a shell line with pipes or &&, pass it as one string after --shell: hippo watch --shell "npm test && npm run build".

---

Auto-install (recommended)

hippo init detects your agent framework and patches the right config file automatically:

Init patches an instruction file only if it already exists. It also sets up a daily run and imports your coding agents' own memories; What hippo init changes lists everything.

Manual install

If you prefer explicit control:

hippo hook install claude-code   # patches CLAUDE.md + adds the 7 settings.json hook entries listed below
hippo hook install codex         # patches AGENTS.md + adds hooks to Codex's hooks.json + wraps the detected Codex launcher
hippo hook install cursor        # patches AGENTS.md
hippo hook install openclaw      # patches AGENTS.md
hippo hook install opencode      # patches AGENTS.md + installs the opencode TS plugin

This adds a ` ... ` block that tells the agent to: 1. Run hippo context --auto --budget 1500 at session start 2. Run hippo remember "<what went wrong and why>" --error the moment it finds out why something failed, never as a closing step 3. Everywhere but Claude Code, whose own auto memory does this job: run a plain hippo remember the moment it learns something that should outlive the session, leaving out secrets and personal details 4. Capture a short summary with hippo capture --stdin when the session ends, but only where no hook captures the session: Cursor, OpenClaw, OpenCode, Pi, and Codex without its wrapper

The block asks for nothing a hook already does, because each extra tool call re-reads the whole context. Re-running hippo init swaps a block an older hippo wrote for the current one, as long as nobody edited it. It leaves an edited block alone and says so, and never touches text outside the markers.

For Claude Code, it also adds 7 hook entries to ~/.claude/settings.json: - a SessionEnd hook that runs hippo sleep and then hippo capture when the session exits. Capture matches the last 20 user and 10 assistant messages of the transcript against word patterns for decisions, rules, errors and preferences. It uses no model and does not read earlier turns, so record lessons with hippo remember as you go. - a SessionStart hook that prints the previous session's consolidation log on stderr, where claude --debug shows it. When the last sleep failed or a compaction summary was set aside, it shows you one line that points to hippo doctor. - a UserPromptSubmit hook that runs hippo context --pinned-only --include-recent 5 --format additional-context every turn. It re-injects pinned memories (hippo remember <text> --pin) plus up to 5 memories that share words with your prompt. When nothing matches, it adds only the pinned ones. Since 1.55.0 this replaces the 5 newest memories, which cut the median block from 847 to 533 tokens in our eval. {"pinnedInject":{"promptRecall":false}} brings back the 5 newest, so fresh same-session lessons appear on the next prompt whatever you ask. The block is rendered without live strength percentages, so it stays byte-identical while its memories do not change, and it is sent only when it changed since the session's last prompt: an unchanged block is skipped, resent every 10 skips (pinnedInject.refreshTurns, 0 never resends) and resent after compaction. The prompt-matched memories go in a separate block that is never skipped, so they are sent on every prompt they match. {"pinnedInject":{"skipUnchanged":false}} sends the pinned block every turn as before. Opt out entirely with {"pinnedInject":{"enabled":false}} in .hippo/config.json. - a PreCompact hook that runs hippo pre-compact before the transcript gets summarized. It records the compaction in the store, saves a working-state snapshot (task/summary/next step) so mid-session compaction can't drop it, and asks the summariser to end its summary with a "Memories for hippo" list: the lessons, decisions and corrections from the session that should outlive it. The SessionEnd hook still owns extracting durable memories from the transcript. - a second SessionStart hook (matcher compact) that runs hippo compact-resume, printing that snapshot back into context right after compaction, if it is under 15 minutes old. - a PostCompact hook that runs hippo post-compact. It keeps the summary in the store with secrets scrubbed, and saves each item of that list as a memory that sleep never deletes: at most 10 per compaction, skipping an item an earlier compaction already saved and any item that looks like a secret. An item over 500 characters stays in the compaction's record only. It then prints one line, such as "Hippo saved 3 memories from this compaction and restored your task snapshot." If the store is busy, the summary waits in the store's compactions-spool/ folder and hippo sleep finishes the save; hippo doctor names any compaction left unfinished for over 10 minutes. It also counts spool files that are waiting, stale (left by a replay that stopped) or set aside as .bad. The session that compacted does not have those memories injected back into its own prompts, since it just read them in the summary; hippo recall still finds them. The hook prints nothing when there is no store to save to. - a PostToolUseFailure hook that runs hippo capture-error, which stores a failed tool call as an error memory. It skips interrupts, declined permissions and searches that found nothing, and stores a repeated failure once. It also logs every failure, stored or not, for hippo failures: the session, the tool and hashes of the error, never its text. A hash is not anonymous, since anyone who guesses an error's text can check it against the hash. The log keeps 90 days.

Only Claude Code saves memories at a compaction: hippo installs no PreCompact or PostCompact hook for Codex, Cursor, OpenCode, OpenClaw or Pi.

To remove: hippo hook uninstall claude-code

For Codex, it adds two hooks to $CODEX_HOME/hooks.json (else ~/.codex/hooks.json) and keeps every hook already there: - a UserPromptSubmit hook that runs the same hippo context --pinned-only command as Claude Code's, so your pinned memories plus up to 5 that match the prompt reach every prompt as developer context - a SessionStart hook (matcher compact) that runs hippo compact-resume after a compaction, so the next prompt sends that block again. Codex gets no PreCompact hook from hippo, so it restores a task snapshot only if one was saved with hippo snapshot save in the last 15 minutes

Codex runs a new or changed hook only after you trust it, so open /hooks in Codex once and trust both; hippo doctor reminds you. The per-prompt hook was checked against a real Codex request; the compaction hook follows Codex's documented compact start source and has not been watched end to end in Codex. Each hook also carries a commandWindows form (hippo.cmd ...), because Codex runs hooks through PowerShell on Windows, where the execution policy can block npm's hippo.ps1. hippo only ever appends these two entries and never rewrites one, since Codex treats a changed command as a new hook to trust. To remove: hippo hook uninstall codex, which takes out only hippo's exact commands and leaves every other hook, including one of yours that runs hippo.

For GitHub Copilot, when $COPILOT_HOME (else ~/.copilot) or a VS Code User folder exists, hippo setup writes hippo's own hooks/hippo.json. When the Copilot folder was there before setup, it also adds a hippo server to mcp-config.json and a block to copilot-instructions.md. The block asks the agent to call hippo_recall and hippo_remember. The Copilot CLI, including its sessions inside VS Code, uses the session-start, tool-failure, pre-compact and session-end hooks, the server and the block. VS Code's agent mode (the Local agent, VS Code 1.109.3 or later) reads the same hooks file. It gets session start, the pre-compact snapshot and a capture after every reply. Setup also adds hippo to VS Code's own mcp.json and writes prompts/hippo.instructions.md, so its recall tools and instructions work too. The hooks, the VS Code files and how to remove them: integrations/copilot.md.

Quick start

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

```bash npm install -g hippo-memory

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 the hook adds (Claude Code example)

````markdown

Invalidated 5 memories referencing "REST API".

```

---

CLI Reference

On heartbeat, block, review and complete, a given --run is checked against the card's live run and the command is refused, unchanged, if the two do not match.

---

BM25: matched [data, pipeline]; cosine: 0.82

Framework Integrations