Memory Maintenance

Intelligent memory management for OpenClaw agents. Reviews daily notes, suggests MEMORY.md updates, maintains directory health, and auto-cleans old files. Recommended for agents with growing memory footprints.

Security Scan

The skill largely does what it says (reviews local memory files and proposes maintenance) but contains several implementation issues and privacy risks (hardcoded user paths, sourcing of a .env that exports all env vars, and sending local notes to the Gemini CLI) that make the package inconsistent or surprising for general use.

Purpose & Capability

The declared requirements (gemini CLI, jq, GEMINI_API_KEY) align with the stated purpose of running LLM-based reviews and JSON processing. Requiring GEMINI_API_KEY is appropriate for calling Gemini. The binaries and config referenced are proportionate to a memory-review skill.

Instruction Scope

The runtime instructions and scripts read lots of user-local files (memory/YYYY-MM-DD.md, MEMORY.md, USER.md) and package their contents into a prompt sent to the Gemini CLI. That is expected for a review tool, but it means potentially sensitive local data is transmitted to an external model. Also the scripts export and source a workspace .env (see env/credential concerns below).

Install Mechanism

Installation is script-based (no remote download), which reduces supply-chain risk, but the scripts copy themselves into the user's workspace and add a cron job. Multiple scripts contain hardcoded absolute paths pointing at /Users/maxhutchinson/.openclaw/workspace instead of relying consistently on the configurable OPENCLAW_WORKSPACE or $HOME. That hardcoding is an implementation bug and causes incoherence (would fail or operate on the wrong path on other systems).

Credentials

The skill only declares GEMINI_API_KEY, which is reasonable. However the scripts source $WORKSPACE/.env with set -a (exporting all variables), making all .env entries available in the environment when the Gemini CLI runs. That raises the risk that unrelated secrets in .env could be present in the process environment and (depending on how the gemini CLI handles environment data or logs) could be exposed. The skill does not request other unrelated credentials, which is good, but the behavior of exporting an entire .env is disproportionate without explicit guidance.

Persistence & Privilege

The skill installs cron jobs and copies executable scripts into the workspace so it will run daily (persistent presence). always:false is set, so it is not forcibly injected into every agent, but the install creates a scheduled, autonomous job — this is expected for a maintenance tool but worth noting because it gives the skill recurring execution privileges on the host.

What to consider before installing

Key things to consider before installing: - Privacy: The review script builds a prompt containing your recent daily notes, MEMORY.md, and USER.md and sends it to the Gemini CLI (external model). If those files contain sensitive data (passwords, tokens, personal data), they will be included in requests to an external service. Only install if you're comfortable with that or you sanitize files first. - .env export: The scripts source and export all variables from workspace/.env. Ensure that file does not contain other secrets you don't want exported or sent to the model. Consider giving GEMINI_API_KEY a restricted key or setting it only for this skill's runtime. - Hardcoded paths & portability: Several scripts use /Users/maxhutchinson/.openclaw/workspace hardcoded. This will likely fail or behave unexpectedly on other machines. Inspect and fix these paths (replace with OPENCLAW_WORKSPACE or $HOME/.openclaw/workspace) before installing broadly. - Review and test first: Run the review script in a safe test workspace (with non-sensitive sample files) to confirm behavior. Check where files are moved (archive/.trash) and verify the retention behavior meets your expectations. - Code quality issues: There are bugs (argument parsing in apply.sh mis-indents the --all handling) and rough edges; treat this as alpha software and review scripts before granting production use. - If you proceed: backup your workspace (or at least agents/memory and MEMORY.md), remove unrelated secrets from workspace/.env, and run install in a controlled environment. If you need strict privacy, do not use an external LLM or run the LLM step locally with a model you trust.

Memory Maintenance Skill

Intelligent memory management for OpenClaw agents. Reviews daily notes, suggests MEMORY.md updates, maintains directory health, and auto-cleans old files.

Why This Exists

Agents wake up fresh every session. Without maintenance:

• Daily notes pile up and become unsearchable
• Important decisions get buried in old sessions
• Context windows fill with irrelevant history
• You repeat the same context-setting every day

This skill automates the tedious work of keeping your agent's memory organized and actionable.

Features

• Content Review: Analyzes daily notes and suggests MEMORY.md updates
• Directory Health: Monitors memory/ directory for naming issues, fragmentation, bloat
• Auto-Cleanup: Archives old reviews (7+ days) and enforces retention policy (30 days)
• Safe by Default: Content changes require approval; only safe maintenance auto-applies

Recommended Model

This skill works well with lightweight models. We recommend:

• Primary: gemini-2.5-flash (fast, cost-effective)
• Fallback: gemini-2.5-flash-lite (if rate limits hit)

Both handle the structured output and analysis tasks efficiently.

Quick Start

# Install the skill
clawhub install memory-maintenance

# Configure (optional)
# Edit config/settings.json to customize schedule, retention, etc.

# Run manually
openclaw skill memory-maintenance run

# Or let it run automatically via cron (configured during install)

Architecture

Daily Session Notes (memory/YYYY-MM-DD.md)
    ↓
Review Agent (scheduled daily)
    ↓
Structured Suggestions (JSON)
    ↓
Human Review (markdown report)
    ↓
Approved Updates → MEMORY.md
    ↓
Auto-Cleanup (archive old files)

Workflow

1. Daily Review (23:00 by default)

   • Scans configurable lookback period (default: 7 days)
   • Checks memory/ directory health
   • Generates suggestions via LLM
   • Outputs structured JSON + human-readable markdown

2. Human Review

   • Read agents/memory/review-v2-YYYY-MM-DD.md
   • Approve/reject suggestions

3. Apply Changes

   # Dry run (preview)
   openclaw skill memory-maintenance apply --dry-run 2026-02-05
   
   # Apply safe changes (archiving, cleanup)
   openclaw skill memory-maintenance apply --safe 2026-02-05
   
   # Apply all (requires confirmation)
   openclaw skill memory-maintenance apply --all 2026-02-05
   

4. Auto-Cleanup (runs after successful review)

   • Archives reviews older than configured threshold
   • Deletes archive files older than retention period
   • Cleans up error logs

Configuration

Edit config/settings.json:

{
  "schedule": {
    "enabled": true,
    "time": "23:00",
    "timezone": "Europe/London"
  },
  "review": {
    "lookback_days": 7,
    "model": "gemini-2.5-flash",
    "max_suggestions": 10
  },
  "maintenance": {
    "archive_after_days": 7,
    "retention_days": 30,
    "consolidate_fragments": true,
    "auto_archive_safe": true
  },
  "safety": {
    "require_approval_for_content": true,
    "require_approval_for_delete": true,
    "trash_instead_of_delete": true
  }
}

Safety

• Content suggestions: Never auto-applied (human review mandatory)
• Safe maintenance (archiving): Auto-applied with --safe
• Risky operations (delete, rename): Require --all + confirmation
• Trash recovery: Deleted files go to agents/memory/.trash/ (recoverable for retention period)

Commands

# Run review manually
openclaw skill memory-maintenance review

# Apply changes
openclaw skill memory-maintenance apply [--dry-run|--safe|--all] DATE

# Run cleanup
openclaw skill memory-maintenance cleanup

# Check status
openclaw skill memory-maintenance status

# View stats
openclaw skill memory-maintenance stats

Integration with MEMORY.md

The skill suggests updates to standard MEMORY.md sections:

• Agent Identity and Core Preferences
• Infrastructure/Setup
• Memory Management
• Backup & Migration
• Contacts
• Scheduled Operations
• Content Creation & Projects
• Active Projects

Files

Output

• agents/memory/review-v2-YYYY-MM-DD.json — Structured suggestions
• agents/memory/review-v2-YYYY-MM-DD.md — Human-readable report
• agents/memory/stats.json — Aggregate statistics

Archive

• agents/memory/archive/YYYY-MM/ — Monthly buckets
• agents/memory/.trash/ — Recoverable deletions

Requirements

• OpenClaw >= 2026.2.0
• Gemini CLI (brew install gemini-cli)
• jq (brew install jq)
• Gemini API key (from Google AI Studio)

Troubleshooting

"Gemini failed" → Check GEMINI_API_KEY is set in .env or environment

"No suggestions generated" → Check daily notes exist in memory/YYYY-MM-DD.md → Review error logs in agents/memory/error-*.txt

"Too many maintenance tasks" → Run openclaw skill memory-maintenance apply --safe to archive old files → Adjust archive_after_days in config

Author

Built by Max Hutchinson as part of an AI agent infrastructure exploration.

• GitHub: @MaxLaurieHutchinson
• Agent: Ash (OpenClaw)

License

MIT — Free to use, modify, distribute.

---

Part of the Hybrid Agent Architecture. Built for agents that improve over time.