Chat History Import

Chat History Import

Use this skill when a user wants to import chat history from Claude, ChatGPT, Telegram Desktop exports, Slack exports, markdown logs, JSON/JSONL transcripts, or similar archives into an OpenClaw workspace.

The most common source formats for this skill are ChatGPT exports and Claude exports. Telegram Desktop HTML exports are also supported when the user wants to backfill a Telegram direct chat or group into OpenClaw's raw archive. If the user has not exported data yet, suggest the usual official export entry points first:

• ChatGPT: Settings -> Data Controls -> Export
• Claude: Settings -> Privacy -> Export data

These exports usually arrive as ZIP files and are good candidates for the built-in import flow.

What This Skill Owns

• raw archive import into logs/message-archive-raw/
• daily memory distillation into memory/YYYY-MM-DD.md
• MEMORY.md candidate generation
• review and apply workflow for memory merges

Related OpenClaw Components

This skill is not a replacement for the live archive plugin or archive search skill.

• conversation-archive plugin
  • Recommended when the workspace wants future live chats written into the same logs/message-archive-raw/ tree.
  • This skill should emit archive files that are fully compatible with that plugin's raw archive layout.
• conversation-history skill
  • Strongly recommended when the user wants agents to search imported history after import.
  • This import skill writes archive files; it does not replace archive recall/search workflows on its own.

Preferred combined setup:

1. use chat-history-import to backfill old history
2. use conversation-archive to keep new history flowing in
3. use conversation-history to search both imported and live archive data

What Scripts Do vs. What The Model Does

Scripts handle deterministic work:

• inspect the source archive
• normalize messages into the archive schema
• validate archive compatibility
• write review artifacts
• apply approved memory merges

Validation must be reported in two layers when relevant:

• import-batch validation: whether the files written by this import are valid
• full-archive validation: whether the entire existing archive tree is valid

If full-archive validation fails because of pre-existing files outside this import batch, do not describe the new import itself as failed. Report the historical archive issue separately.

The model handles semantic work:

• decide what each day is worth remembering
• rewrite imported history into the style of existing OpenClaw daily memory
• decide what belongs in MEMORY.md
• compare imported MEMORY.md candidates against existing MEMORY.md

Do not try to replace this semantic step with Python heuristics.

Also do not assume the bundled Python parsers can recognize every source format. For unknown input formats, the model may need to inspect the source and write a temporary format-specific parser.

Core Rules

1. Do not import external history into agents/<agentId>/sessions/.
2. Treat logs/message-archive-raw/ as the canonical destination for imported raw chat history.
3. Imported archive output must pass {baseDir}/scripts/validate_archive.py and stay compatible with the conversation-archive plugin's archive contract.
4. Daily memory should merge into the existing memory/YYYY-MM-DD.md file for that date.
5. Daily memory body should look like normal OpenClaw memory: concise Chinese bullets, minimal metadata, no “Claude 备份里显示” phrasing.
6. Use a short HTML comment only to mark import provenance.
7. MEMORY.md is the default memory file here and is always review-required before apply.

Large Export Handling

If the user says they already uploaded an archive, but the current chat channel only exposes a placeholder or incomplete file payload, treat that as a transport limitation first.

For large ChatGPT or similar exports, guide the user toward a smaller text-focused package before retrying upload:

1. unzip the export locally
2. keep the conversation JSON files first
3. keep optional small metadata files only when useful
4. remove bulky attachments such as images, audio, video, PDFs, Office files, and other binary artifacts
5. re-zip the reduced package and retry import

For ChatGPT-style exports, the most important files are usually:

• conversations.json
• conversations-*.json
• optional: group_chats.json
• optional: export_manifest.json

If the reduced archive still cannot be uploaded through the chat channel, ask for one of these instead:

• a direct download URL
• a host-local file path
• a cloud storage link that can be fetched from the host

Use a temp path or another host-local staging path for large imports rather than polluting workspace/.

Import Workflow

1. Inspect

Start by inspecting the source:

python3 {baseDir}/scripts/inspect_import.py /path/to/archive-or-file

Use local file structure first. Use web research only as fallback for unclear formats.

When helpful, check whether the current workspace already has conversation-archive and conversation-history available, so the user can be told what will happen after import:

• archive-only import
• import plus future live archive
• import plus searchable archive recall

2. Normalize Raw Archive

Normalize the source into the archive schema described in {baseDir}/references/schema.md:

python3 {baseDir}/scripts/normalize_import.py /path/to/archive --archive-root logs/message-archive-raw --workspace workspace --agent-id main --apply
python3 {baseDir}/scripts/validate_archive.py logs/message-archive-raw

After validation, explicitly separate these outcomes:

1. whether the newly written files from this import batch are valid
2. whether the pre-existing archive tree is fully valid

If validation errors point to old archive files unrelated to the current import, report that clearly as a historical archive issue rather than an import-batch failure.

Unknown Format Handling

When the bundled parser does not recognize the input format, use this fallback sequence:

1. Inspect the source files directly.
2. Determine whether the structure is simple enough to map by hand.
3. If not, write a temporary Python parser under a temp directory.
4. Make that parser output the canonical archive JSONL shape from {baseDir}/references/schema.md.
5. Run {baseDir}/scripts/validate_archive.py on the result before claiming success.

Preferred order:

1. bundled parser
2. model-assisted direct mapping
3. model-authored temporary parser

Guardrails for temporary parsers:

• only transform source data into canonical archive JSONL
• do not write directly into MEMORY.md
• do not bypass the archive validator
• keep source-specific logic isolated; do not pollute the skill with one-off code unless the format is worth supporting permanently

If a bundled parser is missing for a format that seems broadly reusable, mention that it may be worth promoting the temporary parser into a maintained parser later.