Skill: inxan3/delphi (version 1.0.0)

--- name: self-awareness description: > Always-on self-awareness framework for OpenClaw agents. Imprints accurate knowledge of how the agent works — platform mechanics, memory layers, storage conventions, context health, and common failure modes. Use when: answering meta questions about how the agent functions, diagnosing unexpected behavior, running /selfcheck, or as a permanent enrichment layer that keeps the agent honest about its own architecture. Prevents platform drift, lateral-move debugging, and confident-but-wrong answers about the runtime. --- # Self-Awareness This skill is a framework — not a trigger-based tool. Load it once and let it shape how you operate. ## What This Skill Does 1. **Imprints** accurate knowledge of the OpenClaw runtime so you stop guessing 2. **Enforces** a failure-handling protocol that prevents lateral-move debugging 3. **Defines** drift patterns you're prone to and how to catch them early 4. **Establishes** a self-check habit — periodic or on-demand Read the references as needed. The rules below are always active. --- ## Core Operating Rules (Always Active) ### Rule 1: Know Before You Assume Before answering any question about how the platform works, your config, your tools, or your storage — **verify, don't guess**. - Unsure where a file lives? Check with `read` or `exec ls`. - Unsure what model is active? Run `session_status`. - Unsure what a config option does? Read [REDACTED_SECRET] or `https://docs.openclaw.ai`. - "I think" and "usually" are red flags. Replace them with a tool call. ### Rule 2: First Fail → Stop and Reason When something doesn't work: 1. **Stop** — do not immediately try a variation of the same approach 2. **Diagnose** — read the error carefully, check what it actually says 3. **Identify root cause** — not the symptom ("exec failed"), the cause ("exec preflight blocks `&&` chains") 4. **Fix the cause** — not a lateral variation of the broken approach > Lateral-move debugging: trying `fix_A`, it fails, trying `fix_A2` (same class, slightly different), it fails, trying `fix_A3`... This loop is almost always wrong. If A didn't work, understand *why* before moving to B. See `references/failure-protocol.md` for the full protocol. ### Rule 3: Context Window Is a Shared Resource You are always consuming context. Act accordingly: - At **45%+**: note it internally, mention it once if the session is getting complex - At **70%+**: proactively suggest `/new` if work is ongoing - At **85%+**: strongly recommend `/new` before continuing - Check with `session_status` when in doubt — it's the authoritative source Large tool outputs, long file reads, and repeated memory searches compound fast. ### Rule 4: Memory Has Layers — Use the Right One | Layer | File | When it's loaded | |---|---|---| | Long-term | `MEMORY.md` | Every main session (auto-injected) | | Daily notes | `memory/YYYY-MM-DD.md` | Today + yesterday only | | On-demand | Any `memory/*.md` | When you explicitly read it | - Don't assume memory from 3 days ago is in context. It isn't. - Don't write "I'll remember this" — write it to a file. - `MEMORY.md` = curated wisdom. Daily files = raw notes. Keep them distinct. ### Rule 5: Workspace ≠ Sandbox The workspace is the default working directory for file tools — not a hard boundary. Absolute paths reach the host unless sandboxing is explicitly configured. Don't assume files outside the workspace are inaccessible, and don't assume relative paths work from arbitrary locations. ### Rule 6: Skills Are Snapshots Skills are snapshotted when a session starts. Changes to skill files take effect on the **next session**, not the current one. Don't expect edits to SKILL.md files to change behavior mid-session. --- ## First-Load Setup When this skill first loads in a new deployment, do the following **once**: ### 1. Learn the Storage Layout Read the workspace to understand what's where: ``` exec: ls <workspace>/ exec: ls <workspace>/memory/ (if exists) exec: ls <workspace>/skills/ (if exists) ``` Then read `references/storage-conventions.md` to understand how to reason about paths generically. ### 2. Set Up the Weekly Recheck Cron Create a weekly isolated cron job that runs `/selfcheck`: ```json { "schedule": { "kind": "cron", "expr": "0 9 * * 1" }, "payload": { "kind": "agentTurn", "message": "Run /selfcheck per self-awareness skill instructions." }, "sessionTarget": "isolated", "delivery": { "mode": "announce" } } ``` Use the `cron` tool to create this. Adjust time to user's timezone if known. ### 3. Initialize Drift Log Create `memory/drift-log.md` if it doesn't exist: ```markdown # Drift Log Append-only log of detected behavioral drift. Format: [date] | [drift type] | [what was caught] | [correction applied] ``` --- ## /selfcheck Protocol When triggered by `/selfcheck` or the weekly cron, run through this checklist and report results: ### A. Context Health - Run `session_status` — note context % used - Flag if above 45% ### B. Memory Freshness - Check when `MEMORY.md` was last meaningfully updated (look for recent dates in content) - Check if today's daily file exists: `memory/YYYY-MM-DD.md` - Flag if MEMORY.md hasn't been updated in >7 days ### C. Storage Sanity - Verify workspace path is known and accessible - Check that key paths referenced in MEMORY.md actually exist - Flag any broken references ### D. Drift Check - Run through the drift catalog mentally: am I currently doing any of these wrong? - Read `references/drift-catalog.md` for the full list ### E. Active Crons - Note how many cron jobs are active (use `cron` tool: `action=list`) - Flag any that haven't fired recently or seem misconfigured ### Report Format ``` 🔍 Self-Check — [date] Context: [X%] [OK / ⚠️ elevated / 🔴 critical] Memory: [fresh / stale — last updated X days ago] Storage: [OK / issues found] Drift: [none detected / N items flagged] Crons: [N active / issues found] [Brief notes on anything flagged] ``` If anything is flagged, offer to go deeper (C option). Always log the check to `memory/drift-log.md`. --- ## References Load these when you need depth — don't preload all of them: - **`references/platform-truths.md`** — universal OpenClaw facts agents consistently get wrong. Read when unsure about platform behavior. - **`references/storage-conventions.md`** — how to reason about workspace and volume layout. Read on first load or when storage decisions come up. - **`references/failure-protocol.md`** — the full stop-reason-fix protocol. Read when debugging something that isn't working. - **`references/drift-catalog.md`** — known drift patterns with detection signals and corrections. Read during /selfcheck or when behavior feels off.

path: references/drift-catalog.md
content: # Drift Catalog

Known patterns of behavioral drift — things agents confidently do wrong over time. Each entry has: what it looks like, how to detect it, and how to correct it.

Use this file during `/selfcheck` or when behavior feels off.

---

## Category 1: Platform Misassumptions

Drift where the agent states or acts on incorrect beliefs about how OpenClaw works.

### 1.1 Heartbeat = Background Task
**What it looks like:** Treating heartbeat runs as if they create `/tasks` records, or expecting them to show up in task history.
**Detection:** You say "the heartbeat ran a background task" or check `/tasks` expecting heartbeat results.
**Correction:** Heartbeat = periodic main-session turns only. No task record. Use isolated cron agentTurn for detached background work with task records.

### 1.2 Skill Changes Are Live
**What it looks like:** Editing a SKILL.md mid-session and expecting new behavior immediately.
**Detection:** You make a skill edit, then refer to the "updated" skill in the same session.
**Correction:** Skills are snapshotted at session start. `/new` to pick up changes.

### 1.3 Per-Agent Skills Merge
**What it looks like:** Adding one skill to `agents.list[].skills` expecting it to add to the defaults.
**Detection:** Agent is missing skills it used to have after a config change to the skills list.
**Correction:** `agents.list[].skills` **replaces** the full skill list. Always include all desired skills.

### 1.4 Workspace Is a Sandbox
**What it looks like:** Assuming files outside the workspace are inaccessible or protected.
**Detection:** Avoiding absolute paths unnecessarily, or assuming a relative path is "safe" because it's in the workspace.
**Correction:** Workspace = default cwd. Not a security boundary. Absolute paths work unless sandbox mode is explicitly configured.

### 1.5 BOOT.md Gets a Normal Reply
**What it looks like:** Responding conversationally to a BOOT.md message.
**Detection:** Gateway startup triggers a message from BOOT.md and you write a full response.
**Correction:** Reply must be exactly `NO_REPLY` — the entire response, nothing else. Any other content gets routed as a real reply.

---

## Category 2: Memory & Context Drift

Drift where the agent loses track of what it knows, what's in context, or how full the window is.

### 2.1 Assuming Old Memory Is Loaded
**What it looks like:** Referencing something from 3+ days ago as if it's in context.
**Detection:** You mention something specific from a past session without having searched for it.
**Correction:** Only today + yesterday's daily files auto-load. Search with `memory_search` or explicitly `read` older files.

### 2.2 Mental Notes
**What it looks like:** "I'll keep that in mind" or "I'll remember that" without writing to a file.
**Detection:** You say you'll remember something without calling `write` or `edit`.
**Correction:** Nothing survives a session end unless written to disk. Write it now.

### 2.3 Context Window Blindness
**What it looks like:** Operating normally deep into a long session without monitoring context usage.
**Detection:** You haven't checked `session_status` in a while during a complex multi-tool session.
**Correction:** Run `session_status` during long sessions. The context % is not visible unless you check it. At 70%+, warn the user.

### 2.4 MEMORY.md Staleness
**What it looks like:** Trusting MEMORY.md entries without checking how current they are.
**Detection:** Acting on MEMORY.md content that references dates many weeks old as if it's current.
**Correction:** MEMORY.md is manually curated. Check the dates of entries. Stale entries can be misleading. Flag if >7 days since last meaningful update.

---

## Category 3: Storage Drift

Drift where the agent loses coherent understanding of where things are stored.

### 3.1 Path Guessing
**What it looks like:** Using a path that seems right without verifying it exists.
**Detection:** You construct a path like `<workspace>/memory/topic.md` without having confirmed the file is there.
**Correction:** `read` or `exec ls` to verify before operating. Silent "file not found" downstream is worse than a quick check upfront.

### 3.2 Relative Path Confusion
**What it looks like:** Using `./file.md` in exec commands without confirming cwd.
**Detection:** exec fails with "no such file" on a relative path.
**Correction:** In exec, use absolute paths or explicitly `cd` first. Relative paths in exec depend on cwd, which may not be the workspace.

### 3.3 Temp File Accumulation
**What it looks like:** Creating working files during a task and not cleaning them up.
**Detection:** Finding files like `output_draft.md`, `temp_results.json`, etc. with no clear purpose during a storage scan.
**Correction:** Clean up after completing a task. If a file is genuinely useful, put it in the right place with a proper name.

### 3.4 Duplicate Knowledge
**What it looks like:** The same information exists in MEMORY.md, a daily file, and a topic file — out of sync.
**Detection:** Searching for something and finding multiple conflicting versions.
**Correction:** One canonical location per piece of knowledge. MEMORY.md for distilled facts, daily files for raw notes, topic files for deep references. Pick one and remove the others.

---

## Category 4: Behavioral Drift

Drift in how the agent approaches tasks — process quality, not knowledge accuracy.

### 4.1 Lateral-Move Debugging
**What it looks like:** Trying A, it fails, trying A', it fails, trying A''.
**Detection:** You've attempted the same general approach 3+ times with minor variations.
**Correction:** Stop. Read `references/failure-protocol.md`. Diagnose root cause before trying again.

### 4.2 Confident Uncertainty
**What it looks like:** Using "I think", "usually", "probably" when the answer is verifiable.
**Detection:** You hedge on something that a tool call could answer definitively.
**Correction:** Run the tool call. Replace guesses with facts. "I think the context is around 50%" → `session_status`.

### 4.3 Output Without Verification
**What it looks like:** Writing a file, running a command, then declaring it done without checking.
**Detection:** You say "done" after a write/exec without reading back the result.
**Correction:** Always verify. `read` after `write`. Check exec output carefully. Silent exit 0 ≠ success.

### 4.4 Scope Creep on Fixes
**What it looks like:** Fixing one thing and inadvertently changing other things in the same file/config.
**Detection:** The user reports unexpected behavior after a targeted fix.
**Correction:** When making targeted edits, use `edit` (not full `write` rewrites) to minimize blast radius. Read before editing to understand what's already there.

---

## Self-Check Usage

During `/selfcheck`, go through each category and honestly ask: *am I currently doing any of these?*

Not "could I theoretically do this" — but "is there evidence in this session or recent behavior that this drift is active?"

If yes: flag it (one line to user), log it to `memory/drift-log.md`, offer to discuss.

Format for drift-log entries:
```
[YYYY-MM-DD] | [category] | [drift ID e.g. 2.3] | [what was observed] | [correction applied]
```

Example:
```
2026-04-24 | Context Drift | 2.3 | Session at 72% before checking status | Warned user, recommended /new
```


path: references/failure-protocol.md
content: # Failure Protocol

How to handle things that don't work. The goal is root cause, not lateral movement.

---

## The Core Rule

> When something fails, your first instinct will be to try a slightly different version of the same thing. **Don't.**

That instinct — lateral-move debugging — is the single most common failure mode for AI agents. It feels like progress (you're doing something!) but it's usually just burning tokens on variations of a broken approach.

The protocol below replaces that instinct with a structured process.

---

## The Protocol

### Step 1: STOP

Do not immediately retry. Do not try a variation. Stop.

Read the error output in full. Not a skim — actually read it.

Ask: *"What is this error actually telling me?"*

### Step 2: SEPARATE symptom from cause

| Symptom (don't fix this) | Cause (fix this) |
|---|---|
| "exec failed" | exec preflight blocks `&&` chains |
| "file not found" | wrong path assumption, or cwd is not what you think |
| "tool returned empty" | tool call was correct but the resource doesn't exist |
| "permission denied" | elevated exec needed, or wrong file ownership |
| "API error 429" | rate limit — wait, don't retry immediately |
| "context too long" | context window full — compact or start new session |
| "skill not found" | skill not installed, or session started before install |

### Step 3: IDENTIFY the actual cause

Before touching anything, answer these:
- What exactly failed? (which tool, which line, which operation)
- What did I assume that turned out to be wrong?
- Is this a one-time error or a systematic misunderstanding?

If you can't answer these, you're not ready to fix it yet. Use more diagnostic tools:
```
read the error output again
exec: echo $PWD   (confirm cwd)
read: <the file you thought existed>
session_status    (confirm model, context %)
```

### Step 4: FIX the cause, not the symptom

Only now attempt a fix — and it should address the root cause you identified, not a variation of the failed approach.

Examples:
- ❌ Lateral move: exec failed with `&&`, so try exec with `;` instead
- ✅ Root fix: exec failed with `&&` because exec preflight blocks chained operators — split into separate exec calls

- ❌ Lateral move: file not found at `./memory/file.md`, try `../memory/file.md`
- ✅ Root fix: confirmed cwd is not workspace root — use absolute path instead

### Step 5: VERIFY before declaring success

Don't assume a fix worked. Verify it:
- Read the output carefully
- Check the file actually exists/has the right content
- Run the operation a second time if there's any doubt
- Silent exit 0 with no output is **not** confirmation

### Step 6: LOG if it was non-obvious

If the root cause was something genuinely surprising or worth remembering, append to `memory/drift-log.md`:
```
[date] | failure | [what failed] | [root cause found] | [fix applied]
```

---

## Escalation Rules

If you've applied the protocol and still can't fix it after **2 genuine attempts** (not lateral moves — real different approaches based on different diagnoses):

1. **Stop trying to fix it**
2. Tell the user: what you tried, what failed each time, what you think the root cause is
3. Ask for guidance or suggest what information would help you proceed

Never retry indefinitely. Never silently fail and pretend it worked.

---

## Common Trap Patterns

### The Variation Loop
```
Try A → fails
Try A' (same class, minor variation) → fails  
Try A'' (same class again) → fails
```
**Signal:** You're in this loop if you're trying the same general approach 3+ times.
**Break:** Go back to Step 2. Your diagnosis of the cause is probably wrong.

### The Assumption Stack
```
Assume X → build on X → assume Y → build on Y → it fails
```
**Signal:** You realize mid-fix that an earlier assumption was wrong.
**Break:** Don't try to patch around it. Go back to the earliest wrong assumption and fix from there.

### The Silent Move-On
```
Tool call fails → note it internally → continue as if it worked
```
**Signal:** You're about to use a result that may not exist.
**Break:** Always verify before building on a result. Especially file reads, API calls, exec output.

### The Optimistic Retry
```
API returns 429 → immediately retry → 429 again → retry → 429 again
```
**Signal:** Error is rate/capacity-based, not logic-based.
**Break:** Wait before retrying. For 429: respect Retry-After header or wait at minimum 10-30 seconds.

---

## When the Protocol Doesn't Apply

Some failures are expected and don't need the full protocol:
- **First-time setup**: trying a new tool or API for the first time — some trial is normal
- **Explicit exploration**: when the task is to find what works (e.g. testing multiple approaches by design)
- **Known transient errors**: 429 rate limits, network blips — retry with backoff is correct

The protocol applies when: something was expected to work, it didn't, and you're about to try again.


path: references/platform-truths.md
content: # Platform Truths

Universal OpenClaw facts that agents frequently get wrong. These are authoritative — verified against docs, not assumed.

---

## Session & Memory

| Topic | Wrong assumption | Truth |
|---|---|---|
| Daily memory auto-loads | All history loads automatically | Only **today + yesterday** auto-loaded. Older files require explicit `memory_get` or `memory_search`. |
| Mental notes persist | "I'll remember this" works | No. Session ends, it's gone. **Write to a file.** |
| MEMORY.md is always current | It's live/auto-updated | It's manually curated. It can go stale. Check dates in the content. |
| memory_search searches everything | Full history is indexed | Searches indexed memory files only. Non-indexed files need explicit `read`. |

## Skills

| Topic | Wrong assumption | Truth |
|---|---|---|
| Skill edits take effect now | Live reload mid-session | Skills are **snapshotted at session start**. Edits take effect next session (or with skills watcher hot-reload if enabled). |
| Per-agent skills list merges | `agents.list[].skills` adds to defaults | It **replaces** defaults entirely. Omit the field to inherit. |
| Skills run automatically | A skill = a tool the agent uses | Skills are **instructions** loaded on demand — the agent must `read` the SKILL.md and follow it. |
| All skills in context always | Skill content is always loaded | Only metadata (name + description + location) is in context. Body loads only when triggered. |

## Cron & Heartbeat

| Topic | Wrong assumption | Truth |
|---|---|---|
| Heartbeat creates task records | Heartbeat runs appear in `/tasks` | **No.** Heartbeat = main-session turns only. No background task record. |
| Isolated cron = heartbeat | They're the same mechanism | Isolated agentTurn cron = **has a task record**, separate session. Heartbeat = no record, main session. |
| Cron jobs survive without gateway | Jobs run independently | Cron runs **inside the gateway process**. Gateway down = cron stopped. |
| `--at` without timezone = local time | Uses host timezone | **Treated as UTC.** Always specify `--tz` for local wall-clock scheduling. |

## Context & System Prompt

| Topic | Wrong assumption | Truth |
|---|---|---|
| System prompt is user-controlled | You can override the full prompt | System prompt is **OpenClaw-owned**. Bootstrap files are injected under Project Context, not as the full prompt. |
| Bootstrap files are unlimited | Files load in full | Each file capped at `bootstrapMaxChars` (default: 12k chars). Total cap: `bootstrapTotalMaxChars` (default: 60k). Large files are **silently truncated**. |
| `/context` shows the full prompt | It dumps everything | `/context list` shows sizes and contributors — not the full prompt or tool schemas. |
| Tool schemas don't cost tokens | Only visible text counts | Tool schemas (JSON) are sent to the model and **count toward context** even though you don't see them as text. |

## Workspace & Storage

| Topic | Wrong assumption | Truth |
|---|---|---|
| Workspace is a sandbox | Files outside workspace are blocked | Workspace is the **default cwd**, not a security boundary. Absolute paths reach the host unless sandboxing is explicitly configured. |
| Relative paths work anywhere | `./file` works from any tool | Relative paths resolve from the **workspace root**. Outside the workspace, use absolute paths. |
| Files auto-organize themselves | Storage stays clean | Without conventions, files accumulate in random locations. Establish storage rules and follow them. |

## Hooks & Config

| Topic | Wrong assumption | Truth |
|---|---|---|
| Workspace hooks override bundled | You can replace built-in hooks | Workspace hooks can **add new hook names only** — cannot override bundled, managed, or plugin hooks. |
| BOOT.md needs a reply | Respond normally to boot messages | When boot hook sends a message, reply with **`NO_REPLY`** exactly — nothing else. That exact token suppresses routing. |
| BOOTSTRAP.md persists | It's a permanent reference file | **Delete after first-run setup is complete.** It's a one-time ritual file. |
| Config changes are live | Edits take effect immediately | Some changes require gateway restart. Skills require new session. |

## Behavioral

| Topic | Wrong assumption | Truth |
|---|---|---|
| `NO_REPLY` can be appended | "Here's help... NO_REPLY" | `NO_REPLY` must be the **entire response** — never append to a real reply. |
| `session_status` is optional | Time/model info is always known | `session_status` is the **only reliable way** to get current time, context %, and active model. |
| Sub-agents share parent context | Sub-agents inherit full context | Sub-agents only get `AGENTS.md` and `TOOLS.md` from bootstrap. Other files are filtered out. |
| Per-agent `skills` merges | Adding one skill keeps all others | It **replaces** the entire list. To add one skill, list all others explicitly too. |


path: references/storage-conventions.md
content: # Storage Conventions

How to reason about workspace layout, file placement, and path decisions — generically, for any OpenClaw deployment.

---

## The Mental Model

Think of storage in three zones:

```
ZONE 1: Workspace (agent's home)
  └── Where you read and write files by default
  └── Auto-injected bootstrap files live here
  └── Path: configured in `agents.defaults.workspace` (default: ~/.openclaw/workspace)

ZONE 2: State dir (platform's home)
  └── Where OpenClaw stores its own operational data
  └── Session transcripts, cron jobs, skill installs, logs
  └── Path: ~/.openclaw/ (or OPENCLAW_STATE_DIR)

ZONE 3: Host filesystem (everything else)
  └── Accessible via absolute paths unless sandboxed
  └── Where persistent volumes live on cloud deployments
  └── Treat with care — changes here survive redeployments
```

---

## Workspace Layout (Recommended)

A well-organized workspace follows this convention:

```
<workspace>/
├── AGENTS.md           ← primary operating instructions
├── SOUL.md             ← personality/tone
├── IDENTITY.md         ← agent identity
├── USER.md             ← user profile
├── TOOLS.md            ← environment-specific notes
├── HEARTBEAT.md        ← periodic task checklist
├── MEMORY.md           ← long-term curated memory (main session only)
├── PLATFORM.md         ← optional: platform reference (if created)
│
├── memory/             ← all memory files
│   ├── YYYY-MM-DD.md   ← daily notes (auto-loaded: today + yesterday)
│   ├── drift-log.md    ← self-awareness drift log
│   ├── lessons.md      ← append-only lessons learned
│   └── *.md            ← topic files, loaded on demand
│
├── skills/             ← workspace-level skills (highest precedence)
│   └── <skill-name>/
│       ├── SKILL.md
│       └── references/
│
├── scripts/            ← utility scripts
├── agents/             ← per-agent bootstrap files (if multi-agent)
└── <project-dirs>/     ← project-specific working directories
```

---

## Storage Decision Rules

### Where does a new file go?

| File type | Location |
|---|---|
| Long-term knowledge the agent should always have | `MEMORY.md` (as a distilled entry) |
| Raw session notes, logs, daily events | `memory/YYYY-MM-DD.md` |
| Lessons learned (append-only) | `memory/lessons.md` |
| Topic-specific knowledge (loaded on demand) | `memory/<topic>.md` |
| Self-check drift events | `memory/drift-log.md` |
| Scripts | `scripts/<name>.<ext>` |
| Skill instructions | `skills/<skill-name>/SKILL.md` |
| Skill reference material | `skills/<skill-name>/references/<file>.md` |
| Persistent data that survives redeployments | A persistent volume path (e.g. `/data/` on Railway) |
| Temporary working files | `<workspace>/tmp/` or in-memory — clean up after use |

### What NOT to put in MEMORY.md

- Raw logs or transcripts — those go in daily files
- Temporary state — will be stale immediately
- Very large reference documents — create a topic file instead
- Secrets or API keys — those go in a secure location (`memory/keys.env` or env config), never in MEMORY.md

### What NOT to put in daily files

- Curated knowledge — distill important stuff into MEMORY.md
- Lessons that should persist — those go in `memory/lessons.md`

---

## Path Conventions

### Always verify before using a path

Don't assume a path exists. Check with `read` or `exec ls` before operating on it.

```
# Check workspace
read: <workspace>/

# Check a specific file
read: <workspace>/memory/YYYY-MM-DD.md

# List a directory
exec: ls <workspace>/memory/
```

### Absolute vs relative paths

- **Within workspace tools**: relative paths resolve from workspace root — safe to use
- **In exec commands**: use absolute paths unless you've confirmed cwd
- **In cron/subagent contexts**: always use absolute paths — they run in fresh sessions with potentially different cwd

### Persistent vs ephemeral storage

| Storage type | Survives restart? | Survives redeploy? |
|---|---|---|
| Workspace files | ✅ (if on persistent volume) | Depends on deployment |
| State dir (`~/.openclaw/`) | ✅ | ❌ usually (unless volume-mounted) |
| In-memory / session state | ❌ | ❌ |
| Persistent volume (e.g. `/data/`) | ✅ | ✅ |

**Key question to ask on any deployment:** Is the workspace on a persistent volume? If not, files written there will be lost on redeploy.

---

## First-Load Storage Discovery

On first load in a new deployment, do this to understand what you're working with:

```
1. Run session_status → note the workspace path
2. exec: ls <workspace>/
3. exec: ls <workspace>/memory/ (if it exists)
4. Read MEMORY.md to understand what's been established
5. Check if drift-log.md exists — create it if not
```

This gives you a complete picture in under a minute.

---

## Storage Hygiene Rules

1. **Name files clearly** — a file named `notes.md` from 6 months ago is useless. Use dated names or descriptive names: `memory/integrations.md`, `memory/2026-04-24.md`.
2. **Clean up tmp files** — if you create a working file, delete it when done.
3. **Don't duplicate** — if something belongs in MEMORY.md, don't also put it in a daily file. Pick one.
4. **Append-only for logs** — `drift-log.md`, `lessons.md` — never edit past entries, only append.
5. **Reference over copy** — if a topic needs detail, create `memory/<topic>.md` and add a pointer in MEMORY.md rather than bloating MEMORY.md itself.


Security scan verdicts — ClawScan: suspicious | static analysis: clean | VirusTotal: clean | SkillSpector: suspicious (HIGH)