🧠 MemoryBox

Memory health CLI for Claude Code, OpenClaw, and any markdown-based AI agent.

Install once. Your agent's memory stays lean forever. Zero dependencies.

If this fixed your agent's memory bloat, a ⭐ helps others find it.

Quick Install

curl -fsSL https://raw.githubusercontent.com/Ramsbaby/openclaw-memorybox/main/install.sh | bash

⚡ Quick Start • 📊 Without vs With • 🤖 Claude Code • 💻 CLI • 📈 Results • 🔧 How It Works • 🔄 Daemon • ❓ FAQ

Full diagnostic in one command: health check → size analysis → duplicates → stale content → suggestions

⚡ Quick Start

3 commands. 30 seconds.

# 1. Install (one-liner)
curl -fsSL https://raw.githubusercontent.com/Ramsbaby/openclaw-memorybox/main/install.sh | bash

# 2. Diagnose
memorybox doctor ~/openclaw         # OpenClaw
memorybox doctor ~/.claude          # Claude Code

# 3. Fix (if needed)
memorybox split ~/openclaw          # interactive: move large sections to domain files
memorybox archive ~/openclaw        # move old logs to archive/

Verify install:

memorybox --version   # memorybox v2.3.0

git clone https://github.com/Ramsbaby/openclaw-memorybox.git
cd openclaw-memorybox && chmod +x bin/memorybox
sudo ln -sf "$(pwd)/bin/memorybox" /usr/local/bin/memorybox

📊 Without vs With MemoryBox

The crash chain MemoryBox prevents:

Memory bloat → Context overflow → Compaction failure → Gateway crash

🌟 The Problem

Your AI agent's MEMORY.md grows every day. Whether you're running Claude Code, OpenClaw, or any 24/7 agent — at some point it hits 20KB+, gets loaded into every session, eats tokens, and eventually causes context overflow or crashes.

MemoryBox prevents this in 5 minutes:

memorybox doctor ~/openclaw   # diagnose
memorybox split ~/openclaw    # fix interactively

Your MEMORY.md stays lean. Your agent stays fast. Move on to things that matter.

2026 context: Personal AI agents running 24/7 locally are surging — subscription fatigue is real, and "own your AI" is the new default. Memory management is now the #1 silent bottleneck. MemoryBox solves it before it crashes you.

🔧 How It Works

MemoryBox applies a simple 3-tier pattern (inspired by Letta/MemGPT):

workspace/
├── MEMORY.md              ← Tier 1: Core facts only (≤10KB, loaded everywhere)
└── memory/
    ├── YYYY-MM-DD.md      ← Tier 1.5: Daily logs (today+yesterday, auto-loaded)
    ├── domains/           ← Tier 2: Detailed reference (searched on-demand)
    │   ├── persona.md
    │   ├── decisions.md
    │   └── ...
    ├── projects/          ← Tier 2: Per-project context
    └── archive/           ← Tier 3: Old daily logs (14+ days)

Key insight: OpenClaw's memory_search indexes memory/**/*.md recursively. Tier 2 files are automatically searchable — zero config changes needed.

🤖 Claude Code Compatibility

MemoryBox works directly with Claude Code's CLAUDE.md / AGENTS.md workflow.

Point it at your Claude workspace:

memorybox doctor ~/.claude

Or set the workspace once:

export OPENCLAW_WORKSPACE=~/.claude
memorybox doctor    # uses ~/.claude automatically

Add to your CLAUDE.md or AGENTS.md

## Memory Health Protocol

- Check health: `memorybox health ~/.claude`
- If score < 80: run `memorybox doctor ~/.claude` and follow the suggestions
- NEVER delete files in memory/ directly — use `memorybox archive` instead
- After restructuring: memory/ is RAG-indexed on the next rag-index run
- Large MEMORY.md (≥10KB): run `memorybox split` interactively
- Search memory: `memorybox search "<query>" ~/.claude`

Claude Code + Daemon (fully automated)

# Start the health watcher before beginning a long Claude Code session
MEMORYBOX_WORKSPACE=~/.claude \
MEMORYBOX_NTFY_TOPIC=your-ntfy-topic \
bash /path/to/memorybox-watch.sh --daemon

# It runs in the background while you work.
# If memory health degrades mid-session, you get a push notification.

Auto-capture at session end (Claude Code hook)

{
  "hooks": {
    "Stop": [{"command": "bash ~/.local/share/memorybox/session-end-hook.sh"}]
  }
}

Install the hook:

mkdir -p ~/.local/share/memorybox
curl -fsSL https://raw.githubusercontent.com/Ramsbaby/openclaw-memorybox/main/scripts/session-end-hook.sh \
  -o ~/.local/share/memorybox/session-end-hook.sh
chmod +x ~/.local/share/memorybox/session-end-hook.sh

📈 Real Results

Tested on a production instance (7 Discord channels, 48 crons, running 24/7):

Real Terminal Output

Before:

$ memorybox health ~/openclaw
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
🏥 Health Score: 28/100 🚨 CRITICAL

  ✗ MEMORY.md over limit: 20,542 bytes (205%) 🚨
  △ 8 daily logs need archiving (>14 days)
  △ 12 potential duplicate lines

ACTION REQUIRED: Run 'memorybox doctor' for full diagnostic
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

After (5 minutes of interactive splitting + archiving):

$ memorybox health ~/openclaw
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
🏥 Health Score: 92/100 ✅ EXCELLENT

  ✓ MEMORY.md: 3,460 bytes (35%)
  ✓ domains/: 3 files
  ✓ Daily logs up to date
  ✓ memory/ root is clean
  ✓ archive/ exists

All systems green. No action needed.
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Honest note: The 83% reduction applies to MEMORY.md load — roughly 5-15% of total per-session tokens depending on conversation length. But in a 24/7 agent with 48 crons, those savings compound over thousands of sessions. More importantly, it prevents the context overflow that crashes your agent — and that's worth far more than the token savings alone.

💻 CLI Commands

memorybox doctor [path]           # Full diagnostic — start here
memorybox analyze [path]          # Section-by-section size breakdown with bar charts
memorybox split [path]            # Interactive: move large sections to domain files
memorybox health [path]           # Quick health score (0-100)
memorybox search "<query>" [path] # Search memory files for matching content
memorybox archive [path]          # Move old daily logs (14+ days) to archive/
memorybox dedupe [path]           # Find duplicate content across files
memorybox stale [path]            # Detect outdated content
memorybox suggest [path]          # Improvement recommendations
memorybox report [path]           # Before/after token savings
memorybox init [path]             # Set up 3-tier directory structure

Daemon mode (v2.2):

bash scripts/memorybox-watch.sh --daemon   # start background health watcher
bash scripts/memorybox-watch.sh --status   # check watcher status
bash scripts/memorybox-watch.sh --stop     # stop watcher

Most users only need two commands:

1. memorybox doctor — see what's wrong
2. memorybox split — fix it interactively

Options

memorybox -w ~/my-workspace doctor   # custom workspace path
memorybox -d 7 archive               # archive logs older than 7 days (default: 14)
memorybox -m 8000 health             # custom max target (default: 10KB)

🏥 Example: Doctor Output

🩺 MemoryBox Doctor — Full Diagnostic
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Workspace: /Users/you/openclaw
2026-02-11 17:00:00

[1/5] Health Check

    ✗ MEMORY.md over limit: 20,542 bytes (205%) 🚨
    ✓ domains/: 3 files
    △ 8 daily logs need archiving (>14 days)
    ✓ memory/ root is clean
    ✓ archive/ exists

    Health Score: 40/100 🚨 Critical

[2/5] Size Analysis

  MEMORY.md: 20,542 bytes (205%)
  domains/: 3,200 bytes
  Total managed: 23,742 bytes

[3/5] Duplicate Check

  ⚠️  2 potential duplicate lines

[4/5] Stale Content

  ⏰ 1 domain file(s) unchanged for 60+ days

[5/5] Suggestions

  📌 3 section(s) could be split to domains/
  🗄️  8 daily logs ready for archiving

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

🔄 Daemon Mode — memorybox watch (New in v2.2)

Run MemoryBox in the background. Get alerts when your memory health drops below a threshold — before it crashes your agent.

# Start background daemon (checks every 60s, alerts when score < 80)
bash scripts/memorybox-watch.sh --daemon

# With push notifications + custom interval
MEMORYBOX_INTERVAL=120 \
MEMORYBOX_THRESHOLD=85 \
MEMORYBOX_NTFY_TOPIC=your-ntfy-topic \
bash scripts/memorybox-watch.sh --daemon

# With Discord webhook
MEMORYBOX_DISCORD_URL="https://discord.com/api/webhooks/..." \
bash scripts/memorybox-watch.sh --daemon

# Check status
bash scripts/memorybox-watch.sh --status

# Stop
bash scripts/memorybox-watch.sh --stop

What it does

1. Runs memorybox health every N seconds (default: 60)
2. Score drops below threshold → sends alert (ntfy / Discord webhook)
3. Score recovers above threshold → sends recovery notification
4. Logs all checks to ~/.openclaw/logs/memorybox-watch.log
5. State persisted to /tmp/memorybox-watch-state.json

Configuration

Cron alternative (simpler)

If you just want daily checks without a running daemon:

{
  "name": "Memory Health Watch",
  "schedule": "0 9 * * *",
  "prompt": "Run: memorybox health ~/openclaw. If score < 80, run memorybox doctor and report findings."
}

📦 Installation

Option A: One-line install (recommended)

curl -fsSL https://raw.githubusercontent.com/Ramsbaby/openclaw-memorybox/main/install.sh | bash

This installs the CLI to ~/.local/bin/memorybox and the Claude Code skill to ~/.claude/skills/memorybox.md.

Option B: CLI only (legacy)

curl -sSL https://raw.githubusercontent.com/Ramsbaby/openclaw-memorybox/main/bin/memorybox -o /usr/local/bin/memorybox && chmod +x /usr/local/bin/memorybox

Option C: Manual

git clone https://github.com/Ramsbaby/openclaw-memorybox.git
cd openclaw-memorybox && chmod +x bin/memorybox
sudo ln -sf "$(pwd)/bin/memorybox" /usr/local/bin/memorybox

Verify

memorybox --version   # memorybox v2.3.0
memorybox doctor ~/openclaw

🔄 What This Is (and Isn't)

MemoryBox is a maintenance tool, like df for your agent's memory.

It doesn't replace your memory system — it keeps it healthy.

You can use MemoryBox with all of the above, or with none of them. It only touches file structure — never configs, never plugins, never internals.

📖 Origin Story

I run an OpenClaw agent 24/7 — 7 Discord channels, 48 cron jobs. As it learned, MEMORY.md ballooned to 20KB+. Every session loaded all of it.

One day, context hit 100%. Compaction corrupted state. I tried to fix the config — and crashed the gateway.

That crash led to openclaw-self-healing (auto-recovery in ~30s). But the root cause was memory bloat. So I built MemoryBox to prevent it from happening again.

Memory bloat → Context overflow → Gateway crash
  → Built self-healing (recover from crashes)
  → Built MemoryBox (prevent the bloat)
  → Problem solved at both ends.

🤖 Teach Your Agent the 3-Tier Pattern

Add to your AGENTS.md:

## Memory Protocol
- **MEMORY.md** (≤10KB): Core facts only. Loaded everywhere — keep it lean.
- **memory/domains/*.md**: Detailed reference. Use `memory_search` to find.
- **memory/archive/**: Old logs. Rarely needed.

When MEMORY.md grows past 8KB, split large sections to domains/.

Set It and Forget It (Optional Cron)

{
  "name": "Memory Maintenance",
  "schedule": { "kind": "cron", "expr": "0 23 * * 0", "tz": "Asia/Seoul" },
  "sessionTarget": "isolated",
  "payload": {
    "kind": "agentTurn",
    "message": "Run: memorybox archive && memorybox health. Report if score < 80."
  }
}

✅ Compatibility

Works with everything:

Does NOT touch:

• openclaw.json — no config changes
• Plugin behavior — no overrides
• OpenClaw internals — files only

🌐 OpenClaw Ecosystem

All MIT licensed, all battle-tested on the same 24/7 production instance.

❓ FAQ

Q: My MEMORY.md is only 5KB. Do I need this? A: Not yet. Bookmark it for when it grows. Or run memorybox health to confirm you're fine.

Q: Will this break my existing setup? A: No. It only creates directories and moves content you approve. Backup is automatic.

Q: Does memory_search find files in subdirectories? A: Yes. OpenClaw indexes memory/**/*.md recursively.

Q: I'm using Mem0/Supermemory. Should I also use this? A: Yes — they solve different problems. Mem0 decides what to remember. MemoryBox keeps your file structure clean so sessions load fast.

Q: Will OpenClaw updates break this? A: Unlikely. This uses standard markdown files in the standard memory directory. OpenClaw's philosophy is "files are source of truth" — that won't change.

Q: I use Claude Code, not OpenClaw. Does this work? A: Yes. Point MEMORYBOX_WORKSPACE at ~/.claude or your project dir. See Claude Code Compatibility.

Q: How does memorybox search work? A: It searches MEMORY.md and all memory/**/*.md files for your query (case-insensitive), showing 2 context lines around each match. Example: memorybox search "API key" ~/.claude

🤝 Contributing

PRs welcome! Areas for improvement:

• Migration script for different workspace layouts
• Automated MEMORY.md size monitoring via cron (see cron template)
• Domain file templates for common use cases
• Integration tests with memory_search
• memorybox watch — daemon mode for continuous monitoring (added in v2.2)
• memorybox search — full-text search across memory files (added in v2.3)
• Qdrant/local vector search integration for Tier 2 semantic retrieval

📜 License

MIT — Do whatever you want.

📊 Star History

Made with 🦞 by @ramsbaby

Battle-tested on a production OpenClaw instance running 24/7 with 48 crons and 7 channels.