{"id":48085246,"url":"https://github.com/Ramsbaby/openclaw-memorybox","last_synced_at":"2026-04-20T01:00:54.628Z","repository":{"id":337554831,"uuid":"1154159499","full_name":"Ramsbaby/openclaw-memorybox","owner":"Ramsbaby","description":"🧠 Install once, forget about memory management. Zero-dependency maintenance CLI for OpenClaw agents. Works alongside Mem0, Supermemory, QMD.","archived":false,"fork":false,"pushed_at":"2026-03-25T08:09:31.000Z","size":371,"stargazers_count":8,"open_issues_count":0,"forks_count":3,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-03-26T08:57:00.953Z","etag":null,"topics":["ai-agents","anthropic","claude-code","context-management","knowledge-base","memory","persistent-memory","slash-commands"],"latest_commit_sha":null,"homepage":"https://ramsbaby.netlify.app","language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Ramsbaby.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-02-10T04:30:25.000Z","updated_at":"2026-03-25T08:09:39.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/Ramsbaby/openclaw-memorybox","commit_stats":null,"previous_names":["ramsbaby/openclaw-memorybox"],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/Ramsbaby/openclaw-memorybox","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Ramsbaby%2Fopenclaw-memorybox","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Ramsbaby%2Fopenclaw-memorybox/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Ramsbaby%2Fopenclaw-memorybox/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Ramsbaby%2Fopenclaw-memorybox/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Ramsbaby","download_url":"https://codeload.github.com/Ramsbaby/openclaw-memorybox/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Ramsbaby%2Fopenclaw-memorybox/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32028547,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-20T00:18:06.643Z","status":"ssl_error","status_checked_at":"2026-04-20T00:17:31.068Z","response_time":55,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-agents","anthropic","claude-code","context-management","knowledge-base","memory","persistent-memory","slash-commands"],"created_at":"2026-04-04T15:14:13.317Z","updated_at":"2026-04-20T01:00:54.615Z","avatar_url":"https://github.com/Ramsbaby.png","language":"Shell","funding_links":[],"categories":["Skills \u0026 Plugins","Ecosystem"],"sub_categories":["Notable Skills \u0026 Plugins","Quick Setup with cc-safe-setup"],"readme":"# 🧠 MemoryBox\n\n\u003e **Memory health CLI for Claude Code, OpenClaw, and any markdown-based AI agent.**\n\u003e\n\u003e Install once. Your agent's memory stays lean forever. Zero dependencies.\n\n[![GitHub stars](https://img.shields.io/github/stars/Ramsbaby/openclaw-memorybox?style=social)](https://github.com/Ramsbaby/openclaw-memorybox/stargazers)\n[![CI](https://github.com/Ramsbaby/openclaw-memorybox/actions/workflows/ci.yml/badge.svg)](https://github.com/Ramsbaby/openclaw-memorybox/actions)\n[![Lint](https://github.com/Ramsbaby/openclaw-memorybox/actions/workflows/lint.yml/badge.svg)](https://github.com/Ramsbaby/openclaw-memorybox/actions/workflows/lint.yml)\n[![Version](https://img.shields.io/badge/version-2.3.0-blue.svg)](https://github.com/Ramsbaby/openclaw-memorybox/releases)\n[![OpenClaw Compatible](https://img.shields.io/badge/OpenClaw-Compatible-blue)](https://github.com/openclaw/openclaw)\n[![Claude Code Compatible](https://img.shields.io/badge/Claude%20Code-Compatible-blueviolet)](README.md#-claude-code-compatibility)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![ShellCheck](https://img.shields.io/badge/ShellCheck-passing-brightgreen)](https://www.shellcheck.net/)\n![Last commit](https://img.shields.io/github/last-commit/Ramsbaby/openclaw-memorybox)\n\n\u003e If this fixed your agent's memory bloat, a ⭐ helps others find it.\n\n## Quick Install\n\n```bash\ncurl -fsSL https://raw.githubusercontent.com/Ramsbaby/openclaw-memorybox/main/install.sh | bash\n```\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"docs/assets/hero.svg\" alt=\"openclaw-memorybox\" width=\"100%\"\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"#-quick-start\"\u003e⚡ Quick Start\u003c/a\u003e •\n  \u003ca href=\"#-without-vs-with-memorybox\"\u003e📊 Without vs With\u003c/a\u003e •\n  \u003ca href=\"#-claude-code-compatibility\"\u003e🤖 Claude Code\u003c/a\u003e •\n  \u003ca href=\"#-cli-commands\"\u003e💻 CLI\u003c/a\u003e •\n  \u003ca href=\"#-real-results\"\u003e📈 Results\u003c/a\u003e •\n  \u003ca href=\"#-how-it-works\"\u003e🔧 How It Works\u003c/a\u003e •\n  \u003ca href=\"#-daemon-mode----memorybox-watch-new-in-v22\"\u003e🔄 Daemon\u003c/a\u003e •\n  \u003ca href=\"#-faq\"\u003e❓ FAQ\u003c/a\u003e\n\u003c/p\u003e\n\n\u003cbr/\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"https://raw.githubusercontent.com/Ramsbaby/openclaw-memorybox/main/assets/demo.gif\" alt=\"MemoryBox Demo\" /\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\u003cem\u003eFull diagnostic in one command: health check → size analysis → duplicates → stale content → suggestions\u003c/em\u003e\u003c/p\u003e\n\n---\n\n## ⚡ Quick Start\n\n\u003e **3 commands. 30 seconds.**\n\n```bash\n# 1. Install (one-liner)\ncurl -fsSL https://raw.githubusercontent.com/Ramsbaby/openclaw-memorybox/main/install.sh | bash\n\n# 2. Diagnose\nmemorybox doctor ~/openclaw         # OpenClaw\nmemorybox doctor ~/.claude          # Claude Code\n\n# 3. Fix (if needed)\nmemorybox split ~/openclaw          # interactive: move large sections to domain files\nmemorybox archive ~/openclaw        # move old logs to archive/\n```\n\n**Verify install:**\n```bash\nmemorybox --version   # memorybox v2.3.0\n```\n\n\u003cdetails\u003e\n\u003csummary\u003eOption B: Manual install (git clone)\u003c/summary\u003e\n\n```bash\ngit clone https://github.com/Ramsbaby/openclaw-memorybox.git\ncd openclaw-memorybox \u0026\u0026 chmod +x bin/memorybox\nsudo ln -sf \"$(pwd)/bin/memorybox\" /usr/local/bin/memorybox\n```\n\n\u003c/details\u003e\n\n---\n\n## 📊 Without vs With MemoryBox\n\n| | Without MemoryBox | With MemoryBox |\n|--|---|---|\n| **MEMORY.md size** | Grows unbounded (20KB+) | Capped at ~3.5KB |\n| **Every session loads** | Everything (all 20KB) | Core facts only (3.5KB) |\n| **Context pressure** | 98% → compaction failures | 7% → comfortable headroom |\n| **Agent crashes** | 2–3/week from context overflow | 0 |\n| **Setup time** | — | 5 minutes, one-time |\n| **Maintenance** | Manual or never | Automated via cron/daemon |\n| **Old logs** | Accumulate in root | Auto-archived after 14 days |\n\n**The crash chain MemoryBox prevents:**\n```\nMemory bloat → Context overflow → Compaction failure → Gateway crash\n```\n\n---\n\n## 🌟 The Problem\n\nYour 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.\n\nMemoryBox prevents this in 5 minutes:\n\n```bash\nmemorybox doctor ~/openclaw   # diagnose\nmemorybox split ~/openclaw    # fix interactively\n```\n\nYour MEMORY.md stays lean. Your agent stays fast. **Move on to things that matter.**\n\n\u003e **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.\n\n---\n\n## 🔧 How It Works\n\nMemoryBox applies a simple 3-tier pattern (inspired by [Letta/MemGPT](https://github.com/letta-ai/letta)):\n\n```\nworkspace/\n├── MEMORY.md              ← Tier 1: Core facts only (≤10KB, loaded everywhere)\n└── memory/\n    ├── YYYY-MM-DD.md      ← Tier 1.5: Daily logs (today+yesterday, auto-loaded)\n    ├── domains/           ← Tier 2: Detailed reference (searched on-demand)\n    │   ├── persona.md\n    │   ├── decisions.md\n    │   └── ...\n    ├── projects/          ← Tier 2: Per-project context\n    └── archive/           ← Tier 3: Old daily logs (14+ days)\n```\n\n| Tier | Loaded when | Token cost |\n|------|------------|------------|\n| **Tier 1** | Every session, automatically | ~3.5KB (lean!) |\n| **Tier 2** | On-demand via `memory_search` | Only when needed |\n| **Tier 3** | Manual reference only | ~0 |\n\n**Key insight:** OpenClaw's `memory_search` indexes `memory/**/*.md` recursively. Tier 2 files are automatically searchable — zero config changes needed.\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"docs/assets/lifecycle.svg\" alt=\"Memory hygiene lifecycle\" width=\"100%\"\u003e\n\u003c/p\u003e\n\n---\n\n## 🤖 Claude Code Compatibility\n\nMemoryBox works directly with Claude Code's `CLAUDE.md` / `AGENTS.md` workflow.\n\n**Point it at your Claude workspace:**\n```bash\nmemorybox doctor ~/.claude\n```\n\n**Or set the workspace once:**\n```bash\nexport OPENCLAW_WORKSPACE=~/.claude\nmemorybox doctor    # uses ~/.claude automatically\n```\n\n### Add to your `CLAUDE.md` or `AGENTS.md`\n\n```markdown\n## Memory Health Protocol\n\n- Check health: `memorybox health ~/.claude`\n- If score \u003c 80: run `memorybox doctor ~/.claude` and follow the suggestions\n- NEVER delete files in memory/ directly — use `memorybox archive` instead\n- After restructuring: memory/ is RAG-indexed on the next rag-index run\n- Large MEMORY.md (≥10KB): run `memorybox split` interactively\n- Search memory: `memorybox search \"\u003cquery\u003e\" ~/.claude`\n```\n\n### Claude Code + Daemon (fully automated)\n\n```bash\n# Start the health watcher before beginning a long Claude Code session\nMEMORYBOX_WORKSPACE=~/.claude \\\nMEMORYBOX_NTFY_TOPIC=your-ntfy-topic \\\nbash /path/to/memorybox-watch.sh --daemon\n\n# It runs in the background while you work.\n# If memory health degrades mid-session, you get a push notification.\n```\n\n### Auto-capture at session end (Claude Code hook)\n\n```json\n{\n  \"hooks\": {\n    \"Stop\": [{\"command\": \"bash ~/.local/share/memorybox/session-end-hook.sh\"}]\n  }\n}\n```\n\nInstall the hook:\n```bash\nmkdir -p ~/.local/share/memorybox\ncurl -fsSL https://raw.githubusercontent.com/Ramsbaby/openclaw-memorybox/main/scripts/session-end-hook.sh \\\n  -o ~/.local/share/memorybox/session-end-hook.sh\nchmod +x ~/.local/share/memorybox/session-end-hook.sh\n```\n\n---\n\n## 📈 Real Results\n\nTested on a production instance (7 Discord channels, 48 crons, running 24/7):\n\n| Metric | Before | After | Improvement |\n|--------|--------|-------|-------------|\n| **MEMORY.md size** | 20,542 bytes | 3,460 bytes | **-83%** |\n| **Context pressure** | 98% (critical) | 7% (healthy) | **-91%** |\n| **Compaction frequency** | Multiple per session | Rare (~weekly) | **10x fewer** |\n| **Gateway crashes** | 2-3/week | **0** | **100% stable** |\n| **`memory_search`** | Works | Still works | No change |\n| **Setup time** | — | **5 minutes** | One-time |\n\n### Real Terminal Output\n\n**Before:**\n```\n$ memorybox health ~/openclaw\n━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n🏥 Health Score: 28/100 🚨 CRITICAL\n\n  ✗ MEMORY.md over limit: 20,542 bytes (205%) 🚨\n  △ 8 daily logs need archiving (\u003e14 days)\n  △ 12 potential duplicate lines\n\nACTION REQUIRED: Run 'memorybox doctor' for full diagnostic\n━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n```\n\n**After (5 minutes of interactive splitting + archiving):**\n```\n$ memorybox health ~/openclaw\n━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n🏥 Health Score: 92/100 ✅ EXCELLENT\n\n  ✓ MEMORY.md: 3,460 bytes (35%)\n  ✓ domains/: 3 files\n  ✓ Daily logs up to date\n  ✓ memory/ root is clean\n  ✓ archive/ exists\n\nAll systems green. No action needed.\n━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n```\n\n\u003e **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.\n\n---\n\n## 💻 CLI Commands\n\n```bash\nmemorybox doctor [path]           # Full diagnostic — start here\nmemorybox analyze [path]          # Section-by-section size breakdown with bar charts\nmemorybox split [path]            # Interactive: move large sections to domain files\nmemorybox health [path]           # Quick health score (0-100)\nmemorybox search \"\u003cquery\u003e\" [path] # Search memory files for matching content\nmemorybox archive [path]          # Move old daily logs (14+ days) to archive/\nmemorybox dedupe [path]           # Find duplicate content across files\nmemorybox stale [path]            # Detect outdated content\nmemorybox suggest [path]          # Improvement recommendations\nmemorybox report [path]           # Before/after token savings\nmemorybox init [path]             # Set up 3-tier directory structure\n```\n\n**Daemon mode** (v2.2):\n```bash\nbash scripts/memorybox-watch.sh --daemon   # start background health watcher\nbash scripts/memorybox-watch.sh --status   # check watcher status\nbash scripts/memorybox-watch.sh --stop     # stop watcher\n```\n\n**Most users only need two commands:**\n1. `memorybox doctor` — see what's wrong\n2. `memorybox split` — fix it interactively\n\n### Options\n\n```bash\nmemorybox -w ~/my-workspace doctor   # custom workspace path\nmemorybox -d 7 archive               # archive logs older than 7 days (default: 14)\nmemorybox -m 8000 health             # custom max target (default: 10KB)\n```\n\n---\n\n## 🏥 Example: Doctor Output\n\n```\n🩺 MemoryBox Doctor — Full Diagnostic\n━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\nWorkspace: /Users/you/openclaw\n2026-02-11 17:00:00\n\n[1/5] Health Check\n\n    ✗ MEMORY.md over limit: 20,542 bytes (205%) 🚨\n    ✓ domains/: 3 files\n    △ 8 daily logs need archiving (\u003e14 days)\n    ✓ memory/ root is clean\n    ✓ archive/ exists\n\n    Health Score: 40/100 🚨 Critical\n\n[2/5] Size Analysis\n\n  MEMORY.md: 20,542 bytes (205%)\n  domains/: 3,200 bytes\n  Total managed: 23,742 bytes\n\n[3/5] Duplicate Check\n\n  ⚠️  2 potential duplicate lines\n\n[4/5] Stale Content\n\n  ⏰ 1 domain file(s) unchanged for 60+ days\n\n[5/5] Suggestions\n\n  📌 3 section(s) could be split to domains/\n  🗄️  8 daily logs ready for archiving\n\n━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n```\n\n---\n\n## 🔄 Daemon Mode — `memorybox watch` (New in v2.2)\n\nRun MemoryBox in the background. Get alerts when your memory health drops below a threshold — **before it crashes your agent**.\n\n```bash\n# Start background daemon (checks every 60s, alerts when score \u003c 80)\nbash scripts/memorybox-watch.sh --daemon\n\n# With push notifications + custom interval\nMEMORYBOX_INTERVAL=120 \\\nMEMORYBOX_THRESHOLD=85 \\\nMEMORYBOX_NTFY_TOPIC=your-ntfy-topic \\\nbash scripts/memorybox-watch.sh --daemon\n\n# With Discord webhook\nMEMORYBOX_DISCORD_URL=\"https://discord.com/api/webhooks/...\" \\\nbash scripts/memorybox-watch.sh --daemon\n\n# Check status\nbash scripts/memorybox-watch.sh --status\n\n# Stop\nbash scripts/memorybox-watch.sh --stop\n```\n\n### What it does\n\n1. Runs `memorybox health` every N seconds (default: 60)\n2. Score drops below threshold → sends **alert** (ntfy / Discord webhook)\n3. Score recovers above threshold → sends **recovery** notification\n4. Logs all checks to `~/.openclaw/logs/memorybox-watch.log`\n5. State persisted to `/tmp/memorybox-watch-state.json`\n\n### Configuration\n\n| Env var | Default | Description |\n|---------|---------|-------------|\n| `MEMORYBOX_WORKSPACE` | `~/openclaw` | Workspace path to monitor |\n| `MEMORYBOX_INTERVAL` | `60` | Check interval in seconds |\n| `MEMORYBOX_THRESHOLD` | `80` | Alert when score drops below this |\n| `MEMORYBOX_NTFY_TOPIC` | — | [ntfy.sh](https://ntfy.sh) push topic |\n| `MEMORYBOX_DISCORD_URL` | — | Discord webhook URL |\n| `MEMORYBOX_LOG_DIR` | `~/.openclaw/logs` | Log directory |\n\n### Cron alternative (simpler)\n\nIf you just want daily checks without a running daemon:\n\n```json\n{\n  \"name\": \"Memory Health Watch\",\n  \"schedule\": \"0 9 * * *\",\n  \"prompt\": \"Run: memorybox health ~/openclaw. If score \u003c 80, run memorybox doctor and report findings.\"\n}\n```\n\n---\n\n## 📦 Installation\n\n### Option A: One-line install (recommended)\n\n```bash\ncurl -fsSL https://raw.githubusercontent.com/Ramsbaby/openclaw-memorybox/main/install.sh | bash\n```\n\nThis installs the CLI to `~/.local/bin/memorybox` and the Claude Code skill to `~/.claude/skills/memorybox.md`.\n\n### Option B: CLI only (legacy)\n\n```bash\ncurl -sSL https://raw.githubusercontent.com/Ramsbaby/openclaw-memorybox/main/bin/memorybox -o /usr/local/bin/memorybox \u0026\u0026 chmod +x /usr/local/bin/memorybox\n```\n\n### Option C: Manual\n\n```bash\ngit clone https://github.com/Ramsbaby/openclaw-memorybox.git\ncd openclaw-memorybox \u0026\u0026 chmod +x bin/memorybox\nsudo ln -sf \"$(pwd)/bin/memorybox\" /usr/local/bin/memorybox\n```\n\n### Verify\n\n```bash\nmemorybox --version   # memorybox v2.3.0\nmemorybox doctor ~/openclaw\n```\n\n---\n\n## 🔄 What This Is (and Isn't)\n\n**MemoryBox is a maintenance tool**, like `df` for your agent's memory.\n\nIt doesn't replace your memory system — it keeps it healthy.\n\n| Tool | What it does | Category |\n|------|-------------|----------|\n| **Mem0** | Decides *what* to remember | 🧠 Memory engine |\n| **Supermemory** | Cloud-based persistent recall | 🧠 Memory engine |\n| **QMD** | Local search backend | 🔍 Search engine |\n| **MemoryBox** | Keeps files organized \u0026 lean | 🧹 Maintenance tool |\n\n**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.\n\n---\n\n## 📖 Origin Story\n\nI 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.\n\nOne day, context hit 100%. Compaction corrupted state. I tried to fix the config — and **crashed the gateway**.\n\nThat crash led to **[openclaw-self-healing](https://github.com/Ramsbaby/openclaw-self-healing)** (auto-recovery in ~30s). But the *root cause* was memory bloat. So I built MemoryBox to prevent it from happening again.\n\n```\nMemory bloat → Context overflow → Gateway crash\n  → Built self-healing (recover from crashes)\n  → Built MemoryBox (prevent the bloat)\n  → Problem solved at both ends.\n```\n\n---\n\n## 🤖 Teach Your Agent the 3-Tier Pattern\n\nAdd to your `AGENTS.md`:\n\n```markdown\n## Memory Protocol\n- **MEMORY.md** (≤10KB): Core facts only. Loaded everywhere — keep it lean.\n- **memory/domains/*.md**: Detailed reference. Use `memory_search` to find.\n- **memory/archive/**: Old logs. Rarely needed.\n\nWhen MEMORY.md grows past 8KB, split large sections to domains/.\n```\n\n### Set It and Forget It (Optional Cron)\n\n```json\n{\n  \"name\": \"Memory Maintenance\",\n  \"schedule\": { \"kind\": \"cron\", \"expr\": \"0 23 * * 0\", \"tz\": \"Asia/Seoul\" },\n  \"sessionTarget\": \"isolated\",\n  \"payload\": {\n    \"kind\": \"agentTurn\",\n    \"message\": \"Run: memorybox archive \u0026\u0026 memorybox health. Report if score \u003c 80.\"\n  }\n}\n```\n\n---\n\n## ✅ Compatibility\n\n**Works with everything:**\n\n| Plugin / Backend | Compatible | Notes |\n|-----------------|-----------|-------|\n| memory-core (default) | ✅ | No changes needed |\n| Mem0 | ✅ | Different layer — no conflict |\n| Supermemory | ✅ | Different layer — no conflict |\n| QMD | ✅ | Indexes same files |\n| `memory_search` | ✅ | Indexes `memory/**/*.md` recursively |\n| `memory_get` | ✅ | Reads any `memory/` file |\n| **Claude Code** | ✅ | CLAUDE.md / AGENTS.md friendly |\n\n**Does NOT touch:**\n- `openclaw.json` — no config changes\n- Plugin behavior — no overrides\n- OpenClaw internals — files only\n\n---\n\n## 🌐 OpenClaw Ecosystem\n\n| Project | Role |\n|---------|------|\n| **[openclaw-memorybox](https://github.com/Ramsbaby/openclaw-memorybox)** ← you are here | Zero-dep memory hygiene CLI |\n| **[openclaw-self-healing](https://github.com/Ramsbaby/openclaw-self-healing)** | 4-tier autonomous crash recovery — gateway back in ~30s |\n| **[openclaw-self-evolving](https://github.com/Ramsbaby/openclaw-self-evolving)** | AI agent that proposes its own improvements |\n| **[jarvis](https://github.com/Ramsbaby/jarvis)** | 24/7 AI ops system using Claude Max — self-healing, RAG, cron |\n\nAll MIT licensed, all battle-tested on the same 24/7 production instance.\n\n---\n\n## ❓ FAQ\n\n**Q: My MEMORY.md is only 5KB. Do I need this?**\nA: Not yet. Bookmark it for when it grows. Or run `memorybox health` to confirm you're fine.\n\n**Q: Will this break my existing setup?**\nA: No. It only creates directories and moves content you approve. Backup is automatic.\n\n**Q: Does `memory_search` find files in subdirectories?**\nA: Yes. OpenClaw indexes `memory/**/*.md` recursively.\n\n**Q: I'm using Mem0/Supermemory. Should I also use this?**\nA: Yes — they solve different problems. Mem0 decides *what* to remember. MemoryBox keeps your *file structure* clean so sessions load fast.\n\n**Q: Will OpenClaw updates break this?**\nA: Unlikely. This uses standard markdown files in the standard memory directory. OpenClaw's philosophy is \"files are source of truth\" — that won't change.\n\n**Q: I use Claude Code, not OpenClaw. Does this work?**\nA: Yes. Point `MEMORYBOX_WORKSPACE` at `~/.claude` or your project dir. See [Claude Code Compatibility](#-claude-code-compatibility).\n\n**Q: How does `memorybox search` work?**\nA: 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`\n\n---\n\n## 🤝 Contributing\n\nPRs welcome! Areas for improvement:\n- [ ] Migration script for different workspace layouts\n- [x] Automated MEMORY.md size monitoring via cron *(see [cron template](#-teach-your-agent-the-3-tier-pattern))*\n- [ ] Domain file templates for common use cases\n- [ ] Integration tests with memory_search\n- [x] `memorybox watch` — daemon mode for continuous monitoring *(added in v2.2)*\n- [x] `memorybox search` — full-text search across memory files *(added in v2.3)*\n- [ ] Qdrant/local vector search integration for Tier 2 semantic retrieval\n\n---\n\n## 📜 License\n\nMIT — Do whatever you want.\n\n---\n\n## 📊 Star History\n\n[![Star History Chart](https://api.star-history.com/svg?repos=Ramsbaby/openclaw-memorybox\u0026type=Date)](https://star-history.com/#Ramsbaby/openclaw-memorybox\u0026Date)\n\n---\n\n\u003cp align=\"center\"\u003e\n  \u003cstrong\u003eMade with 🦞 by \u003ca href=\"https://github.com/ramsbaby\"\u003e@ramsbaby\u003c/a\u003e\u003c/strong\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cem\u003eBattle-tested on a production OpenClaw instance running 24/7 with 48 crons and 7 channels.\u003c/em\u003e\n\u003c/p\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FRamsbaby%2Fopenclaw-memorybox","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FRamsbaby%2Fopenclaw-memorybox","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FRamsbaby%2Fopenclaw-memorybox/lists"}