Skip to main content
The chatgpt2memmachine utility is a Python-based migration tool that transforms exported chat histories into episodic or semantic memories within your MemMachine organization.
Before starting, ensure you have your orgId and projectId available from your MemMachine dashboard.

​
Quick Start

1

Prepare your Data

Export your chat history from OpenAI (Settings > Data Controls > Export Data) or locate your Locomo history JSON file.
2

Install Dependencies

Clone the tool from the official repository and install required Python packages.
3

Run the Migration

Execute the script using the --source flag matching your data.

​
Configuration

The migration script supports several arguments to fine-tune how data is ingested.

​
Core Arguments

​
Filtering & Logic

​
Advanced Operations

​
Resuming Failed Jobs

If a migration is interrupted, use the run-id generated in the output/ directory to retry or resume.

​
Performance Tuning

For large datasets, use parallel processing to speed up the ingestion:
Start with --workers 4 to balance speed without hitting rate limits on your local MemMachine instance.

​
Output & Logs

Each migration run generates a unique run_id and stores data in the following directories:
  • extracted/: Contains extracted conversations saved for caching.
  • output/success_{run_id}.txt: List of successfully migrated message IDs.
  • output/errors_{run_id}.txt: List of failed messages with error details.
  • output/migration_stats_{run_id}.json: Summary of counts and duration.

​
Verifying Your Migration

Once the script completes, you can verify that your memories were correctly ingested by checking the following:
1

Check the Output Files

The script generates a migration_stats_{run_id}.json file in the output/ directory. Open it to confirm:
  • total_messages_processed matches your expectations.
  • success_count represents the majority of your data.
2

Spot-Check the API

You can query your MemMachine instance directly to see if the new memories appear in your project.
3

Review the Trace (Optional)

If things look off, check trace_{run_id}.txt. This file contains the raw API responses for every message, which is the “Source of Truth” if a specific conversation didn’t migrate.