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

# CLI Reference

> Complete reference for all memoclaw CLI commands, flags, and options.

## Installation

```bash theme={null}
npm install -g memoclaw
```

## Setup

### `memoclaw init`

Generate a new wallet or configure an existing one.

```bash theme={null}
# Generate a new wallet
memoclaw init

# Use an existing wallet
memoclaw init --private-key 0xYourExistingKey
```

Config is saved to `~/.memoclaw/config.json`. Every wallet gets **100 free API calls** — no payment required to start.

| Flag                  | Description                     |
| --------------------- | ------------------------------- |
| `--private-key <key>` | Use an existing EVM private key |

***

## Storing Memories

### `memoclaw store`

Store a single memory with semantic embeddings.

```bash theme={null}
memoclaw store "User prefers dark mode and vim keybindings" \
  --importance 0.8 \
  --tags preferences,editor \
  --namespace project-x
```

| Flag               | Type   | Default   | Description                                                                              |
| ------------------ | ------ | --------- | ---------------------------------------------------------------------------------------- |
| `--importance <n>` | number | `0.5`     | Importance score (0–1)                                                                   |
| `--tags <list>`    | string | —         | Comma-separated tags                                                                     |
| `--namespace <ns>` | string | `default` | Memory namespace                                                                         |
| `--type <type>`    | string | `general` | Memory type: `correction`, `preference`, `decision`, `project`, `observation`, `general` |
| `--agent <id>`     | string | —         | Agent identifier                                                                         |
| `--session <id>`   | string | —         | Session identifier                                                                       |
| `--pinned`         | flag   | `false`   | Pin memory (exempt from decay)                                                           |

**Price:** \$0.005

### `memoclaw store-batch`

Store multiple memories in a single request (up to 100).

```bash theme={null}
memoclaw store-batch \
  '{"content": "Uses PostgreSQL 15", "importance": 0.9}' \
  '{"content": "Deploys to Railway", "importance": 0.8}' \
  '{"content": "Team of 3 developers", "importance": 0.7}'
```

| Flag               | Type   | Default   | Description                |
| ------------------ | ------ | --------- | -------------------------- |
| `--namespace <ns>` | string | `default` | Namespace for all memories |
| `--agent <id>`     | string | —         | Agent identifier           |
| `--session <id>`   | string | —         | Session identifier         |

**Price:** \$0.04 per batch

***

## Retrieving Memories

### `memoclaw recall`

Semantic search — find memories by meaning.

```bash theme={null}
memoclaw recall "What are the user's editor preferences?" \
  --limit 5 \
  --min-similarity 0.7 \
  --namespace project-x
```

| Flag                   | Type   | Default   | Description                        |
| ---------------------- | ------ | --------- | ---------------------------------- |
| `--limit <n>`          | number | `10`      | Max results (1–100)                |
| `--min-similarity <n>` | number | `0.0`     | Minimum similarity threshold (0–1) |
| `--tags <list>`        | string | —         | Filter by tags (match any)         |
| `--namespace <ns>`     | string | `default` | Filter by namespace                |
| `--type <type>`        | string | —         | Filter by memory type              |
| `--after <date>`       | string | —         | Only memories after this ISO date  |

**Price:** \$0.005

### `memoclaw search`

Full-text keyword search (no embeddings). Always free.

```bash theme={null}
memoclaw search "PostgreSQL" --limit 10 --namespace project-x
```

| Flag               | Type   | Default   | Description           |
| ------------------ | ------ | --------- | --------------------- |
| `--limit <n>`      | number | `10`      | Max results (1–100)   |
| `--namespace <ns>` | string | `default` | Filter by namespace   |
| `--tags <list>`    | string | —         | Filter by tags        |
| `--type <type>`    | string | —         | Filter by memory type |
| `--agent <id>`     | string | —         | Filter by agent       |
| `--session <id>`   | string | —         | Filter by session     |

**Price:** FREE

### `memoclaw list`

List stored memories with pagination.

```bash theme={null}
memoclaw list --limit 20 --namespace project-x --tags preferences
```

| Flag               | Type   | Default   | Description           |
| ------------------ | ------ | --------- | --------------------- |
| `--limit <n>`      | number | `20`      | Max results           |
| `--offset <n>`     | number | `0`       | Pagination offset     |
| `--namespace <ns>` | string | `default` | Filter by namespace   |
| `--tags <list>`    | string | —         | Filter by tags        |
| `--type <type>`    | string | —         | Filter by memory type |
| `--agent <id>`     | string | —         | Filter by agent       |

**Price:** FREE

### `memoclaw suggested`

Get proactive memory suggestions (stale, fresh, hot, decaying).

```bash theme={null}
memoclaw suggested --category stale --limit 5
```

| Flag               | Type   | Default   | Description                            |
| ------------------ | ------ | --------- | -------------------------------------- |
| `--category <cat>` | string | —         | `stale`, `fresh`, `hot`, or `decaying` |
| `--limit <n>`      | number | `10`      | Max results                            |
| `--namespace <ns>` | string | `default` | Filter by namespace                    |

**Price:** FREE

***

## Updating & Deleting

### `memoclaw delete`

Delete a memory by ID.

```bash theme={null}
memoclaw delete 550e8400-e29b-41d4-a716-446655440000
```

**Price:** FREE

### `memoclaw update`

Update an existing memory (content change re-embeds).

```bash theme={null}
memoclaw update 550e8400-e29b-41d4-a716-446655440000 \
  --importance 0.95 \
  --tags corrections,critical
```

| Flag               | Type   | Description                         |
| ------------------ | ------ | ----------------------------------- |
| `--content <text>` | string | New content (triggers re-embedding) |
| `--importance <n>` | number | New importance score                |
| `--tags <list>`    | string | New tags (replaces existing)        |
| `--type <type>`    | string | New memory type                     |
| `--pinned`         | flag   | Pin the memory                      |

**Price:** \$0.005 (if content changes), FREE (metadata-only update)

***

## Intelligence

### `memoclaw ingest`

Extract facts from a conversation, deduplicate, and optionally create relations.

```bash theme={null}
memoclaw ingest \
  --messages '[{"role":"user","content":"I prefer dark mode and use vim."},{"role":"assistant","content":"Got it!"}]' \
  --auto-relate \
  --namespace project-x
```

| Flag                | Type   | Default   | Description                                            |
| ------------------- | ------ | --------- | ------------------------------------------------------ |
| `--messages <json>` | string | —         | JSON array of `{role, content}` messages               |
| `--namespace <ns>`  | string | `default` | Target namespace                                       |
| `--auto-relate`     | flag   | `false`   | Automatically create relations between extracted facts |

**Price:** \$0.01

### `memoclaw consolidate`

Merge similar/duplicate memories by clustering.

```bash theme={null}
memoclaw consolidate --namespace default --dry-run
```

| Flag                   | Type   | Default   | Description                      |
| ---------------------- | ------ | --------- | -------------------------------- |
| `--namespace <ns>`     | string | `default` | Target namespace                 |
| `--min-similarity <n>` | number | `0.9`     | Similarity threshold for merging |
| `--dry-run`            | flag   | `false`   | Preview without merging          |

**Price:** \$0.01

***

## Import & Export

### `memoclaw migrate`

Import markdown files (`.md`) into MemoClaw. Each `##` section becomes a separate memory.

```bash theme={null}
memoclaw migrate ~/.openclaw/workspace/memory/
```

| Flag               | Type   | Default   | Description               |
| ------------------ | ------ | --------- | ------------------------- |
| `--namespace <ns>` | string | `default` | Target namespace          |
| `--dry-run`        | flag   | `false`   | Preview without importing |

Migration is idempotent — running it twice won't create duplicates.

**Price:** \$0.01 per file

### `memoclaw export`

Export all memories as JSON.

```bash theme={null}
memoclaw export --namespace project-x > memories.json
```

| Flag               | Type   | Default | Description         |
| ------------------ | ------ | ------- | ------------------- |
| `--namespace <ns>` | string | —       | Filter by namespace |
| `--agent <id>`     | string | —       | Filter by agent     |
| `--format <fmt>`   | string | `json`  | Output format       |

**Price:** FREE

***

## Status & Info

### `memoclaw status`

Check your free tier remaining calls and wallet info.

```bash theme={null}
memoclaw status
```

```
Wallet: 0x1a2B...9cDe
Free tier: 87/100 calls remaining
```

**Price:** FREE

### `memoclaw config`

Show current configuration.

```bash theme={null}
memoclaw config
```

***

## Relations

### `memoclaw relate`

Create a directed relationship between two memories.

```bash theme={null}
memoclaw relate <source-id> <target-id> --type derived_from
```

| Flag            | Type   | Default      | Description                                                                          |
| --------------- | ------ | ------------ | ------------------------------------------------------------------------------------ |
| `--type <type>` | string | `related_to` | Relation type: `related_to`, `derived_from`, `contradicts`, `supersedes`, `supports` |

**Price:** FREE

***

## Global Flags

These flags work with any command:

| Flag          | Description                                            |
| ------------- | ------------------------------------------------------ |
| `--json`      | Output raw JSON instead of formatted text              |
| `--url <url>` | Override API URL (default: `https://api.memoclaw.com`) |
| `--help`      | Show help for a command                                |
| `--version`   | Show CLI version                                       |

## Environment Variables

| Variable               | Description                                         |
| ---------------------- | --------------------------------------------------- |
| `MEMOCLAW_PRIVATE_KEY` | Wallet private key (alternative to `memoclaw init`) |
| `MEMOCLAW_URL`         | API URL override                                    |
| `MEMOCLAW_NAMESPACE`   | Default namespace                                   |

## Next Steps

<CardGroup cols={2}>
  <Card title="Quickstart" icon="rocket" href="/get-started/quickstart">
    Get started in under 2 minutes.
  </Card>

  <Card title="Recipes" icon="book" href="/get-started/recipes">
    Common patterns and examples.
  </Card>

  <Card title="OpenClaw Hooks" icon="plug" href="/openclaw-hooks">
    Automatic memory for OpenClaw agents.
  </Card>

  <Card title="Pricing" icon="tag" href="/reference/pricing">
    Full pricing breakdown.
  </Card>
</CardGroup>