How to Set Up Hipocampus on OpenClaw (Complete Guide)

I run a company where every employee is an AI agent. Seven agents, running 24/7, handling SEO, lead gen, customer support, code, email, and analytics. The single biggest problem I hit in the first month wasn't code quality or API limits — it was memory loss.

Every time a session ended, my agents forgot everything. Decisions we'd made. Bugs we'd fixed. Customer preferences. Context that took 30 minutes to build got wiped in 2 seconds when a session timed out. I was re-explaining the same things five times a day.

That problem is why Hipocampus exists. And after running it for weeks across every agent in our fleet, I can tell you: it's the difference between an agent that works and an agent that's actually useful.

Try MrDelegate — Get your own OpenClaw assistant, fully hosted and managed. Start free trial →

What Is Hipocampus?

Hipocampus is a 3-tier memory system designed specifically for OpenClaw agents. Named after the brain region responsible for memory consolidation, it gives your agent persistent, searchable, hierarchical memory that survives across sessions.

Here's the architecture in plain terms:

Layer 1: Hot Memory (System Prompt)

These files load automatically at session start. Your agent reads them before processing any user message:

• MEMORY.md (~50 lines) — long-term memory, split into frozen Core and compactable Adaptive sections
• SCRATCHPAD.md (~150 lines) — active working state, what's happening right now
• WORKING.md (~100 lines) — current task list with statuses
• TASK-QUEUE.md (~50 lines) — backlog items waiting for attention
• ROOT.md (~100 lines) — topic index across all memory, roughly 3K tokens

Layer 1 fits inside the system prompt. It's always available. No search required.

Layer 2: On-Demand Memory

Larger files that get pulled in when the agent needs them:

• memory/YYYY-MM-DD.md — raw daily logs. Permanent, append-only, never deleted
• knowledge/*.md — detailed knowledge docs on specific topics
• plans/*.md — task plans and project outlines

Layer 2 gets read explicitly. The agent decides when to pull these in based on what it's working on.

Layer 3: Search + Compaction Tree

This is where Hipocampus gets interesting. A 5-level hierarchical index built from your raw daily logs:

Raw daily logs → Daily compaction → Weekly compaction → Monthly compaction → ROOT.md
```bash

Each level summarizes the level below it. Search works in reverse — ROOT.md first (broad), then drill down through monthly, weekly, daily, and finally raw logs for full detail.

The search engine (`qmd`) supports BM25 keyword search, vector search, and hybrid mode. You run `qmd query "what was the bug we fixed last Tuesday"` and it finds it.

## Why Default OpenClaw Memory Is Lossy

Out of the box, OpenClaw gives your agent a single MEMORY.md file. That's it. No structure, no compaction, no search. Here's what goes wrong:

**Problem 1: No session continuity.** When a session ends, the agent's context window gets wiped. If it didn't write something to MEMORY.md before the session closed, that information is gone permanently.

**Problem 2: MEMORY.md doesn't scale.** A flat file works for the first week. By week three, you've got 400 lines of unstructured notes that blow past any reasonable token budget for a system prompt. Your agent spends 2,000 tokens just reading stale memory every single message.

**Problem 3: No search.** With a flat file, the only way to find something is to read the entire file. There's no index, no hierarchy, no way to ask "what happened on March 12th?" without loading everything.

**Problem 4: No compaction.** Raw logs accumulate forever. Nobody summarizes them. Nobody prunes them. After a month, you've got 30 files of varying quality with no way to extract signal from noise.

I lost three days of context in my first week running MrDelegate because a session timed out during a complex deployment. The agent had made 14 decisions about our auth system, none of which were written down. We had to re-derive everything from scratch.

## Step-by-Step Setup

### Prerequisites

- OpenClaw installed and running (any version after 0.9)
- Node.js 18+ (you already have this if OpenClaw runs)
- 5 minutes

### Step 1: Initialize Hipocampus

From your OpenClaw workspace directory:

```bash
npx hipocampus init
```bash

This creates the memory directory structure, config file, and base templates. You'll see:

```bash
Created: memory/
Created: memory/ROOT.md
Created: hipocampus.config.json
Created: SCRATCHPAD.md
Created: WORKING.md
Created: TASK-QUEUE.md
Updated: AGENTS.md (added protocol block)
```bash

### Step 2: Configure

Open `hipocampus.config.json`:

```json
{
  "compaction": {
    "cooldownHours": 3,
    "thresholds": {
      "daily": 200,
      "weekly": 300,
      "monthly": 500
    }
  },
  "search": {
    "vector": true,
    "rerank": true
  }
}
```bash

Key settings:

- **cooldownHours** — minimum hours between compaction runs. Set to 3 for active use, 0 if you want compaction every session. I run 3 hours because compaction is expensive and daily logs don't change that fast.
- **thresholds** — line counts that trigger LLM summarization vs. verbatim copy. Below threshold, raw content gets concatenated directly (zero information loss). Above threshold, the LLM generates keyword-dense summaries.
- **search.vector** — enables embedding-based semantic search alongside BM25 keyword search. Costs a few cents per update but dramatically improves recall.

### Step 3: Install the Skills

Hipocampus ships as four OpenClaw skills:

```bash
clawhub install hipocampus-core
clawhub install hipocampus-compaction
clawhub install hipocampus-search
clawhub install hipocampus-flush
```bash

Or if they came pre-installed (which they do on MrDelegate instances), verify they're present:

```bash
ls ~/.openclaw/workspace/skills/hipocampus-*/SKILL.md
```bash

### Step 4: Add the Protocol to AGENTS.md

If `npx hipocampus init` didn't do this automatically, add the protocol block to your AGENTS.md. This is the critical piece — it tells your agent to follow the memory protocol every session:

```markdown
<!-- hipocampus:protocol:start -->
## Hipocampus — Memory Protocol
This project uses hipocampus 3-tier memory. Follow skills/hipocampus-core/SKILL.md.
<!-- hipocampus:protocol:end -->
```bash

The protocol enforces five mandatory steps at session start: read SCRATCHPAD.md, read WORKING.md, recover stale tasks, read TASK-QUEUE.md, and run compaction maintenance. No skipping. No shortcuts.

### Step 5: Build the Initial Index

```bash
qmd update    # Build BM25 index
qmd embed     # Generate vector embeddings (optional, requires API key)
```bash

### Step 6: Verify

Start a new OpenClaw session. Your agent should immediately read all Layer 1 files and check the compaction state. If it doesn't, the protocol block in AGENTS.md isn't being picked up — double-check the formatting.

## How MrDelegate Pre-Installs Hipocampus

Every MrDelegate managed hosting customer gets Hipocampus configured out of the box. Here's what we set up:

1. **Hipocampus initialized** with tuned thresholds based on expected usage volume
2. **All four skills installed** and verified
3. **AGENTS.md protocol block** injected with the full 5-step session start sequence
4. **Compaction cron** set to run every 3 hours via OpenClaw heartbeat
5. **qmd search** configured with vector embeddings enabled
6. **MEMORY.md** pre-structured with Core (frozen) and Adaptive (compactable) sections

We do this because memory setup is the #1 thing new OpenClaw users get wrong. They either skip it entirely or configure it halfway and wonder why their agent still forgets things. Pre-installing it eliminates that failure mode completely.

On our $99/mo Pro plan and above, we also configure **cross-agent memory sharing** — multiple agents can search the same memory tree, so your SEO agent knows what your support agent learned from customer conversations.

## Hipocampus vs ByteRover vs Manual MEMORY.md

I've tried all three. Here's the honest comparison:

### Manual MEMORY.md (Free, Built-in)

**Pros:** Zero setup. Works immediately. Fine for personal use with one agent doing light tasks.

**Cons:** No search. No compaction. No hierarchy. Doesn't scale past 200 lines. You'll outgrow it in two weeks if you're doing anything serious.

**Best for:** Hobbyists running a single agent for personal tasks.

### ByteRover Memory

**Pros:** Cloud-hosted memory storage. API-based access. Handles persistence without local file management.

**Cons:** External dependency — your memory lives on someone else's server. Latency on every memory read. Monthly cost scales with storage. No compaction tree — it's flat storage with search, not hierarchical summarization. Limited control over how summaries are generated.

**Best for:** Teams who want managed infrastructure and don't mind the dependency.

### Hipocampus

**Pros:** Local-first. All data stays on your machine. 5-level compaction tree with smart thresholds. BM25 + vector search via qmd. Completely free. Full control over summarization quality. Integrates natively with OpenClaw skills system. Supports cross-agent memory sharing.

**Cons:** Requires OpenClaw (not platform-agnostic). Initial setup takes 5 minutes. Compaction uses LLM tokens for summarization above thresholds. You manage your own backups.

**Best for:** Anyone running OpenClaw agents in production. Especially multi-agent setups.

### The Numbers

Here's what we measured over 30 days across our 7-agent fleet:

| Metric | Manual MEMORY.md | Hipocampus |
|--------|-------------------|------------|
| Context rebuilt from scratch | 23 times | 0 times |
| Average session start time | 4.2s | 6.8s |
| Tasks requiring re-explanation | 31% | 3% |
| Token waste on stale context | ~2,100/msg | ~800/msg |
| Agent "I don't know about that" errors | 47 | 4 |

The session start time is 2.6 seconds slower because the agent reads more files. That tradeoff is worth it every single time. Those 2.6 seconds save 15–20 minutes of re-explaining per day, per agent.

## Real Examples From Running Hipocampus in Production

### Example 1: The Auth System Saga

Our platform went through three iterations of the authentication system in one week. Session-based auth, then JWT, then back to session-based with a different cookie strategy. Without Hipocampus, every new session would have the agent trying to implement JWT again because that's what the stale MEMORY.md said.

With Hipocampus, the daily compaction nodes captured each decision and its rationale. When a new session started, the agent read ROOT.md, saw "auth: session-based (third iteration, JWT abandoned due to refresh token complexity)" and picked up exactly where we left off.

### Example 2: Cross-Agent Knowledge

Our QA agent discovered that a specific API endpoint was returning 403s intermittently due to a race condition in the auth middleware. It logged the finding to the daily memory file. Two hours later, our builder agent picked up a task to fix error handling on that same endpoint. Because both agents share the memory tree, the builder agent found the QA report via `qmd query "403 auth middleware"` and fixed the root cause instead of just adding retry logic.

Without shared memory, the builder would have added retries. The underlying bug would have persisted for weeks.

### Example 3: The Compaction Payoff

After 30 days, we had 30 raw daily log files totaling 4,200 lines. The compaction tree compressed that into:
- 30 daily nodes (2,100 lines total — about 50% compression)
- 4 weekly nodes (600 lines total)
- 1 monthly node (180 lines)
- ROOT.md (87 lines)

Searching 87 lines in ROOT.md to find the right weekly node, then reading 150 lines of that weekly summary, is massively faster and cheaper than scanning 4,200 lines of raw logs. The agent finds what it needs in 2 hops instead of brute-forcing through everything.

## Common Mistakes and How to Avoid Them

**Mistake 1: Skipping the protocol block in AGENTS.md.** Hipocampus is installed but the agent doesn't follow the session start sequence. Fix: verify the `<!-- hipocampus:protocol:start -->` block exists in AGENTS.md.

**Mistake 2: Setting cooldownHours to 0 in production.** This runs compaction every single session, which burns tokens and adds latency. Use 0 for testing, 3 for production.

**Mistake 3: Not running qmd update after adding knowledge files.** New files in knowledge/ don't appear in search until the index is rebuilt. Run `qmd update` after adding files, or let the compaction cron handle it.

**Mistake 4: Editing compaction nodes directly.** Daily, weekly, and monthly compaction files are generated artifacts. Editing them manually means your changes get overwritten on the next compaction run. Edit raw daily logs or knowledge files instead.

**Mistake 5: Letting MEMORY.md grow unchecked.** The Adaptive section of MEMORY.md should stay under 50 lines. If it's growing past that, you're not using the compaction tree properly — put detailed context in knowledge/ files and let ROOT.md index them.

## What's Next

Hipocampus is actively developed. The roadmap includes:

- **Automatic knowledge extraction** — identify recurring patterns in daily logs and auto-generate knowledge/ files
- **Memory health scoring** — detect when compaction quality degrades and alert you
- **Multi-workspace search** — query across multiple OpenClaw workspaces from a single agent

If you're running OpenClaw without Hipocampus, you're leaving performance on the table. The setup takes 5 minutes. The payoff starts immediately. Your agents will remember what they learned yesterday, and that changes everything.

Need it pre-configured? [MrDelegate](https://mrdelegate.ai) ships every managed hosting instance with Hipocampus installed, tuned, and running. You focus on what your agents do — we handle making sure they remember it.

## Ready to get started?

[Start your free trial](https://mrdelegate.ai/start) and experience the power of OpenClaw, hosted by MrDelegate.