# 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

```bash
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
```

## Related tools

[[mempalace]] takes the opposite philosophy (verbatim storage, no decay, palace-metaphor hierarchy). [[toolbox/stash|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