# Hippo Memory

> Biologically-inspired persistent memory system for AI agents with decay, retrieval strengthening, and sleep consolidation — zero runtime dependencies.

Hippo is a CLI-based memory layer for AI coding agents that models human hippocampal memory mechanics: decay by default, retrieval strengthening, sleep consolidation, and reward-proportional decay. It solves the problem of agents forgetting everything between sessions and context being trapped inside individual tools like ChatGPT, Claude, or Cursor. Hippo uses a SQLite backbone with markdown/YAML mirrors, making memories git-trackable and human-readable, with zero runtime dependencies.

- **Decay by default** — every memory has a configurable half-life (7 days default); persistence must be earned through retrieval or explicit pinning
- **Retrieval strengthening** — each recall extends a memory's half-life by 2 days, implementing the testing effect mechanically
- **Sleep consolidation** — `hippo sleep` compresses repeated episodic memories into semantic patterns, removes decayed entries, and merges related episodes
- **Error memories stick** — memories tagged `--error` receive 2× the half-life and a 1.5× strength multiplier, so hard lessons don't fade quietly
- **Confidence tiers** — memories carry `verified`, `observed`, `inferred`, or `stale` labels so agents know how much to trust each piece of context
- **Hybrid search** — BM25 keyword search with optional cosine embedding similarity via `@xenova/transformers` for semantic recall
- **Cross-tool import** — import memories from ChatGPT exports, CLAUDE.md, `.cursorrules`, or any markdown/text file with `hippo import`
- **Auto-hook install** — `hippo init` detects Claude Code, Codex, Cursor, OpenClaw, and OpenCode and patches the right config file automatically
- **MCP server** — `hippo mcp` starts an MCP server over stdio, exposing tools like `hippo_recall`, `hippo_remember`, and `hippo_context` to any MCP-compatible client
- **Active invalidation** — `hippo learn --git` detects migration commits and actively weakens memories referencing replaced patterns; manual invalidation also supported
- **Architectural decisions** — `hippo decide` stores one-off decisions with a 90-day half-life and supports superseding chains as architecture evolves
- **Working memory & session handoffs** — bounded scratchpad (`hippo wm`) for current-session notes and `hippo handoff` for persisting session summaries across agent switches
- **Outcome feedback** — `hippo outcome --good/--bad` applies reward-proportional decay modulation inspired by R-STDP in spiking neural networks
- **Token budgets** — `hippo recall --budget 2000` ranks memories by relevance × strength × recency and fills the budget with highest-signal results first

## Features
- Decay-based memory lifecycle with configurable half-lives
- Retrieval strengthening (half-life extension on recall)
- Sleep consolidation (episodic → semantic compression)
- Error memories with 2× half-life
- Confidence tiers: verified, observed, inferred, stale
- Hybrid BM25 + embedding search
- Cross-tool import from ChatGPT, Claude, Cursor, markdown
- Auto-hook install for Claude Code, Codex, Cursor, OpenClaw, OpenCode
- MCP server over stdio
- Active invalidation from git commit detection
- Architectural decision memory with 90-day half-life
- Working memory scratchpad with importance-based eviction
- Session handoffs for cross-session continuity
- Reward-proportional decay modulation
- Token budget-aware recall
- Conflict detection and resolution
- Multi-agent shared memory with transfer scoring
- Auto-learn from git commit history
- Watch mode for auto-capturing command failures
- Explainable recall with --why flag
- Web dashboard at localhost:3333
- Path-based memory triggers
- Outcome feedback loop

## Integrations
Claude Code, Codex, Cursor, OpenClaw, OpenCode, ChatGPT, Cline, Windsurf, Claude Desktop, @xenova/transformers, SQLite, Git

## Platforms
WEB, API, CLI

## Pricing
Open Source

## Version
v0.11.1

## Links
- Website: https://github.com/kitfunso/hippo-memory
- Documentation: https://github.com/kitfunso/hippo-memory
- Repository: https://github.com/kitfunso/hippo-memory
- EveryDev.ai: https://www.everydev.ai/tools/hippo-memory