Hippo Memory: A Decay-Based Memory Layer for CLI Coding Agents

The Problem Hippo Targets: Agents That Never Learn From Their Own Failures

A coding agent that hits the same broken deploy step on Monday and again on Thursday has not stored the wrong thing. It has stored everything and ranked nothing. The README frames the failure this way: the system saw the failure four times and had no signal telling it which observation deserved to survive. Hippo's answer is to treat forgetting as the default state and retrieval as the event that promotes a memory. Errors are tagged so they decay more slowly than ordinary observations, which means a failure recorded once with the error tag keeps resurfacing when the agent works near the same code.

The second problem is portability. Memories written into CLAUDE.md, .cursorrules or a ChatGPT export stay inside the tool that produced them. Hippo imports from those formats and keeps one SQLite store per project, so an agent swap does not reset what the agent knows. The intended user is a developer who already runs at least two CLI agents and has felt the seam between them. Someone using a single agent in a single repository will get less out of it, because the cross-tool argument is most of the value proposition.

Buffer, Episodic, Semantic: What the Three Tiers Actually Do

The README describes three biological layers, buffer, episodic and semantic, that consolidate during sleep. The repository layout backs this up: hippo init creates buffer/, episodic/ and semantic/ directories alongside conflicts/ inside the .hippo/ store. The buffer is the short-lived landing zone for raw events. Episodic holds session-level memories. Semantic holds what has been promoted after repeated use. A conflicts/ directory suggests contradictions between memories are parked rather than silently overwritten, though the supplied material does not describe the resolution policy, so treat that as unverified.

Storage is a SQLite backbone with markdown mirrors. That combination matters more than it sounds. SQLite gives the query layer a real index and a real transaction boundary. The markdown mirror means the store is git-trackable and readable without the tool, which is a deliberate hedge against lock-in. Every row is described as carrying kind, scope, owner and artifact_ref, which is what makes the deletion path a single API call rather than a crawl through derived indexes.

Retrieval is where the design gets opinionated. The project reports R@5 of 74.0% on LongMemEval using BM25 only, with no embeddings. Embeddings are opt-in and nothing is installed automatically: you either bring a local Transformers.js model or configure an API embedder. That ordering is sensible. A lexical baseline that works before you add a model is easier to debug than a pipeline where the embedding step is assumed.

Getting It Running: init, scan, remember, recall, sleep

Installation is a global npm package: npm install -g hippo-memory. The README lists Node.js 22.5+ as the requirement and states zero runtime dependencies.

For a single repository, hippo init. For every git repository under your home directory, hippo init --scan ~, which creates a .hippo/ store in each one and seeds it with lessons from the last 30 days of commit history. The init step also auto-detects your agent framework and patches the relevant file: CLAUDE.md for Claude Code, AGENTS.md for Codex, OpenClaw and OpenCode, .cursorrules for Cursor. It registers the project in a workspace registry and installs one machine-level daily runner at 6:15am that sweeps every registered workspace, runs hippo learn --git --days 1 and then hippo sleep. To opt out of all of it: hippo init --no-hooks --no-schedule.

Day-to-day use is two commands. hippo remember "FRED cache silently dropped the tips_10y series" --tag error writes a memory with the error tag. hippo recall "data pipeline issues" --budget 2000 reads it back under a token budget. The budget flag is the part worth noticing: recall returns a bounded set rather than everything that matches, which is the mechanism that keeps the decay model from being drowned out by sheer volume.

Codex session capture is opt-in rather than automatic. The README states that Hippo wraps the codex launcher only when you run hippo hook install codex, and that init prints the command when it detects Codex. Undo is hippo hook uninstall codex. Importing from other tools uses hippo import with a source flag: --chatgpt memories.json, --claude CLAUDE.md, --cursor .cursorrules. The --claude path skips existing hippo hook blocks, which prevents a re-import from duplicating the block init already wrote.

The Sleep Cycle Is the Whole Design, and the Least Inspectable Part

Everything above depends on hippo sleep running at session end. The README says it does five things: learns from the day's git commits, imports new entries from Claude Code MEMORY.md files, consolidates by decay, merge and prune, deduplicates near-identical memories keeping the stronger copy, and shares high-value lessons to a global store so they surface in every project.

That fifth step is the one to think hardest about before adopting. A global store that receives lessons from every project means a memory written in one repository can appear in recall results in an unrelated one. For a solo developer working across personal projects this is probably the feature. In a multi-tenant or client-work setting it is a boundary you need to understand before the first sleep cycle runs, because the sharing decision is made by the consolidation pass, not by you at write time.

The deduplication rule, keep the stronger copy, is also under-specified in the supplied material. Strength presumably derives from retrieval count and recency, but the README does not state the formula. If you are evaluating Hippo for a team, that formula is the first thing to read in the source, because it decides which of two near-identical lessons survives and which is deleted.

A practical failure mode follows from the scheduling model. The daily runner is machine-level and fires at 6:15am. If your machine is asleep at that time, or the runner fails silently, consolidation does not happen and the decay curve stops advancing. Nothing in the supplied material describes catch-up behaviour after a missed run.

Zero Dependencies and an MCP Server Are Not the Same as Zero Integration Work

The zero-runtime-dependency claim is real and verifiable from the package metadata, and it is a genuine advantage for anyone who has watched a memory tool pull in a transitive tree of native modules. But zero dependencies applies to the package, not to your setup. Embeddings, if you want them, mean installing @huggingface/transformers yourself or configuring an API embedder against OpenAI, Voyage or Cohere, which reintroduces a network dependency and a per-call cost that the BM25-only default avoids.

The integration surface is also wider than a library import. Hippo patches your CLAUDE.md or .cursorrules, registers a workspace, and installs a scheduled task. Each of those is a mutation to your environment that persists after you stop using the tool. The --no-hooks --no-schedule flag exists precisely because some developers will not want that, and the honest reading is that Hippo is designed as infrastructure you install once rather than a library you call from code.

On multi-tenancy, the README states API keys are scrypt-hashed, that every mutation writes an audit log, and that tenant isolation is proven by a negative test. Those are claims about the server mode, not the local CLI. If you only ever run hippo init and hippo remember locally, the tenant machinery is dormant.

How Hippo Differs From a Vector Store Plus a Retrieval Wrapper

The obvious alternative is a general-purpose vector database with a retrieval layer on top, or a hosted memory API. The difference is not the storage engine. It is where the ranking signal comes from. A vector store ranks by similarity to the query and nothing else. A memory written once and never retrieved sits in the index at the same weight as one that has been pulled into twenty sessions, unless you build a scoring layer yourself.

Hippo inverts that. Decay reduces the weight of unused memories over time, retrieval increases it, and the consolidation pass is what applies both. The project's own framing is that storage with semantic search bolted on is the thing it is reacting against. Whether that produces better agent behaviour than a well-tuned vector store is an empirical question, and the supplied material offers one relevant data point: 10 of 10 incident scenarios beat transcript replay on a staged Slack corpus, meaning recall surfaced the cause faster than scrolling the last N messages. That is a comparison against replay, not against a vector database, so it does not settle the question.

A second alternative is simpler still: a hand-maintained CLAUDE.md or AGENTS.md file. It has no decay, no retrieval budget and no deduplication, but it is fully inspectable and requires no process running behind your agent. Hippo's import commands exist because that file is where most developers actually start, and the migration path from it is one command.

Maintenance Cost, Release Cadence and the MIT Licence

The release history shows a fast cadence. Three releases are listed in the two days before the last push: v1.38.9, v1.38.7 and v1.38.10. A version number in the high thirties with patch releases landing hours apart suggests active iteration rather than a stable API. If you pin hippo-memory in a team environment, pin an exact version and read the CHANGELOG between upgrades, because the consolidation and decay logic is the kind of code that changes behaviour without changing the command surface.

The README is unusually candid about a retraction: an informal magnitude result from v0.11.0 was retracted in v1.7.9, while the underlying mechanism stayed shipped. That is a better signal about the project's testing culture than any number would be, and it is worth reading the v1.7.9 CHANGELOG entry before you trust the sequential learning benchmark framing.

The licence is MIT, which permits commercial use, modification and redistribution with the copyright notice retained. That is a permissive default and imposes no copyleft obligation on your own code. It says nothing about the data you put in the store. If you ingest Slack history or customer material through the connectors, the compliance question is about that data and your own obligations, not about Hippo's licence. The provenance fields and the deletion endpoint are the mechanisms the project gives you for that work. Whether they satisfy a specific regulatory requirement is a question for your own counsel, not something a README can settle.

Editorial conclusion

Adopt Hippo if you run several CLI agents against the same repositories and keep re-explaining the same failures to each of them. Skip it if you need a hosted memory service with a managed vector index, or if your agents are not file-and-terminal based. Before committing, run hippo init in one throwaway repository and read the .hippo/ directory it creates, then run hippo sleep once and inspect what consolidation actually pruned, because the decay thresholds are the part of the design most likely to disagree with your expectations.

Official sources

1. kitfunso/hippo-memory on GitHub
2. License: MIT
3. Project website
4. README
5. Releases