> ## Documentation Index
> Fetch the complete documentation index at: https://docs.argentos.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Legacy Migration Reference

> Historical reference for transitioning from a legacy OpenClaw installation to ArgentOS.

## Overview

This page is a historical reference for users transitioning from legacy OpenClaw installations. ArgentOS was inspired by OpenClaw's original vision but is an independently developed AI operating system with 90,000+ lines of original code. The two projects have diverged significantly and are no longer compatible.

<Info>
  The migration tool preserves data from legacy installations:

  * Agent identity files (SOUL.md, AGENTS.md)
  * User profile (USER.md)
  * Tool configurations (TOOLS.md)
  * Memory and daily logs (MEMORY.md, memory/\*.md)
  * Channel configurations
  * Cron jobs and schedules
</Info>

```
+-----------------------------------------------------------------------------+
|                    LEGACY DATA -> ARGENTOS MIGRATION                         |
|                                                                             |
|   Legacy Installation                ArgentOS Workspace                     |
|   ~/.openclaw/                       ~/.argentos/                           |
|                                                                             |
|   +-- workspace/          --->    +-- workspace/                           |
|   |   +-- SOUL.md         --->    |   +-- SOUL.md         (preserved)     |
|   |   +-- AGENTS.md       --->    |   +-- AGENTS.md       (upgraded)      |
|   |   +-- USER.md         --->    |   +-- USER.md         (preserved)     |
|   |   +-- TOOLS.md        --->    |   +-- TOOLS.md        (preserved)     |
|   |   +-- MEMORY.md       --->    |   +-- MEMORY.md       (preserved)     |
|   |   +-- HEARTBEAT.md    --->    |   +-- HEARTBEAT.md    (upgraded)      |
|   |   +-- memory/         --->    |   +-- memory/         (preserved)     |
|   |                                                                         |
|   +-- config.json         --->    +-- config.json         (converted)     |
|   +-- sessions/           --->    +-- sessions/           (preserved)     |
|   +-- credentials/        --->    +-- credentials/        (preserved)     |
|                                                                             |
|   Legacy memory database  --->    Built-in MemU system                     |
|   ~/.openclaw-mem/        --->    ~/.argentos/data/memory.db               |
|                                                                             |
+-----------------------------------------------------------------------------+
```

## Migration Commands

<Warning>
  These commands are for users transitioning from legacy installations only. New users should follow the [Getting Started](/start/getting-started) guide instead.
</Warning>

<CodeGroup>
  ```bash One-command migration theme={null}
  argent migrate from-openclaw
  ```

  ```bash With explicit path theme={null}
  argent migrate from-openclaw --workspace ~/.openclaw/workspace
  ```

  ```bash Dry run (preview) theme={null}
  argent migrate from-openclaw --dry-run
  ```

  ```bash Specific components only theme={null}
  argent migrate from-openclaw --only identity,memory
  ```
</CodeGroup>

## What Gets Migrated

### 1. Identity Files

| File          | Description                   | Migration                       |
| ------------- | ----------------------------- | ------------------------------- |
| `SOUL.md`     | Personality, values, behavior | Copied as-is                    |
| `AGENTS.md`   | Workspace conventions         | Upgraded with ArgentOS features |
| `USER.md`     | Owner profile                 | Copied as-is                    |
| `TOOLS.md`    | Tool notes, API keys          | Copied as-is                    |
| `IDENTITY.md` | Additional identity           | Copied if exists                |

### 2. Memory

| Source                      | Destination                  | Notes                          |
| --------------------------- | ---------------------------- | ------------------------------ |
| `MEMORY.md`                 | `MEMORY.md`                  | Preserved exactly              |
| `memory/*.md`               | `memory/*.md`                | All daily logs preserved       |
| `~/.openclaw-mem/memory.db` | `~/.argentos/data/memory.db` | Legacy SQLite migrated to MemU |
| `~/.openclaw-mem/chroma/`   | `~/.argentos/data/vectors/`  | Vectors migrated if exists     |

### 3. Configuration

```yaml theme={null}
# Legacy config.json -> ArgentOS config.json

# Channel credentials preserved:
telegram:
  token: "..." -> telegram.token

discord:
  token: "..." -> discord.token

# Model settings converted:
model: "anthropic/claude-sonnet-4" -> models.default: "balanced"

# ArgentOS systems enabled:
+ sis.enabled: true
+ tasks.enabled: true
+ models.routing.enabled: true
+ models.local.endpoint: "http://localhost:11434"
```

### 4. Channel Credentials

All channel credentials are migrated:

* Telegram bot tokens
* Discord bot tokens
* Slack app credentials
* Signal sessions
* WhatsApp sessions (Baileys auth)

### 5. Sessions & History

* Active sessions preserved
* Conversation history maintained
* Session keys unchanged (no disruption)

## Migration Process

<Steps>
  <Step title="Install ArgentOS">
    ```bash theme={null}
    # Install ArgentOS globally
    npm install -g argentos

    # Or with Bun
    bun install -g argentos
    ```
  </Step>

  <Step title="Run Migration">
    ```bash theme={null}
    # Interactive migration wizard
    argent migrate from-openclaw

    # Wizard prompts:
    # Found legacy workspace at ~/.openclaw/workspace
    # Found identity files: SOUL.md, AGENTS.md, USER.md, TOOLS.md
    # Found memory: MEMORY.md + 47 daily logs
    # Found legacy memory database: 1,234 observations
    # Found channels: telegram, discord, whatsapp
    #
    # Ready to migrate. This will:
    # - Create ArgentOS workspace at ~/.argentos/
    # - Copy all identity and memory files
    # - Convert configuration
    # - Migrate memory database to MemU
    #
    # Continue? [Y/n]
    ```
  </Step>

  <Step title="Verify Migration">
    ```bash theme={null}
    # Check migration status
    argent doctor

    # Output:
    # Identity files: OK
    # Memory system: OK (1,234 observations imported)
    # Channels: telegram (OK), discord (OK), whatsapp (OK)
    # Configuration: OK
    #
    # ArgentOS is ready!
    ```
  </Step>

  <Step title="Start ArgentOS">
    ```bash theme={null}
    # Start all services
    argent start

    # Or start gateway only
    argent gateway start
    ```
  </Step>
</Steps>

## Manual Migration

If you prefer manual migration:

```bash theme={null}
# 1. Create ArgentOS workspace
mkdir -p ~/.argentos/workspace

# 2. Copy identity files
cp ~/.openclaw/workspace/SOUL.md ~/.argentos/workspace/
cp ~/.openclaw/workspace/AGENTS.md ~/.argentos/workspace/
cp ~/.openclaw/workspace/USER.md ~/.argentos/workspace/
cp ~/.openclaw/workspace/TOOLS.md ~/.argentos/workspace/
cp ~/.openclaw/workspace/MEMORY.md ~/.argentos/workspace/
cp -r ~/.openclaw/workspace/memory ~/.argentos/workspace/

# 3. Copy credentials
cp -r ~/.openclaw/credentials ~/.argentos/

# 4. Migrate memory database
mkdir -p ~/.argentos/data
cp ~/.openclaw-mem/memory.db ~/.argentos/data/

# 5. Convert config (use migration tool)
argent migrate convert-config ~/.openclaw/config.json
```

## FAQ

<AccordionGroup>
  <Accordion title="Will my agent's personality change?">
    No. Your `SOUL.md` and identity files are copied exactly as-is.
  </Accordion>

  <Accordion title="Will I lose my memories?">
    No. All memory files and the legacy database are migrated to MemU.
  </Accordion>

  <Accordion title="What about my channel connections?">
    All credentials are migrated. Your Telegram, Discord, Slack, Signal, and WhatsApp connections will work immediately.
  </Accordion>
</AccordionGroup>

## Support

Need help with migration?

* Documentation: [argentos.ai/docs](https://argentos.ai/docs)
* Discord: [discord.gg/argentos](https://discord.gg/argentos)
* GitHub Issues: [github.com/ArgentAIOS/core/issues](https://github.com/ArgentAIOS/core/issues)