claude-import

---
name: claude-import
description: Use when migrating a Claude.ai data export into a configured Hermes memory provider.
version: 1.0.0
author: Magnus Hedemark, Nous Research contributors
license: MIT
platforms: [linux, macos, windows]
metadata:
  hermes:
    tags: [migration, claude, memory, import, data]
    related_skills: [agent-memory, hermes-agent]
---

# Claude Data Export Import

Import a Claude.ai data export into the active Hermes memory provider. The parser is read-only and stdlib-only. The import itself must use Hermes's `memory` tool, preserving the active provider's normal write hooks.

## When to Use

- Migrating from Claude.ai to Hermes Agent.
- A user has a Claude export and wants its conversations or project memories in Hermes.

Do not use this to import individual files or Claude attachments. It imports text from `conversations.json` and optional `memories.json` only.

## Prerequisites

1. The user has downloaded their export from Claude.ai **Settings → Privacy → Export data**.
2. Hermes has a non-builtin memory provider. Run `hermes memory status` before parsing.
3. If status shows no configured external provider, stop. Do not import into the builtin filesystem provider: a complete export can produce thousands of entries without reliable write acknowledgement.

## Procedure

### 1. Validate the input

Confirm the export directory exists and contains `conversations.json`, either directly or in a `data-*` subdirectory. Never modify the export.

### 2. Parse it

From this skill's directory:

```bash
python3 scripts/claude_parse.py /path/to/claude-export \
  --output /tmp/claude-memory-units.json
```

The parser streams large `conversations.json` arrays and emits units with `content`, `source_type`, `conversation_uuid`, and timestamps. It reads `memories.json` too, unless `--no-memories` is supplied.

### 3. Inspect the unit count

Read `/tmp/claude-memory-units.json`. Report the number of units before writing. Import `project_memory` and `conversation_memory` units first: they are Claude's curated summaries and usually carry more value than raw conversation units.

### 4. Import in batches

Use the `memory` tool, not direct database access. Put ten conversation units in each call and five curated-memory units in each call. Preserve every unit's provenance:

```python
combined = "\n\n---\n\n".join(
    "\n".join([
        f"[UUID: {u['conversation_uuid']}]",
        "[Source: claude]",
        f"[Type: {u.get('source_type', 'conversation')}]",
        f"[Timestamp: {u.get('timestamp', 'unknown')}]",
        u["content"],
    ])
    for u in batch
)
memory(action="add", target="memory", content=combined)
```

If the number of calls exceeds the session iteration budget, continue in a new turn using the same JSON file. Do not re-parse or re-import completed UUIDs.

### 5. Verify receipt

`memory` success confirms dispatch, not necessarily the provider's durable index. Verify once at the provider layer using `hermes memory status` or the provider's own supported query interface. Report dispatched unit count, batch count, and export path.

## Pitfalls

- **No external provider:** stop before any import. The builtin filesystem provider is not a safe destination for a full export.
- **Re-imports duplicate data:** the parser preserves UUIDs, but does not deduplicate. Track imported UUIDs before a retry.
- **Attachments are omitted:** files, images, and artifacts embedded in conversations are deliberately not imported.
- **Large exports:** do not replace the parser with `json.load`; its streaming path exists to bound memory use.

## Verification Checklist

- [ ] `hermes memory status` shows an external provider before import.
- [ ] Parser completed and produced valid JSON.
- [ ] Curated `memories.json` units were prioritized.
- [ ] Every imported batch retains UUID, source, type, and timestamp.
- [ ] Provider receipt was checked once after dispatch.