hipocampus

hipocampus

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

One command to set up. Works immediately with Claude Code, OpenCode, and OpenClaw.

Benchmark

Evaluated on 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" because the user asked about "payment flow." There is no search query that connects these. The connection only exists if the agent has a holistic view of its own knowledge.

Why existing approaches fail

Large context windows (200K–1M tokens): You could dump all history into context. But attention degrades with length — important details from three weeks ago get drowned by noise. And every API call pays for the full context. At 500K tokens per call, costs become prohibitive.

RAG (vector search, BM25): Powerful when you know what to search for. But search requires a query, and a query requires suspecting that relevant context exists. Our MemAware benchmark confirms: BM25 search scores just 2.8% on implicit context — barely better than no memory (0.8%), while consuming 5x the tokens. Search is a precision tool for known unknowns. It cannot help with unknown unknowns.

Memory files (MEMORY.md, auto memory): Good for the first week. After a month, hundreds of decisions and insights can't fit in a system prompt. You're forced to choose what to keep, and the agent doesn't know what it has forgotten.

What hipocampus does differently

Hipocampus maintains a ~3K token topic index (ROOT.md) that compresses your entire conversation history into a scannable overview — like a table of contents for everything the agent has ever discussed. This is auto-loaded into every session.

When a request comes in, the agent already sees all past topics at zero search cost. It notices connections that search would miss — "this refactoring task relates to the rate limiting decision from three weeks ago" — and retrieves specific details on demand via search or tree traversal.

The effect is similar to injecting your full history into every API call, at a fraction of the token cost.

How It Works

3-Tier Memory

Like a CPU cache hierarchy:

Layer 1 — Hot (always loaded, ~3K tokens)

File	Purpose
memory/ROOT.md	Compressed index of ALL past history — the key innovation
SCRATCHPAD.md	Active work state
WORKING.md	Tasks in progress
TASK-QUEUE.md	Task backlog

ROOT.md has four sections:

## Active Context (recent ~7 days)
- hipocampus open-source: finalizing spec, ROOT.md format refactor

## Recent Patterns
- compaction design: functional sections outperform chronological

## Historical Summary
- 2026-01~02: initial 3-tier design, clawy.pro K8s launch
- 2026-03: hipocampus open-source, qmd integration

## Topics Index
- hipocampus [project, 2d]: compaction tree, ROOT.md, skills → spec/
- legal [reference, 14d]: Civil Act §750, tort liability → knowledge/legal-750.md
- clawy.pro [project, 30d]: K8s infra, provisioning, 80-bot deployment

Each topic carries a type (project, feedback, user, reference) and age — so the agent knows not just what it knows, but what kind of information it is and how fresh it is. O(1) lookup — no file reads needed.

Layer 2 — Warm (read on demand)

Path	Purpose
memory/YYYY-MM-DD.md	Raw daily logs — structured session records
knowledge/*.md	Curated knowledge base
plans/*.md	Task plans

Layer 3 — Cold (search + compaction tree)

Two retrieval mechanisms:

• RAG (qmd) — semantic search when you know what you're looking for
• Compaction tree — hierarchical drill-down (ROOT → monthly → weekly → daily → raw) for browsing and discovery

Compaction chain: Raw → Daily → Weekly → Monthly → Root

memory/
├── ROOT.md                     # Auto-loaded topic index
├── 2026-03-15.md               # Raw daily log (permanent)
├── daily/2026-03-15.md         # Daily compaction node
├── weekly/2026-W11.md          # Weekly index node
└── monthly/2026-03.md          # Monthly index node

Smart Compaction

Below threshold, source files are copied verbatim — no information loss. Above threshold, LLM generates keyword-dense summaries.

Level	Threshold	Below	Above
Raw → Daily	~200 lines	Copy verbatim	LLM summary
Daily → Weekly	~300 lines	Concat	LLM summary
Weekly → Monthly	~500 lines	Concat	LLM summary
Monthly → Root	Always	Recursive recompaction	—

Memory Types

Every memory entry is classified into one of four types, controlling how it's preserved over time:

Type	Purpose	Compaction behavior
project	Work, decisions, technical findings	Compressed when completed
feedback	User corrections on approach	Always preserved verbatim
user	User identity, expertise, preferences	Always preserved
reference	External pointers (URLs, tools)	Preserved with staleness markers

user and feedback memories never get compressed away — they survive indefinitely. project memories compress into Historical Summary after completion. reference entries get a [?] marker after 30 days without verification.

Selective Recall

When a question might relate to past memory, hipocampus uses a 3-step fallback:

• ROOT.md triage (O(1)) — Topics Index lookup. Resolves most queries instantly.
• Manifest-based LLM selection — For cross-domain queries where keywords don't match. Reads compaction node frontmatter only (<500 tokens), LLM selects top 5 relevant files.
• qmd search — BM25/vector hybrid for specific keyword retrieval.

Step 2 solves the keyword mismatch problem: "배포" ↔ "deployment", "CI/CD" ↔ "github-actions" — the LLM understands semantic connections that keyword search misses.

Automatic Operation

Everything runs automatically after npx hipocampus init:

Mechanism	When	Cost
Session Start	First message — load hot files, check compaction	Read only
End-of-Task Checkpoint	After every task — typed entry to daily log	LLM (subagent)
Proactive Flush	Every ~20 messages — prevent context loss	LLM (subagent)
Pre-Compaction Hook	Before context compression — mechanical compact	Zero LLM
Secret Scanning	During compaction — redact API keys, tokens	Zero LLM
ROOT.md Auto-Load	Every session start	~3K tokens

Memory writes are dispatched to subagents to keep the main session clean.

Adaptive compaction triggers: Compaction runs when any condition is met — cooldown expired (default 3h), raw log exceeds 300 lines, or 5+ checkpoints accumulated. Active sessions compact more frequently; quiet days skip unnecessary work.

Comparison

	Ad-hoc MEMORY.md	OpenViking	Hipocampus
Setup	Manual	Python server + embedding model	npx hipocampus init
Infrastructure	None	Server + DB	None — just files
Search	None	Vector + directory recursive	BM25 + vector hybrid (qmd)
Knows what it knows	Only what fits (~50 lines)	No (search required)	ROOT.md (~3K tokens)
Scales over months	No — overflows	Yes	Yes — self-compressing tree

File Layout

project/
├── SCRATCHPAD.md
├── WORKING.md
├── TASK-QUEUE.md
├── memory/
│   ├── ROOT.md                  # Topic index (auto-loaded)
│   ├── (YYYY-MM-DD.md)         # Raw daily logs
│   ├── daily/                   # Daily compaction nodes
│   ├── weekly/                  # Weekly index nodes
│   └── monthly/                 # Monthly index nodes
├── knowledge/
├── plans/
├── hipocampus.config.json
└── .claude/skills/hipocampus-*  # Agent skills (5 skills)

Configuration

{
  "platform": "claude-code",
  "search": { "vector": true, "embedModel": "auto" },
  "compaction": { "rootMaxTokens": 3000, "cooldownHours": 3 }
}

Field	Default	Description
platform	auto-detected	"claude-code", "opencode", or "openclaw"
search.vector	true	Enable vector embeddings (~2GB disk)
search.embedModel	"auto"	"auto" for embeddinggemma-300M, "qwen3" for CJK
compaction.rootMaxTokens	3000	Max token budget for ROOT.md
compaction.cooldownHours	3	Min hours between compaction runs (0 = disable)

Skills

Hipocampus installs five agent skills:

• hipocampus-core — Session start protocol + typed checkpoints + exclusion rules
• hipocampus-compaction — 5-level compaction tree with type-aware rules + secret scanning
• hipocampus-recall — 3-step selective recall (ROOT.md → manifest LLM → qmd search)
• hipocampus-search — Search guide: ROOT.md lookup, qmd, tree traversal
• hipocampus-flush — Manual memory flush via subagent

Spec

Formal specification in spec/:

• layers.md — 3-tier architecture
• file-formats.md — File format specification
• compaction.md — Compaction tree algorithm
• checkpoint.md — Session + checkpoint protocol

License

MIT