How to use the Conversation Archive Importer agent skill

What is an agent skill and what does this one do?

An agent skill is a folder containing a SKILL.md file. The file describes a task and the steps an AI agent should follow when you ask for it. Once the skill is installed, the agent can load these instructions when a request matches them.

This skill has two halves. The import half turns raw exports or session logs into dated markdown pages under conversations/, checks that each page parses correctly, extracts facts, and looks for gaps so nothing is missed. The retrieval half searches that archive before the agent answers questions, so answers come from your own past chats rather than memory.

• Imports ChatGPT conversations.json, Claude.ai exports and Perplexity exports
• Imports agent session logs such as Claude Code, Codex, OpenClaw, Hermes and Grok Build
• Writes one page per conversation, filed under conversations/ by provider
• Answers questions like when you first discussed X or how an idea changed over time

What you need before installing

The skill depends on the GBrain tool. It is not a standalone program, and it will not work on its own. You need the gbrain CLI installed and a configured brain store.

You also need your exported chat files unzipped on your computer. Optionally, you can create ~/.gbrain/harvest-private-patterns.txt to add your own redaction patterns.

• GBrain (gbrain CLI) installed and a configured brain store
• Exported chat files unzipped locally: ChatGPT conversations.json, a Claude.ai export, or a Perplexity export
• Optional: ~/.gbrain/harvest-private-patterns.txt for custom redaction patterns

Install the skill

Download the skill ZIP from the page where you found this guide. Then choose one of the following methods.

For a personal install that is available across your projects, unzip the download into ~/.claude/skills/. To limit it to one project, unzip it into that project's .claude/skills/ folder.

If you use the Claude apps, you can upload the ZIP instead. Open Settings, go to Capabilities, then Skills, and upload the file there.

• Personal install: unzip into ~/.claude/skills/
• Project install: unzip into the project's .claude/skills/ folder
• Claude apps: Settings → Capabilities → Skills, then upload the ZIP

How to trigger the skill with natural requests

You do not need a special command. Ask in plain language, and the agent will match your request against the skill's triggers. The triggers include phrases such as chatgpt export, claude export, perplexity export, conversation history, import my conversations, search my conversations, when did I first discuss, archive my session transcripts and backfill missing conversations.

Retrieval questions are answered from the archive first. The skill tells the agent not to conclude that you never discussed a topic from memory or from one failed search.

• Import my conversations from the ChatGPT export in my Downloads folder
• When did I first discuss home solar with an AI assistant?
• Search my conversations for notes on my thesis outline
• Archive my session transcripts and check for gaps
• Backfill missing conversations from the last import

Import an export with the native importer

When the source is ChatGPT, Claude.ai or an agent session log, the skill prefers the native importer. Unzip the export first, then point the command at the file. Running it with no path discovers harness logs automatically.

Before a bulk import, preview what will be scrubbed with --dry-run. Use gbrain transcripts status to compare what was found with what was imported. For oversized stores you can set a size cap with --max-bytes. Changing the cap starts a fresh watermark scope, so a capped run's skipped tail is not treated as already scanned.

Perplexity has no native adapter in this skill, so it uses the manual conversion procedure instead.

• Unzip the export first, then run: gbrain transcripts ingest ~/Downloads/conversations.json
• Discover agent session logs: gbrain transcripts ingest
• Oversized store: gbrain transcripts ingest --max-bytes 4gb <store>
• Check gaps: gbrain transcripts status

Understand what is redacted and what is not

The native importer redacts secrets by format. This covers vendor key prefixes, JWTs, cloud and API key shapes, Bearer headers, connection strings with inline passwords, PEM private keys, and high-entropy KEY=, TOKEN= or PASSWORD= assignments. It also applies your custom patterns from ~/.gbrain/harvest-private-patterns.txt.

Broad personal information detection, such as names, phone numbers and addresses, is not automatic. That review remains your job. Read sensitive conversations before you share or publish anything from the archive.

If a secret still reaches a page, rotate the secret first. Then remove the page with gbrain delete <slug> --purge. This works on the local CLI only. Git history in your brain repo or a synced file may still contain the secret.

• Automatic: secret shapes, your custom patterns, agent-directed imperatives flagged in frontmatter
• Manual: names, phone numbers, addresses and other personal details
• Long messages are capped at about 4K characters in the page body; the source session file stays the verbatim record
• Tool and thinking traffic appears only as one-line placeholders

Check, backfill and search the archive

After an import, check that pages parse and that nothing was missed. The skill's detect-and-backfill loop compares found sessions with imported ones. Ask the agent to backfill missing conversations if the status shows gaps.

For searches, ask a direct question. The agent looks in the archive before answering and can pull a specific thread or trace how an idea changed across conversations. Filenames begin with the date, which keeps timelines sortable.

• Run gbrain transcripts status to see found versus imported counts
• Ask the agent to backfill missing conversations
• Ask for a specific thread by topic or date
• Test on three to five conversations before importing thousands