Ghost Mode

Enables incognito mode to suppress and securely erase all agent memory writes and session traces upon deactivation, leaving no persistent record.

Security Scan

The skill's code, actions, and required accesses match its stated purpose (securely archive and permanently scrub agent memory), but it is a destructive tool and a few implementation/assurance caveats should be understood before use.

Purpose & Capability

The skill claims to 'suppress memory writes' and then securely erase session traces; the included scripts operate on the OpenClaw workspace, session JSONL/checkpoint files, daily/semantic/episodic memory files, the SQLite memory index, and use secure-delete (shred) — all consistent with the stated purpose. However, there is no code in the package that hooks into or patches the agent's runtime to forcibly block every write; suppression is implemented by writing a flag and registry entry that the broader agent platform would need to consult. If the agent implementation does not honor the flag, in-session writes may still occur and must be scrubbed later. This functional dependency is a design caveat rather than an incoherence.

Instruction Scope

Runtime instructions and scripts perform thorough, irreversible operations: archiving session files, editing/scrubbing memory files, deleting index rows from memory.db, and shredding archived files. These actions are narrowly scoped to the OpenClaw workspace and agent session paths and the code enforces path validation (ensuring workspace/home are subdirectories of the user's home). That scope is appropriate for the feature, but the behavior is destructive by design and relies on correct environment variable configuration (OPENCLAW_WORKSPACE / OPENCLAW_HOME) and the agent honoring the ghost flag for write suppression.

Install Mechanism

There is no external network download or package install; all scripts are bundled. The install behavior is file-based (shell + Python scripts) which is low-to-moderate risk compared with fetching code from arbitrary URLs. No brew/npm/third-party installers are pulled in. Optional use of system 'shred' is expected for secure deletion.

Credentials

The skill does not request external credentials or broad environment variables. It uses OPENCLAW_WORKSPACE, OPENCLAW_HOME, and OPENCLAW_AGENT (all optional with sensible defaults), and explicitly enforces that these paths are subdirectories of the user's home. The scripts access only OpenClaw workspace files and the SQLite index — proportional to the stated destructive purpose.

Persistence & Privilege

The skill does not request always:true or any elevated persistent privilege. It writes and removes files within its own workspace area and maintains a registry and flag file in the workspace. It does not modify other skills' configurations or system-wide settings beyond the OpenClaw workspace it is designed to manage.

Assessment

This skill is a purposeful, destructive tool: it permanently deletes session transcripts, edits memory files, and removes index entries. Before installing or running it: 1) Backup your OpenClaw workspace and memory.db (the SKILL.md itself recommends this). 2) Verify OPENCLAW_WORKSPACE and OPENCLAW_HOME are correctly set to subdirectories (not $HOME) — the scripts will refuse to run if they detect unsafe settings. 3) Test with the default dry-run mode and the provided verification commands to confirm behavior in your environment. 4) Understand that 'suppressing memory writes' depends on the agent respecting the .ghost-mode flag — the skill does not and cannot retroactively prevent writes by other processes. 5) Keep the default interactive confirmation enabled unless you intentionally want irreversible deletes without prompts. If you have low tolerance for data loss or lack backups, do not enable the deletion steps (use dry-run only).

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

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

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

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

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:

# 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

# 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.

$ ./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:

$ ./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):

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

Setting	Default	Description
confirm_before_delete	true	Require typing yes before any destructive operation. Set false to disable prompts.
dry_run_by_default	true	If 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

Path	Read	Write	Delete	When
memory/.ghost-mode	✓	✓	✓	Flag lifecycle
memory/.ghost-sessions.json	✓	✓	—	Registry state machine
memory/YYYY-MM-DD.md	✓	✓*	—	Scrub ghost-window entries
memory/semantic/*.md	✓	✓*	—	Scrub ghost-window entries
memory/episodic/*.md	✓	✓*	—	Scrub ghost-window entries
MEMORY.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

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

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:

{
  "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:

## 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.

## 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

Variable	Default	Purpose
OPENCLAW_WORKSPACE	~/.openclaw/workspace	Path to the OpenClaw workspace directory. All memory and registry files are stored here.
OPENCLAW_HOME	~/.openclaw	Path to the OpenClaw home directory. Session files and archive are stored under agents/ and ghost-archive/ here.
OPENCLAW_AGENT	main	Agent 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.

Property	Detail
Deletion method	shred -u (secure overwrite, then remove). Falls back to rm with warning if shred unavailable
Registry audit trail	Every state transition is timestamped. You can inspect memory/.ghost-sessions.json at any time
7-layer verification	Confirms: flag removed, registry correct, session files gone, checkpoints gone, daily logs free of session references, semantic files free of session references, index clean
Atomic writes	All file modifications use write-to-.tmp then rename — no partial/corrupted state
Confirmation prompt	ghost off and force-cleanup-all require interactive yes confirmation by default. Disable with config or --yes flag
Dry-run mode	--dry-run shows what would be deleted without making any changes. Configurable as default via dry_run_by_default
User-triggered only	No automatic hooks. No passive collection. No daemons. Acts only when you run ghost on, ghost off, or force-cleanup-all
Path validation	All file operations validate paths are within OPENCLAW_WORKSPACE or OPENCLAW_HOME. Session IDs are checked for path traversal. Operations outside these boundaries are rejected
Env var safety check	At 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 operations
Local only	No 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