Hippo Memory

A memory system for AI coding agents modeled after biological memory consolidation. Three storage layers, decay by default, retrieval strengthening, conflict detection, and cross-framework portability. Zero runtime dependencies, SQLite + markdown mirrors, git-trackable.

Architecture

Three layers, inspired by how human memory works:

Buffer — session-scoped working memory. Maximum 20 entries per scope, importance-based eviction when full, no decay. Think of it as a bounded scratchpad for the current task.

Episodic store — timestamped memories with a 7-day half-life (configurable). Each retrieval extends the half-life by 2 days. Error-tagged memories start with 14-day half-life. After 14 days with zero retrievals, a memory becomes eligible for removal.

Semantic store — compressed patterns extracted when 3+ related episodic memories are detected during consolidation. These are stable, schema-aware, and don't decay like episodes do.

The hippo sleep command runs consolidation: calculates decay, removes sub-threshold memories, merges related episodes into semantic patterns, and marks unretrieved items as stale. All writes happen in a single SQLite transaction.

Decay and retrieval mechanics

Every memory has a half-life. Each unused period cuts strength in half — this is the core design choice. Instead of accumulating memories forever and relying on search relevance alone, the system actively forgets. Retrieval is the signal that a memory matters: each recall extends the half-life, and the outcome --good/--bad commands provide explicit feedback that adjusts decay rates.

Confidence tiers (verified, observed, inferred, stale) are inline in output so the agent can judge reliability. Memories auto-mark as stale after 30 days without retrieval.

See agent-memory-decay for the broader concept.

Hybrid search

BM25 keyword matching always works as the default. If @xenova/transformers is installed, embedding-based cosine similarity is added. Blended scoring combines both signals. Falls back gracefully without ML — you always get search results.

Token budget management ranks results by relevance × strength × recency and truncates to fit a token limit. The --why flag shows the full ranking logic: BM25 scores, cosine distances, source buckets, confidence levels.

See hybrid-search for the general technique.

Conflict detection

When a new memory contradicts an existing one, Hippo keeps both visible rather than silently overwriting. Conflicts are stored in SQLite and mirrored to .hippo/conflicts/ as files. You resolve explicitly with hippo resolve <id> --keep <mem_id>.

This is important: silent overwriting means the agent loses context about why something changed. Keeping contradictions visible lets the agent (or human) make an informed choice. See memory-conflict-detection.

Cross-framework integration

Auto-hooks into Claude Code (CLAUDE.md), Cursor (.cursorrules), Codex/OpenClaw (AGENTS.md). Import from ChatGPT JSON exports, Claude's CLAUDE.md, Cursor rules, generic markdown, or plain text. Duplicate detection on import. All imports support --dry-run.

Session handoffs persist summaries, next actions, and artifacts so a successor session can resume without reading the full transcript. Sessions can cross tool boundaries — start in Claude Code, resume in Cursor.

Auto-learning

hippo learn --git extracts lessons from fix/revert/bug commits automatically. hippo watch "<command>" wraps any command and captures stderr on failure as error memories. hippo capture does pattern-based extraction (no LLM needed) from conversation logs.

Usage

npm install -g hippo-memory
hippo init
hippo remember "deploy requires --force flag on staging" --tag ops --observed
hippo recall "deployment issues" --budget 2000 --why
hippo sleep  # consolidate, decay, merge

mempalace takes the opposite philosophy (verbatim storage, no decay, palace-metaphor hierarchy). Stash extends the consolidation idea into a longer pipeline (causal links, contradictions, goal/failure/hypothesis stages). Three-way comparison table lives on the MemPalace page.

232 stars, MIT license. Repo: https://github.com/kitfunso/hippo-memory