Hipocampus

hipocampus

Drop-in **proactive memory** harness for AI agents. Zero infrastructure — just files.

One command to set up. Works immediately with [Claude Code](https://claude.ai/code), [OpenCode](https://opencode.ai/), and [OpenClaw](https://github.com/openclaw).

Benchmark

Evaluated on [MemAware](https://github.com/kevin-hs-sohn/memaware) — 900 implicit context questions across 3 months of conversation history. The agent must proactively surface relevant past context that the user never explicitly asks about.

Method	Easy (n=300)	Medium (n=300)	Hard (n=300)	Overall
No Memory	1.0%	0.7%	0.7%	0.8%
BM25 Search	4.7%	1.7%	2.0%	2.8%
BM25 + Vector Search	6.0%	3.7%	0.7%	3.4%
Hipocampus (tree only)	14.7%	5.7%	7.3%	9.2%
Hipocampus + BM25	18.7%	10.0%	5.7%	11.4%
Hipocampus + Vector	26.0%	18.0%	8.0%	17.3%
Hipocampus + Vector (10K ROOT)	34.0%	21.0%	8.0%	21.0%

Hipocampus + Vector is **21.6x better than no memory** and **5.1x better than search alone**. On hard questions (cross-domain, zero keyword overlap), Hipocampus scores 8.0% vs 0.7% for vector search — **11.4x better**. Search structurally cannot find these connections; the compaction tree can.

Increasing the ROOT.md budget from 3K to 10K tokens (120 topics vs 39) improves Easy from 26% to 34% and overall from 17.3% to 21.0% — more topic coverage means more connections found. Hard tier remains at 8.0%, indicating cross-domain reasoning is bottlenecked by the answer model, not the index size.

Install

Claude Code Plugin

/plugin marketplace add kevin-hs-sohn/hipocampus
/plugin install hipocampus@kevin-hs-sohn/hipocampus

Then run `npx hipocampus init` for full setup.

Standalone (npm)

npx hipocampus init

Options

npx hipocampus init --no-vector    # BM25 only (saves ~2GB disk)
npx hipocampus init --no-search    # Compaction tree only, no qmd
npx hipocampus init --platform claude-code  # Override platform detection

The Problem: You Can't Search for What You Don't Know You Know

AI agents forget everything between sessions. The obvious solutions — RAG, long context windows, memory files — each solve part of the problem. But they all miss the hardest part: **knowing that relevant context exists when nobody asked about it.**

A concrete example

You ask your agent: "Refactor this API endpoint for the new payment flow."

Three weeks ago, you and the agent had a long discussion about API rate limiting and decided on a token bucket strategy. That decision is recorded in the session logs. But the agent doesn't know it exists — so it refactors the endpoint without considering rate limits. The payment flow starts dropping requests under load a week later.

This isn't a retrieval failure. The agent never searched for "rate limiting" becaus