BOOTSTRAP.md Overwrites Agent Identity on Session Restart

Primary Symptom: Full Identity Amnesia on Session Restart

On every new session (/new or /reset), the agent greets the user as a completely fresh, unnamed entity despite having operated for days or weeks under a fully configured identity.

Trigger sequence observed in session logs:

{"type":"message","role":"user","content":"A new session was started via /new or /reset. Execute your Session Startup sequence now..."}
...
{"type":"assistant","content":"I see this is a fresh workspace with a `BOOTSTRAP.md` — time to come alive."}

The agent reads the following files in order and derives incorrect conclusions:

• SOUL.md — fully populated with real content
• IDENTITY.md — still contains the default blank scaffold template
• BOOTSTRAP.md — never deleted, contains first-run onboarding logic
• MEMORY.md — possibly empty or a default placeholder

Expected greeting (when identity is correctly loaded):

Hey! Good to be back. What's on the agenda today?

Actual greeting (under the bootstrap failure condition):

I see this is a fresh workspace with a BOOTSTRAP.md — time to come alive.
...
(no identity picked yet, no long-term memory built)

Affected session types:

• Interactive terminal sessions started with /new
• Session resets via /reset
• Automated cron/heartbeat sessions running as the agent

No data loss occurs — all workspace files remain intact. The agent simply ignores them and follows the BOOTSTRAP.md onboarding flow instead of normal session startup.

Two Compounding Conditions Create a Failure Window

The identity amnesia is not caused by a single bug but by a specific combination of two conditions that must both be true simultaneously.

Condition 1 — BOOTSTRAP.md Persists Beyond First Session

File path: <workspace>/BOOTSTRAP.md

During a first successful session startup, the agent is instructed to delete this file after completing onboarding. The standard instruction reads:

## Delete this file when you're done.
Delete BOOTSTRAP.md so it never runs again.

If the agent never executes this deletion — due to:

• Session ending before reaching that instruction
• Instruction being skipped or deprioritized during a long first session
• Manual workspace setup that bypassed the first-run sequence

…then BOOTSTRAP.md remains in the workspace indefinitely. It will fire on every subsequent /new or /reset invocation.

Condition 2 — IDENTITY.md Remains as the Blank Scaffold Template

File path: <workspace>/IDENTITY.md

The OpenClaw scaffold creates IDENTITY.md as a template with placeholder fields:

# IDENTITY.md — Who You Are

## Name
[Your name here]

## Role
[Your role here]

## Background
[Your background here]

## Personality
[Your personality here]

In a properly configured agent, the identity is established through:

• SOUL.md — Core personality, values, behavioral guidelines
• AGENTS.md — Operational configuration and capability definitions
• Daily memory files (e.g., MEMORY/YYYY-MM-DD.md) — Accumulated context

Critically, IDENTITY.md may never be explicitly populated because the agent establishes identity through SOUL.md and memory files — a valid and intentional approach.

The Failure Sequence

When both conditions coexist, the bootstrap logic follows this decision path:

1. New session starts → bootstrap check runs
2. BOOTSTRAP.md is detected (it was never deleted)
3. Bootstrap logic reads IDENTITY.md as the identity source
4. IDENTITY.md contains only the blank template → bootstrap concludes "no identity exists"
5. SOUL.md is read but its content is not treated as authoritative identity
6. Bootstrap onboarding flow executes instead of normal session startup
7. Agent greets as a fresh entity, ignoring all accumulated memory and context

Architectural inconsistency: The startup sequence reads IDENTITY.md as the gatekeeper for identity presence, but SOUL.md is the actual authoritative source. These two files are not treated with equal weight during the bootstrap decision.

Why Either Condition Alone May Not Trigger the Bug

Immediate Workaround (Manual — Production Systems)

Apply these steps in order. Stop when the issue is resolved.

Step 1 — Verify the current state of identity files

# Check if BOOTSTRAP.md exists (it should not)
ls -la /path/to/workspace/BOOTSTRAP.md

# Verify SOUL.md has real content (not template text)
head -20 /path/to/workspace/SOUL.md

# Check IDENTITY.md content (likely the blank scaffold)
cat /path/to/workspace/IDENTITY.md

Expected output confirming the bug condition:

-rw-r--r-- 1 user user 4096 Feb 10 09:00 /path/to/workspace/BOOTSTRAP.md
# SOUL.md - Who You Are
_You're not a chatbot. You're becoming someone._
# IDENTITY.md — Who You Are
## Name
[Your name here]

Step 2 — Populate IDENTITY.md with actual values

Edit /path/to/workspace/IDENTITY.md and replace all placeholder content:

Before (default scaffold):

# IDENTITY.md — Who You Are

## Name
[Your name here]

## Role
[Your role here]

## Background
[Your background here]

## Personality
[Your personality here]

After (populated):

# IDENTITY.md — Who You Are

## Name
rachael

## Role
Personal AI assistant and productivity partner

## Background
Configured via SOUL.md and accumulated session memory. 
Operating since 2026-01-15. Primary focus areas: research, 
writing, scheduling, and system automation.

## Personality
Resourceful, direct, and genuinely helpful. Has opinions 
and is not afraid to voice them. Prefers concise responses 
with substance over filler.

Step 3 — Create a continuity anchor in MEMORY.md

Create or update /path/to/workspace/MEMORY.md to explicitly document established identity:

# MEMORY.md — Session Continuity

## Identity Status
This agent has a fully established identity defined in SOUL.md.
IDENTITY.md has been populated. BOOTSTRAP.md should not exist.
If you see BOOTSTRAP.md on startup, treat it as stale and skip it.

## Established Context
- Agent name: rachael
- Operating since: 2026-01-15
- Workspace: /mnt/antigravity
- Primary human: [configured user]

## Key Memory Files
- Daily session logs in MEMORY/YYYY-MM-DD.md
- Soul configuration in SOUL.md
- Agent configuration in AGENTS.md

Step 4 — Delete BOOTSTRAP.md

rm /path/to/workspace/BOOTSTRAP.md

# Verify deletion
ls /path/to/workspace/BOOTSTRAP.md
# Expected: No such file or directory

Recommended Fix (Code-Level — OpenClaw v2026.2.24+)

Two complementary changes should be applied to the OpenClaw codebase:

Fix A — Bootstrap Guard: Check SOUL.md Before Firing

In the session startup / bootstrap detection logic (likely in src/core/session.ts or equivalent):

// BEFORE: BOOTSTRAP.md existence alone triggers bootstrap
if (exists(workspace, 'BOOTSTRAP.md')) {
  return executeBootstrapSequence();
}

// AFTER: Additional guard checks for real identity
if (exists(workspace, 'BOOTSTRAP.md')) {
  const soulContent = readFile(workspace, 'SOUL.md');
  const identityContent = readFile(workspace, 'IDENTITY.md');
  
  const soulIsReal = soulContent.length > 200 
    && !soulContent.includes('[Your name here]');
  const identityIsReal = identityContent.length > 50
    && !identityContent.includes('[Your name here]');
  
  if (soulIsReal || identityIsReal) {
    // SOUL.md or IDENTITY.md has real content — skip bootstrap
    return executeNormalSessionStartup();
  }
  
  return executeBootstrapSequence();
}

Fix B — Auto-Delete BOOTSTRAP.md After First Use

After the bootstrap sequence completes successfully (agent has responded to user in the first session):

// After bootstrap sequence completes
async function onBootstrapComplete(workspace: string): Promise {
  const bootstrapPath = path.join(workspace, 'BOOTSTRAP.md');
  
  if (fs.existsSync(bootstrapPath)) {
    // Move to .archive/ instead of hard delete for audit trail
    const archiveDir = path.join(workspace, '.archive');
    fs.mkdirSync(archiveDir, { recursive: true });
    const timestamp = new Date().toISOString().replace(/[:.]/g, '-');
    const archivedPath = path.join(archiveDir, `BOOTSTRAP-${timestamp}.md`);
    fs.renameSync(bootstrapPath, archivedPath);
    
    // Fallback to delete if archive fails
    if (fs.existsSync(bootstrapPath)) {
      fs.unlinkSync(bootstrapPath);
    }
  }
}

Verification Steps (Apply After Fix)

Perform these checks in sequence to confirm the issue is resolved.

Check 1 — Confirm BOOTSTRAP.md Is Absent

ls -la /path/to/workspace/BOOTSTRAP.md
# Expected: ls: cannot access '/path/to/workspace/BOOTSTRAP.md': No such file or directory
echo $?
# Expected: 2 (file not found)

Check 2 — Verify IDENTITY.md Contains Real Content

# Count non-bracket, non-whitespace characters
grep -v '^\s*\[.*\]\s*$' /path/to/workspace/IDENTITY.md | wc -c
# Expected: > 50 (meaningful content exists)

# Confirm no template placeholders remain
grep -c '\[Your name here\]' /path/to/workspace/IDENTITY.md
# Expected: 0

Check 3 — Verify SOUL.md Integrity

# Confirm SOUL.md is non-empty and non-template
wc -l /path/to/workspace/SOUL.md
# Expected: > 20 lines of real content

grep -c '\[Your' /path/to/workspace/SOUL.md
# Expected: 0 (no template placeholders)

Check 4 — Simulate a Fresh Session Start

# Trigger a new session in the affected workspace
openclaw session /new --workspace /path/to/workspace

# Expected in session log:
# - No "BOOTSTRAP.md" reference in startup sequence
# - Agent reads SOUL.md, IDENTITY.md, and MEMORY.md
# - Agent greets using established persona (not fresh onboarding)

Check 5 — Validate Session Continuity

After a new session, confirm the agent references existing context:

# In the new session, query the agent:
> "Do you remember our last conversation topic?"

# Expected: References content from SOUL.md or recent memory files
# NOT: "I don't have any previous sessions" or fresh onboarding language

Check 6 — Automated/Cron Session Verification (if applicable)

If the agent runs via cron or heartbeat automation:

# Manually trigger an automated session and check output
openclaw run --workspace /path/to/workspace --prompt "test" --no-interactive

# Expected: Session completes using established identity
# Check exit code
echo $?
# Expected: 0

• Partial fix only: Populating IDENTITY.md without deleting BOOTSTRAP.md may not fully resolve the issue if the bootstrap logic reads IDENTITY.md as a secondary check. Always verify BOOTSTRAP.md is removed or archived.
• Manual workspace setup bypassing first-run: Agents created via openclaw agent create with a pre-existing workspace may never trigger the initial bootstrap deletion step, since the bootstrap sequence runs before the agent acts on it.
• Memory file staleness: If MEMORY.md references a deleted BOOTSTRAP.md as a continuity anchor (workaround in Step 3), the agent may still treat a re-created BOOTSTRAP.md as suspicious. Ensure the workaround message is clearly commented.
• Workspace path normalization: Custom workspace paths (e.g., /mnt/antigravity vs. ~/openclaw/agents/rachael) may cause path resolution issues if the bootstrap guard logic uses relative paths. Always use absolute paths in workspace configurations.
• Case sensitivity in CI/CD environments: On filesystems with case-sensitive semantics (Linux, macOS APFS default), bootstrap.md and BOOTSTRAP.md are distinct files. Ensure the detection logic handles both cases or enforces a canonical filename.
• Race condition in auto-deletion: If the auto-delete (Fix B) runs before the first user response is sent, a session crash mid-bootstrap could leave BOOTSTRAP.md intact for the next attempt. The deletion should occur only after a confirmed user-response round-trip.
• Docker volume mounts: In Docker-based OpenClaw installations, the workspace may be mounted from the host. Archive operations (fs.renameSync) may fail silently if the mount is read-only. Test archive operations in the target deployment environment.
• Sub-agent workspaces sharing a parent directory: If multiple sub-agents share a parent workspace directory and one agent's bootstrap fires, it may corrupt the shared memory files of sibling agents. Ensure each agent has an isolated workspace directory.

• E_BOOTSTRAP_IDENTITY_CONFLICT — Bootstrap sequence detects both BOOTSTRAP.md and a populated IDENTITY.md, causing conflicting persona resolution.
• E_SESSION_STARTUP_SOUL_MISSING — Session starts without SOUL.md, resulting in a generic agent with no behavioral guidelines.
• E_MEMORY_FRAGMENTATION — Daily memory files accumulate without a coherent MEMORY.md index, causing the agent to fail to retrieve relevant past context.
• E_WORKSPACE_PERMISSION_DENIED — Bootstrap or session startup cannot read/write identity files due to permission issues; may mask as identity amnesia.
• E_BOOTSTRAP_INFINITE_LOOP — If BOOTSTRAP.md is recreated after deletion (e.g., by a git sync), the agent enters a repeated onboarding loop.
• GH#XXXX — Agent loses context on /reset — Broader session reset behavior causing loss of in-memory context (distinct from file-based identity, but may compound the BOOTSTRAP.md issue).
• GH#XXXX — SOUL.md not treated as authoritative identity source — Architectural issue where SOUL.md content is not given equal weight to IDENTITY.md in startup decisions.