Ghost Mode#

Incognito mode for your OpenClaw agent — like a browser's private window, but for your AI.

Activate, and the agent stops writing to memory. Deactivate, and every trace of the session — logs, memory files, session transcripts, search index entries — is securely scrubbed. Like closing an incognito browser window: the activity never happened, as far as the agent's memory is concerned.

What stays: Any files or local outputs you independently create during the session (code, documents, images, etc.) are not touched — provided OPENCLAW_WORKSPACE and OPENCLAW_HOME are correctly scoped to your OpenClaw installation (not broadly set to $HOME or a parent directory). Ghost Mode only impacts the agent's memory and session history; the scripts enforce this scope at startup and will refuse to run if the env vars point too broadly.

User-controlled, explicit, and auditable. No silent hooks, no background daemons, no automatic interception.

When to Use Ghost Mode#

• Experimental work — Trying an approach you don't want the agent to learn from or reference later. Test something wild, then close the incognito window.
• Sensitive conversations — Discussing personal matters, credentials, or anything you don't want persisting in the agent's long-term memory.
• Exploring bad ideas — Prototyping something you might discard. No point polluting the agent's context with abandoned directions.
• One-off tasks — Quick operations where the agent doesn't need to remember what it did.
• Debugging the agent itself — Testing agent behavior without creating a memory trail that could influence future sessions.
• Shared environments — Using an agent on a machine others can access, and you want to keep certain sessions private.
• Resetting context pressure — The agent accumulates context over time. Ghost Mode lets you have a "clean room" conversation without adding to that weight.

Example Sessions#

Example 1: Quick experiment#

text

You: ghost on
Agent: Ghost mode ON. This session will not be recorded. Memory writes are suppressed until you say "ghost off".

You: Let me try refactoring the auth module with a completely different pattern...
Agent: [works on refactoring, creates files, runs tests]

You: Actually, that didn't work. Let me scrap it.
Agent: [deletes the experimental code]

You: ghost off
Agent: Ghost mode OFF. Session data has been scrubbed. The agent has no memory of this conversation.

Result: The agent's memory is untouched. The experimental refactoring was never recorded. Any files you created or deleted during the session remain as-is.

Example 2: Sensitive discussion#

text

You: ghost on
Agent: Ghost mode ON. This session will not be recorded.

You: I need to test the integration with the staging server using my dev credentials.
Agent: [helps with integration, runs tests against staging]

You: Thanks, that's done. ghost off
Agent: Ghost mode OFF. Session scrubbed. No record of credentials or this conversation remains in my memory.

Result: Credentials were used during the session but never written to daily logs, memory files, or session archives. The agent won't reference them later.

Example 3: Exploring a bad direction#

text

You: ghost on
Agent: Ghost mode ON.

You: What if we rewrite the entire backend in Rust?
Agent: [explores the idea, generates code, benchmarks...]

You: Okay, this is clearly not worth it right now. ghost off
Agent: Ghost mode OFF. Scrubbed. The Rust exploration never happened, as far as my memory is concerned.

Result: The agent won't later suggest Rust or reference the abandoned exploration in future sessions.

Example 4: Checking status#

text

You: ghost status
Agent: Ghost mode: ACTIVE
         Session: ghost-1777145449
         Activated: 2026-04-25T19:30:49Z
         Registry shows 1 session in active state.

---

⚠️ DATA LOSS WARNING — READ BEFORE INSTALLING#

This skill permanently deletes data by design.

When you run ghost off or force-cleanup-all, the skill:

• Scrubbs entries from your daily logs, semantic memory, and episodic memory files
• Archives then shreds session transcripts and checkpoint files using shred -u (secure overwrite, then remove)
• Removes entries from the OpenClaw memory search index

This is irreversible. Deleted files are not recoverable — not from trash, not from backup, not from any undo mechanism. This is the entire point of the skill, not a side effect.

The following scenarios can cause unintended data loss:

• Bugs or errors in the scrubbing logic may remove more content than intended
• Misuse — running ghost off in the wrong session or at the wrong time
• Environment conflicts — if your workspace layout differs from the expected OpenClaw structure, scrubbing may target the wrong files or miss files it should clean
• Partial failures — if the pipeline crashes mid-run, some files may be scrubbed while others remain, leaving your memory in an inconsistent state
• Stale sessions — if a ghost session spans multiple days, scrubbing will affect all entries in that time window across all files, including content from other sessions

By installing this skill, you acknowledge and accept these risks.

Recommended: enable daily OpenClaw workspace backups. A tar or rsync backup of ~/.openclaw/workspace/ and ~/.openclaw/data/ run daily ensures you can recover from unintended data loss. Example:

bash

# Add to crontab for daily 2 AM backup
0 2 * * * tar -czf ~/openclaw-backup-$(date +\%F).tar.gz ~/.openclaw/workspace/ ~/.openclaw/data/

---

How It Works#

1. ghost on — writes a .ghost-mode flag file and registers the session in a local JSON registry

2. Agent reads the flag — on session start, checks for .ghost-mode. If present, suppresses all writes to memory files, daily logs, semantic/episodic files, and MEMORY.md

3. ghost off — removes the flag, then runs a 5-stage cleanup pipeline:

   • Archive → moves session JSONL and checkpoint files to a temporary staging directory
   • Scrub → removes ghost-window entries from daily logs, semantic files, episodic files, and MEMORY.md
   • Index cleanup → removes matching entries from the OpenClaw memory index (SQLite)
   • Verify → 7-layer check confirms no traces remain
   • Shred → secure overwrite + delete of all staged files ( shred -u, falls back to rm with warning)

Each stage is idempotent — re-running is safe and produces the same result.

Quick Start#

bash

# Activate (the agent will also do this when you say "ghost on")
./scripts/ghost_mode.sh on --session-key <key>

# Preview what would be deleted (no changes made)
./scripts/ghost_mode.sh off --dry-run

# Deactivate and scrub (with confirmation prompt)
./scripts/ghost_mode.sh off

# Skip confirmation prompt (for scripted/automated use)
./scripts/ghost_mode.sh off --yes

# Check status (includes config)
./scripts/ghost_mode.sh status

# Force cleanup of stale sessions older than 24 hours
./scripts/ghost_mode.sh force-cleanup-all

Safety Interlocks#

Ghost Mode includes two safety mechanisms to prevent accidental data loss:

1. Confirmation Prompt#

By default, ghost off and force-cleanup-all require interactive confirmation before deleting anything. You must type yes to proceed.

bash

$ ./scripts/ghost_mode.sh off
⚠️  You are about to permanently delete session data.
   This action is IRREVERSIBLE. Deleted data cannot be recovered.

  Type yes to confirm, or anything else to cancel:

• Configurable: Set "confirm_before_delete": false in ghost-mode-config.json to disable prompts.
• Non-interactive fallback: If no terminal is available (e.g., cron, piped input), confirmation is required unless you pass --yes / -y.
• --yes / -y flag: Skips the confirmation prompt entirely. Use in scripts, cron jobs, or automation.

2. Dry-Run Mode#

Every destructive command supports --dry-run — shows exactly what would be deleted without making any changes:

bash

$ ./scripts/ghost_mode.sh off --dry-run
[ghost DRY-RUN] Would archive session files for: ghost-1745695449
[ghost DRY-RUN]   Would copy session JSONL + checkpoints to ~/.openclaw/ghost-archive/
[ghost DRY-RUN]   Would remove originals from sessions directory
[ghost DRY-RUN] Would scrub memory files for session: ghost-1745695449
[ghost DRY-RUN]   Would remove ghost-window entries from: memory/*.md
[ghost DRY-RUN]   Would remove ghost-window entries from: memory/semantic/*.md
[ghost DRY-RUN]   Would remove ghost-window entries from: memory/episodic/*.md
[ghost DRY-RUN]   Would remove promoted ghost entries from: MEMORY.md
[ghost DRY-RUN] Would remove index entries for session: ghost-1745695449
[ghost DRY-RUN]   Would DELETE rows from memory.db matching session ID
[ghost DRY-RUN] Would run 7-layer verification for session: ghost-1745695449
[ghost DRY-RUN] Would secure-delete 3 archived file(s)

• Configurable default: dry_run_by_default is true by default — ghost off starts in dry-run mode. Pass --yes to execute for real. Set "dry_run_by_default": false in config to disable this safety default.

Configuration File#

Create ghost-mode-config.json in your workspace root ( ~/.openclaw/workspace/ghost-mode-config.json):

json

{
  "confirm_before_delete": true,
  "dry_run_by_default": true
}

SettingDefaultDescriptionconfirm_before_delete``trueRequire typing yes before any destructive operation. Set false to disable prompts.dry_run_by_default``trueIf true (default), ghost off and force-cleanup-all start in dry-run mode. Pass --yes to execute for real. Set false to skip dry-run by default.

What This Skill Touches#

PathReadWriteDeleteWhenmemory/.ghost-mode✓✓✓Flag lifecyclememory/.ghost-sessions.json✓✓—Registry state machinememory/YYYY-MM-DD.md✓✓*—Scrub ghost-window entriesmemory/semantic/*.md✓✓*—Scrub ghost-window entriesmemory/episodic/*.md✓✓*—Scrub ghost-window entriesMEMORY.md✓✓*—Scrub promoted ghost entries~/.openclaw/agents/<agent>/sessions/✓—✓Archive then remove originals~/.openclaw/ghost-archive/✓✓✓Temporary staging, shredded after verify~/.openclaw/data/memory.db✓✓—Remove index entries for ghost sessions

\* Writes use atomic rename ( .tmp → target) — never partial or corrupted files.

All deletions are user-triggered. The skill only acts when you explicitly run ghost off or force-cleanup-all. No hooks, no daemons, no passive collection.

What This Skill Does NOT Touch#

• Files you create — code, documents, images, configs, anything you explicitly write to disk during a ghost session stays exactly where you put it
• Local outputs — command output, build artifacts, downloaded files, anything the agent creates as a file output (not a memory entry) is untouched
• OpenClaw gateway logs — outside agent workspace scope
• OS-level process traces — outside agent workspace scope
• Third-party service logs — outside agent workspace scope
• Files outside the OpenClaw workspace — never read or modified
• Network requests — none. Entirely local, no API calls, no cloud services

The analogy: Browser incognito mode doesn't delete your downloads. Ghost Mode doesn't delete your files. It only clears the agent's memory of what happened — just like closing a private browsing window clears history but leaves your saved files alone.

File Layout#

text

scripts/
├── ghost_mode.sh           # Main CLI entry point (dry-run, confirm, config)
├── ghost_registry.py       # Session registry + state machine
├── ghost_archive.py        # Session file archival
├── ghost_scrub.py          # Memory file scrubbing
├── ghost_verify.py          # 7-layer verification
└── ghost_index_cleanup.py  # OpenClaw memory index cleanup

references/
└── ARCHITECTURE.md         # Full state machine docs, edge cases, internals

State Machine#

text

active → completed → archived → scrubbed → verified → (shredded)

Each transition is recorded in the registry with a timestamp. Re-running any stage is safe.

Post-Install Warning#

The first time the agent detects this skill after installation, it MUST deliver this warning to the user:

⚠️ Ghost Mode is installed. This skill permanently deletes data — logs, memory files, session transcripts, and search index entries — using secure deletion ( shred -u). This is irreversible. Bugs, misuse, or environment conflicts can cause unrecoverable data loss beyond what you intended. By keeping this skill installed, you accept these risks. Strongly recommended: set up daily backups of ~/.openclaw/workspace/ and ~/.openclaw/data/. Run ghost_mode.sh status to check the current state at any time.

This warning must be shown once after installation. To prevent repeated warnings, after delivering it, create the file memory/.ghost-mode-warning-shown in the workspace. On subsequent sessions, check for this file — if it exists, skip the warning.

On first install, the agent MUST also create ghost-mode-config.json in the workspace root with confirmation enforced:

json

{
  "confirm_before_delete": true,
  "dry_run_by_default": true
}

This ensures every new install starts with confirmation enabled. The user may change these settings later, but confirmation must never be silently disabled.

AGENTS.md Integration#

After installing, add this to your AGENTS.md so the agent respects ghost mode:

markdown

## Ghost Mode

⚠️ This skill permanently deletes data by design. See the post-install warning for details.

- **"ghost on"** → run `ghost_mode.sh on` immediately
- **"ghost off"** → run `ghost_mode.sh off` immediately (requires confirmation unless `--yes`)
- **"ghost status"** → run `ghost_mode.sh status` and report back

When ghost mode is active (`.ghost-mode` flag exists):
- **ZERO memory writes** — no daily logs, semantic files, episodic files, MEMORY.md, AGENTS.md, USER.md, or SOUL.md updates
- Reading files is still allowed
- Do NOT mention ghost mode in channel messages unless the user asks

### Stale Flag Cleanup
If the `.ghost-mode` flag's `activatedAt` is older than 24 hours:
```bash
ghost_mode.sh force-cleanup-all

Remove the flag and proceed normally. Log cleanup to stderr only.

text

## Cron Integration (Optional)

The skill works without cron — `ghost off` runs the full pipeline synchronously. If you want automated cleanup of stale sessions:

```bash
# Archive completed ghost sessions every 15 min (optional)
*/15 * * * * ~/.openclaw/workspace/skills/ghost-mode/scripts/ghost_mode.sh archive-completed

# Verify scrubbed sessions hourly (optional)
0 * * * * ~/.openclaw/workspace/skills/ghost-mode/scripts/ghost_mode.sh verify-pending

# Force cleanup stale sessions daily at 3 AM (optional)
0 3 * * * ~/.openclaw/workspace/skills/ghost-mode/scripts/ghost_mode.sh force-cleanup-all

These are optional — the primary workflow is manual ghost on / ghost off.

Requirements#

• Python 3.8+ — for registry, scrub, verify, and index cleanup scripts
• shred — standard on Linux. macOS: brew install coreutils then use gshred
• OpenClaw workspace — defaults to ~/.openclaw/workspace/, configurable via OPENCLAW_WORKSPACE env var
• No external dependencies — no pip packages, no API keys, no cloud services, no network calls

Environment Variables#

VariableDefaultPurposeOPENCLAW_WORKSPACE``~/.openclaw/workspacePath to the OpenClaw workspace directory. All memory and registry files are stored here.OPENCLAW_HOME``~/.openclawPath to the OpenClaw home directory. Session files and archive are stored under agents/ and ghost-archive/ here.OPENCLAW_AGENT``mainAgent directory name under OPENCLAW_HOME/agents/. Used to locate session JSONL and checkpoint files.

Security Model#

Intentionally destructive. Ghost mode exists to remove data. This is the core purpose, not a side effect. Multiple safety interlocks prevent accidental deletion.

PropertyDetailDeletion methodshred -u (secure overwrite, then remove). Falls back to rm with warning if shred unavailableRegistry audit trailEvery state transition is timestamped. You can inspect memory/.ghost-sessions.json at any time7-layer verificationConfirms: flag removed, registry correct, session files gone, checkpoints gone, daily logs free of session references, semantic files free of session references, index cleanAtomic writesAll file modifications use write-to- .tmp then rename — no partial/corrupted stateConfirmation promptghost off and force-cleanup-all require interactive yes confirmation by default. Disable with config or --yes flagDry-run mode--dry-run shows what would be deleted without making any changes. Configurable as default via dry_run_by_defaultUser-triggered onlyNo automatic hooks. No passive collection. No daemons. Acts only when you run ghost on, ghost off, or force-cleanup-allPath validationAll file operations validate paths are within OPENCLAW_WORKSPACE or OPENCLAW_HOME. Session IDs are checked for path traversal. Operations outside these boundaries are rejectedEnv var safety checkAt startup, the scripts verify that OPENCLAW_WORKSPACE and OPENCLAW_HOME resolve to paths within the user's home directory. If either is misconfigured to point at a broader location (e.g. /, /tmp), the scripts abort with an error before performing any operationsLocal onlyNo network calls. No API keys. No cloud services. Everything runs on your machine

What's out of scope: Gateway logs, OS process traces, third-party service logs. Ghost mode cleans what the agent controls — your workspace.

Limitations#

• Ghost mode is cooperative, not enforced at the OS level. Write suppression is implemented in the agent runtime — the agent checks for the .ghost-mode flag at session start and during the session, and skips memory writes when it is present. The scripts in this skill handle activation (writing the flag) and cleanup (scrubbing traces after deactivation); the runtime enforcement lives in your agent's AGENTS.md integration, not in these scripts. Other processes, scripts, or non-compliant agents that bypass the flag will still write to the workspace. The flag is a coordination mechanism — it works when the agent reads and respects it.

• The OpenClaw gateway logs requests independently. Ghost mode cannot remove gateway logs.

• If the agent crashes before ghost off, the flag persists. The next session will detect it. Run force-cleanup-all to clean up sessions stale for >24 hours.

• Scrubbing uses timestamp and filename heuristics. The scrubber matches ghost-window entries by mtime and embedded timestamps. If your workspace layout or timestamp formats differ from standard OpenClaw conventions, the scrubber may miss some entries or — in edge cases — remove content from non-ghost sessions that falls within the same time window. Always run --dry-run first to preview what will be affected.

Disclaimer#

This skill is provided as-is, with no warranties, express or implied. There is no assurance of fitness for any particular purpose, no guarantee of data safety, and no support commitment.

By installing or using this skill, you accept full responsibility for any outcomes. You use this skill entirely at your own risk. The Author is not liable in any way for any losses, damages, or consequences — direct, indirect, incidental, or otherwise — that result from using this skill. This includes, but is not limited to, data loss, corrupted files, lost sessions, or any other damage arising from the use or inability to use this skill.

You are running a tool whose stated purpose is to permanently delete data. Use it carefully. Back up your workspace.

Source & Issues#

• Repo: https://github.com/stelloxx/ghost-mode
• Install: clawhub install ghost-mode
• Report issues: https://github.com/stelloxx/ghost-mode/issues

License#

MIT-0