Concepts

Core concepts behind ClawDNA — how identity files, bundles, sync, and environments work together to keep your agent's personality safe and portable.

Identity Files

ClawDNA manages the files that define your agent's identity. These are what make your agent yours — ClawDNA versions and syncs them so they never drift or get lost.

File	Purpose
`SOUL.md`	Personality, values, and behavioral rules
`AGENTS.md`	Workspace conventions and operating rules
`IDENTITY.md`	How the agent presents itself
`MEMORY.md`	Accumulated knowledge about the user
`TOOLS.md`	Installed skills and tool configurations
`USER.md`	User-specific context and preferences

The .dna Bundle

A snapshot produces a .dna bundle: a compressed tarball (.tar.gz) containing all identity files plus a manifest with metadata. Bundles are the unit of sync — they get pushed to and pulled from the hub.

Bundle Structure

openclaw-backup-2026-03-15T14-22-00-pedro-main.dna
├── manifest.json              # Bundle metadata
├── identity/
│   ├── SOUL.md
│   ├── AGENTS.md
│   ├── IDENTITY.md
│   ├── TOOLS.md
│   ├── USER.md
│   └── MEMORY.md
├── skills/
│   ├── crm-connector/
│   │   └── SKILL.md
│   └── calendar-sync/
│       └── SKILL.md
├── config/
│   └── openclaw.sanitized.json  # Secrets removed
└── claw.dna.yaml              # Platform-agnostic export

Manifest

Every bundle contains a manifest.json with metadata: bundle ID, agent ID, environment ID, timestamps, OpenClaw version, Node version, platform, and SHA-256 hashes for every included file.

The claw.dna.yaml Format

The canonical, platform-agnostic identity definition. Human-readable and version-controlled.

# claw.dna.yaml — ClawDNA Identity Definition v1
version: "1"

identity:
  id: "pedro-main"
  name: "ClawBot"

files:
  soul: "./SOUL.md"
  agents: "./AGENTS.md"
  identity: "./IDENTITY.md"
  tools: "./TOOLS.md"
  user: "./USER.md"
  memory: "./MEMORY.md"

config:
  model: "anthropic/claude-sonnet-4-6"

environments:
  primary:
    config:
      model: "anthropic/claude-opus-4-6"
    channels:
      telegram:
        bot_token: "$TELEGRAM_PRIMARY_BOT_TOKEN"

sync:
  hub: "clawdna-cloud"
  auto_push: true

Secrets are never stored inline — always use $ENV_VAR references. ClawDNA resolves these at runtime from your environment.

Sync Protocol

The sync protocol tracks state per environment-hub pair. Each side maintains a content hash (SHA-256 of all identity files).

Protocol States

State	Meaning	Action
`SYNCED`	Local hash == hub hash	No action needed
`AHEAD`	Local has unpushed changes	Push available
`BEHIND`	Hub has changes not pulled	Pull available
`DIVERGED`	Both sides changed since last sync	Conflict resolution required
`UNKNOWN`	No sync state recorded	First sync required

Push Flow

Collect identity files
Run secrets sanitizer — abort if violations found
Compute local hash (SHA-256 of all identity file contents)
Fetch current hub hash and compare
Create sanitized bundle
Upload bundle to hub
Update hub manifest and local sync state
Notify registered webhooks (non-blocking)

Pull Flow

Fetch hub manifest (latest hash, timestamp, env attribution)
Compute local hash and compare
Download latest bundle
Compute diff (local vs bundle)
Show diff for user confirmation (unless --quiet)
Apply bundle to local workspace (identity files only)
Never overwrite: .env, credentials, sessions, local-only files
Update local sync state

Environments

An environment represents one instance of your agent running on a specific machine. Each environment has a role that determines its sync behavior.

Role	Description
`primary`	Source of truth. Changes here are pushed to the hub and pulled by replicas.
`replica`	Pulls identity from the primary. Can have local config overrides (different channels, model).
`fork`	Independent copy. Started from a primary's identity but diverges freely.

Environment profiles are stored locally at ~/.clawdna/envs/<env-id>.profile.yaml and are never synced. They contain secret references, sync role, and local path overrides.

Memory Distillation

Over time, your agent accumulates session memory — facts about the user, preferences, conversation context. Memory distillation uses an LLM to classify these entries as:

Core — permanent facts that should persist in MEMORY.md (e.g., "user prefers dark mode")
Ephemeral — session-only context that should expire (e.g., "user is debugging a React component")

Core facts are promoted to MEMORY.md and synced to all environments. Ephemeral entries are discarded. This keeps your agent's memory focused and prevents context bloat.

Secrets Sanitization

Every push, export, and distillation operation passes through a secrets sanitizer before any data leaves the machine. The sanitizer detects:

API key patterns (OpenAI, Anthropic, Telegram, Discord)
Bearer tokens and JWTs
Private key headers
Custom patterns defined in ~/.clawdna/.secretsignore

If a secret is found in any identity file, the operation is aborted with a clear error. This is a hard gate — it cannot be bypassed without the explicit --force-unsafe flag.