{
  "markdown": "# hipocampus\n\nDrop-in **proactive memory** harness for AI agents. Zero infrastructure — just files.\n\nOne command to set up. Works immediately with [Claude Code](https://claude.ai/code), [OpenCode](https://opencode.ai/), and [OpenClaw](https://github.com/openclaw).\n\n## Benchmark\n\nEvaluated 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.\n\n| Method | Easy (n=300) | Medium (n=300) | Hard (n=300) | **Overall** |\n|--------|:---:|:---:|:---:|:---:|\n| No Memory | 1.0% | 0.7% | 0.7% | 0.8% |\n| BM25 Search | 4.7% | 1.7% | 2.0% | 2.8% |\n| BM25 + Vector Search | 6.0% | 3.7% | 0.7% | 3.4% |\n| **Hipocampus (tree only)** | **14.7%** | **5.7%** | **7.3%** | **9.2%** |\n| **Hipocampus + BM25** | **18.7%** | **10.0%** | **5.7%** | **11.4%** |\n| **Hipocampus + Vector** | **26.0%** | **18.0%** | **8.0%** | **17.3%** |\n| **Hipocampus + Vector (10K ROOT)** | **34.0%** | **21.0%** | **8.0%** | **21.0%** |\n\nHipocampus + 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.\n\nIncreasing 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.\n\n## Install\n\n### Claude Code Plugin\n\n```bash\n/plugin marketplace add kevin-hs-sohn/hipocampus\n/plugin install hipocampus@kevin-hs-sohn/hipocampus\n```\n\nThen run `npx hipocampus init` for full setup.\n\n### Standalone (npm)\n\n```bash\nnpx hipocampus init\n```\n\n### Options\n\n```bash\nnpx hipocampus init --no-vector    # BM25 only (saves ~2GB disk)\nnpx hipocampus init --no-search    # Compaction tree only, no qmd\nnpx hipocampus init --platform claude-code  # Override platform detection\n```\n\n## The Problem: You Can't Search for What You Don't Know You Know\n\nAI 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.**\n\n### A concrete example\n\nYou ask your agent: \"Refactor this API endpoint for the new payment flow.\"\n\nThree 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.\n\nThis 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.\n\n### Why existing approaches fail\n\n**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.\n\n**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](https://github.com/kevin-hs-sohn/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.**\n\n**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.\n\n### What hipocampus does differently\n\nHipocampus 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.\n\nWhen 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.\n\nThe effect is similar to injecting your full history into every API call, at a fraction of the token cost.\n\n## How It Works\n\n### 3-Tier Memory\n\nLike a CPU cache hierarchy:\n\n**Layer 1 — Hot (always loaded, ~3K tokens)**\n\n| File | Purpose |\n|------|---------|\n| `memory/ROOT.md` | Compressed index of ALL past history — the key innovation |\n| `SCRATCHPAD.md` | Active work state |\n| `WORKING.md` | Tasks in progress |\n| `TASK-QUEUE.md` | Task backlog |\n\nROOT.md has four sections:\n\n```markdown\n## Active Context (recent ~7 days)\n- hipocampus open-source: finalizing spec, ROOT.md format refactor\n\n## Recent Patterns\n- compaction design: functional sections outperform chronological\n\n## Historical Summary\n- 2026-01~02: initial 3-tier design, clawy.pro K8s launch\n- 2026-03: hipocampus open-source, qmd integration\n\n## Topics Index\n- hipocampus [project, 2d]: compaction tree, ROOT.md, skills → spec/\n- legal [reference, 14d]: Civil Act §750, tort liability → knowledge/legal-750.md\n- clawy.pro [project, 30d]: K8s infra, provisioning, 80-bot deployment\n```\n\nEach 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.\n\n**Layer 2 — Warm (read on demand)**\n\n| Path | Purpose |\n|------|---------|\n| `memory/YYYY-MM-DD.md` | Raw daily logs — structured session records |\n| `knowledge/*.md` | Curated knowledge base |\n| `plans/*.md` | Task plans |\n\n**Layer 3 — Cold (search + compaction tree)**\n\nTwo retrieval mechanisms:\n\n- **RAG (qmd)** — semantic search when you know what you're looking for\n- **Compaction tree** — hierarchical drill-down (ROOT → monthly → weekly → daily → raw) for browsing and discovery\n\n```\nCompaction chain: Raw → Daily → Weekly → Monthly → Root\n\nmemory/\n├── ROOT.md                     # Auto-loaded topic index\n├── 2026-03-15.md               # Raw daily log (permanent)\n├── daily/2026-03-15.md         # Daily compaction node\n├── weekly/2026-W11.md          # Weekly index node\n└── monthly/2026-03.md          # Monthly index node\n```\n\n### Smart Compaction\n\nBelow threshold, source files are copied verbatim — no information loss. Above threshold, LLM generates keyword-dense summaries.\n\n| Level | Threshold | Below | Above |\n|-------|-----------|-------|-------|\n| Raw → Daily | ~200 lines | Copy verbatim | LLM summary |\n| Daily → Weekly | ~300 lines | Concat | LLM summary |\n| Weekly → Monthly | ~500 lines | Concat | LLM summary |\n| Monthly → Root | Always | Recursive recompaction | — |\n\n### Memory Types\n\nEvery memory entry is classified into one of four types, controlling how it's preserved over time:\n\n| Type | Purpose | Compaction behavior |\n|------|---------|-------------------|\n| `project` | Work, decisions, technical findings | Compressed when completed |\n| `feedback` | User corrections on approach | Always preserved verbatim |\n| `user` | User identity, expertise, preferences | Always preserved |\n| `reference` | External pointers (URLs, tools) | Preserved with staleness markers |\n\n`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.\n\n### Selective Recall\n\nWhen a question might relate to past memory, hipocampus uses a 3-step fallback:\n\n1. **ROOT.md triage (O(1))** — Topics Index lookup. Resolves most queries instantly.\n2. **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.\n3. **qmd search** — BM25/vector hybrid for specific keyword retrieval.\n\nStep 2 solves the keyword mismatch problem: \"배포\" ↔ \"deployment\", \"CI/CD\" ↔ \"github-actions\" — the LLM understands semantic connections that keyword search misses.\n\n### Automatic Operation\n\nEverything runs automatically after `npx hipocampus init`:\n\n| Mechanism | When | Cost |\n|-----------|------|------|\n| Session Start | First message — load hot files, check compaction | Read only |\n| End-of-Task Checkpoint | After every task — typed entry to daily log | LLM (subagent) |\n| Proactive Flush | Every ~20 messages — prevent context loss | LLM (subagent) |\n| Pre-Compaction Hook | Before context compression — mechanical compact | Zero LLM |\n| Secret Scanning | During compaction — redact API keys, tokens | Zero LLM |\n| ROOT.md Auto-Load | Every session start | ~3K tokens |\n\nMemory writes are dispatched to subagents to keep the main session clean.\n\n**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.\n\n## Comparison\n\n| | Ad-hoc MEMORY.md | OpenViking | **Hipocampus** |\n|---|---|---|---|\n| Setup | Manual | Python server + embedding model | **`npx hipocampus init`** |\n| Infrastructure | None | Server + DB | **None — just files** |\n| Search | None | Vector + directory recursive | **BM25 + vector hybrid (qmd)** |\n| Knows what it knows | Only what fits (~50 lines) | No (search required) | **ROOT.md (~3K tokens)** |\n| Scales over months | No — overflows | Yes | **Yes — self-compressing tree** |\n\n## File Layout\n\n```\nproject/\n├── SCRATCHPAD.md\n├── WORKING.md\n├── TASK-QUEUE.md\n├── memory/\n│   ├── ROOT.md                  # Topic index (auto-loaded)\n│   ├── (YYYY-MM-DD.md)         # Raw daily logs\n│   ├── daily/                   # Daily compaction nodes\n│   ├── weekly/                  # Weekly index nodes\n│   └── monthly/                 # Monthly index nodes\n├── knowledge/\n├── plans/\n├── hipocampus.config.json\n└── .claude/skills/hipocampus-*  # Agent skills (5 skills)\n```\n\n## Configuration\n\n```json\n{\n  \"platform\": \"claude-code\",\n  \"search\": { \"vector\": true, \"embedModel\": \"auto\" },\n  \"compaction\": { \"rootMaxTokens\": 3000, \"cooldownHours\": 3 }\n}\n```\n\n| Field | Default | Description |\n|-------|---------|-------------|\n| `platform` | auto-detected | `\"claude-code\"`, `\"opencode\"`, or `\"openclaw\"` |\n| `search.vector` | `true` | Enable vector embeddings (~2GB disk) |\n| `search.embedModel` | `\"auto\"` | `\"auto\"` for embeddinggemma-300M, `\"qwen3\"` for CJK |\n| `compaction.rootMaxTokens` | `3000` | Max token budget for ROOT.md |\n| `compaction.cooldownHours` | `3` | Min hours between compaction runs (0 = disable) |\n\n## Skills\n\nHipocampus installs five agent skills:\n\n- **hipocampus-core** — Session start protocol + typed checkpoints + exclusion rules\n- **hipocampus-compaction** — 5-level compaction tree with type-aware rules + secret scanning\n- **hipocampus-recall** — 3-step selective recall (ROOT.md → manifest LLM → qmd search)\n- **hipocampus-search** — Search guide: ROOT.md lookup, qmd, tree traversal\n- **hipocampus-flush** — Manual memory flush via subagent\n\n## Spec\n\nFormal specification in [`spec/`](./spec/):\n\n- [layers.md](./spec/layers.md) — 3-tier architecture\n- [file-formats.md](./spec/file-formats.md) — File format specification\n- [compaction.md](./spec/compaction.md) — Compaction tree algorithm\n- [checkpoint.md](./spec/checkpoint.md) — Session + checkpoint protocol\n\n## License\n\nMIT\n",
  "bytes": 12026,
  "sha": "e157fc6ddee434718e0a6edc25a2b509e6ec8d9e3aba0272b8a2d4dcb7aff938",
  "repo_slug": "kevin-hs-sohn/hipocampus",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/plg_kevin_hs_sohn_hipocampus_hipocampus_6f994438/readme"
}