OpenClaw Maintenance (Memory + Sessions)

Two scripts that keep your OpenClaw instance lean: memory organization and session cleanup. Run nightly via cron or manually when memory files pile up in root, session folders bloat, or disk space runs low.

intent

this skill maintains openclaw's memory and session storage by running two complementary scripts. the memory organizer sorts loose markdown files from ~/.openclaw/workspace/memory/ root into topic subfolders based on keyword matching, adds yaml frontmatter, and updates INDEX.md in each folder. the session cleanup script purges tombstones, old cron sessions, orphan files, and stale entries across all registered agents while preserving active and main sessions. use this skill when memory files are disorganized, session folders are bloated, disk space is low, or to set up automated daily maintenance. triggers: "clean sessions", "organize memory", "maintenance", "session bloat", "memory cleanup", "free disk space", "nightly cleanup".

inputs

local environment

• OPENCLAW_HOME: path to openclaw root directory (defaults to ~/.openclaw)
• OPENCLAW_WORKSPACE: path to workspace root (defaults to ~/.openclaw/workspace)
• memory directory: $OPENCLAW_WORKSPACE/memory/
• agent directories: $OPENCLAW_HOME/agents/*/sessions/

python runtime

• python 3.7+
• standard library only (no external deps): os, json, pathlib, datetime, re, shutil

file system access

• read/write on memory/ directory and all topic subfolders
• read/write on all agent sessions/ directories and sessions.json files
• ability to create backups of sessions.json

no external api connections required , this is pure local file maintenance.

procedure

part 1: memory organizer

1. scan root memory directory

   • input: $OPENCLAW_WORKSPACE/memory/
   • list all .md files in the root (not in subfolders)
   • output: list of file paths

2. categorize each file by keyword matching

   • for each .md file, read the filename and first 500 chars of content
   • match against routing rules (case-insensitive substring match):
     • cabinet/ , keywords: agent, cron, delegation, cabinet agent names
     • content/ , keywords: post, blog, marketing, seo, clips
     • products/ , keywords: copanion, hypercho, feature, ui, roadmap
     • technical/ , keywords: bug, error, config, docs, gateway
     • x/ , keywords: twitter, viral, engagement, followers
     • user/ , keywords: ziwen, founder, personal
     • daily/ , fallback (catch-all)
   • output: dict mapping each file to its target folder

3. add yaml frontmatter if missing

   • for each file, check if it starts with --- yaml block
   • if missing, generate frontmatter:
     • topic: (from categorization step 2)
     • date: (file modification date, or today if unavailable)
     • tags: (empty list, or infer from keywords if desired)
   • if frontmatter exists, leave it untouched
   • output: each file either unchanged or prepended with frontmatter

4. move file to topic folder

   • create topic subfolder if it does not exist: memory/<topic>/
   • move file from memory/<filename>.md to memory/<topic>/<filename>.md
   • skip if file already in correct topic subfolder (idempotent)
   • output: file relocated or skipped

5. update INDEX.md in topic folder

   • check if memory/<topic>/INDEX.md exists
   • if not, create it with a header and empty list
   • append (or update) an entry for the moved file: - [[<filename>]] with optional date/tags
   • avoid duplicates: check if entry already exists before appending
   • output: INDEX.md updated or created

part 2: session cleanup

1. discover all agents

   • input: $OPENCLAW_HOME/agents/
   • scan for subdirectories, each is one agent
   • for each agent, check if sessions/ folder exists
   • output: list of agent names and their session paths

2. back up sessions.json

   • for each agent with a sessions.json file
   • copy to sessions.json.bak-<timestamp>
   • output: backup file path (or skip if already backed up today)

3. list all session files on disk

   • input: sessions/ folder for the agent
   • list all .jsonl files and special files (tombstones: .reset.*, .deleted.*, .bak-*)
   • output: dict mapping filename to modification time

4. read sessions.json (active session registry)

   • input: sessions.json for the agent
   • parse json to get list of session names and metadata (type, created_at, is_locked, etc.)
   • output: dict keyed by session name

5. apply retention policy to tombstones and orphans

   • for each tombstone file (.reset.*, .deleted.*, .bak-*): delete immediately (0 day retention)
   • for each .jsonl file not in sessions.json (orphan): delete immediately
   • output: files deleted or marked for deletion

6. apply retention policy to cron sessions

   • for each session in sessions.json with type: "cron":
     • if created_at > 7 days ago, remove entry from sessions.json
     • also delete the corresponding .jsonl file on disk if it exists
   • for each stale cron session on disk (in sessions/ but not in sessions.json and older than 7 days): delete
   • output: cron session entries and files deleted

7. apply retention policy to other sessions

   • non-cron sessions: keep for 30 days (delete file and entry if older)
   • main sessions: never delete (even if inactive)
   • active sessions (.lock file present): never delete
   • output: sessions deleted or retained

8. validate sessions.json after cleanup

   • remove any entries for files that no longer exist on disk
   • ensure no orphaned entries remain
   • output: cleaned sessions.json

9. write sessions.json back

   • if --dry-run flag: do not write, only report what would be deleted
   • otherwise: write updated sessions.json (backup already created in step 2)
   • output: sessions.json written or preview displayed

decision points

if file already in correct topic subfolder

• do not move it (idempotent, safe to run repeatedly)

if frontmatter exists in memory file

• preserve it as-is, do not overwrite

if memory file matches multiple keyword categories

• use first match in priority order: cabinet > content > products > technical > x > user > daily

if INDEX.md entry for file already exists

• do not append duplicate, skip

if sessions.json does not exist for an agent

• create a new empty one (or skip that agent, depending on implementation)

if --dry-run flag is set

• print what would be deleted, do not modify files or sessions.json

if --agent flag is set

• run cleanup only for that single agent, not all

if session file has .lock present

• never delete it, regardless of age or type

if backup sessions.json.bak- already exists today

• reuse it, do not create duplicate backups

if file system operation fails (permission denied, disk full, etc.)

• log error and continue with next file/session (non-fatal)
• do not stop the entire script on a single failure

output contract

memory organizer outputs

• each .md file moved from memory/ root to memory/<topic>/
• each file prepended with yaml frontmatter block (if missing)
• each memory/<topic>/INDEX.md created or updated with file entries
• no files or folders deleted, only created and moved
• stdout: line-by-line report of actions taken (file moved, INDEX.md updated, etc.)

session cleanup outputs

• tombstone files deleted from all agent sessions/ directories
• orphan .jsonl files deleted
• cron sessions older than 7 days removed from sessions.json and disk
• stale sessions.json entries removed (missing files, expired entries)
• non-cron sessions older than 30 days deleted
• sessions.json.bak-<timestamp> backup created before any modifications
• stdout: report of deleted sessions, freed space (if available), errors
• exit code: 0 on success, non-zero on critical failure (e.g., cannot read agents dir)

if --dry-run

• stdout: preview of what would be deleted (no actual deletions)
• no files modified, sessions.json not written
• exit code: 0

outcome signal

memory organizer success

• loose .md files no longer sit in memory/ root (all moved to topic subfolders)
• each file has a yaml frontmatter block with topic, date, tags
• each topic subfolder has an up-to-date INDEX.md listing its files
• script completes with "all files organized" or similar message

session cleanup success

• no tombstone, orphan, or expired cron session files on disk
• sessions.json contains only valid, active, or recent sessions
• backup of sessions.json created before cleanup
• stdout reports number of files deleted and approximate space freed
• script runs to completion without fatal errors

both scripts via cron

• cron task executes daily at midnight
• both memory organizer and session cleanup run to completion
• no errors logged in cron output (or only non-fatal errors handled gracefully)
• openclaw instance maintains lean memory and session storage over time