Transform messy social media exports into well-organized, properly dated media libraries
Features • Quick Start • Documentation • Platforms • Contributing
- What is Memoria?
- Key Features
- Important Disclaimers
- What Do You Get?
- Design Philosophy
- Supported Platforms
- Quick Start
- Documentation
- Contributing
- License
Memoria transforms messy social media exports into well-organized, properly dated media libraries.
It takes the JSON metadata files, HTML conversation dumps, and scattered media files from your platform exports and produces a clean collection where every photo and video has its original timestamp, location, and context embedded directly into the file itself - making your memories searchable and sortable in any photo application, now and in the future.
|
Smart Metadata Processing
|
Industry-Standard EXIF
|
|
Intelligent Organization
|
Batch Processing & Integration
|
Caution
Backup and Data Loss
While Memoria processes copies of your export files and does not modify the original export directories, I am not responsible for any data loss. Always maintain backups of your original exports before processing.
Warning
AI-Generated Code
This codebase was created with the assistance of AI. It is strongly recommended that you thoroughly review and test the code before using it in any production environment or with irreplaceable data.
Important
Read the Documentation
Please read all documentation carefully before use. This tool makes specific design decisions that may not align with everyone's needs or expectations. Make sure you fully understand the purpose and behavior of this program before processing your data.
After processing, your files are transformed with rich metadata embedded directly into each file.
Metadata Embedding
Every processed file gets comprehensive EXIF metadata written using ExifTool:
Standard Tags
| Tag Type | What's Embedded | EXIF Fields |
|---|---|---|
| Timestamps | Original capture date/time | DateTimeOriginal, CreateDate, ModifyDate |
| GPS | Location data when available | GPSLatitude, GPSLongitude, GPSAltitude |
Source Information
| File Type | Description Fields |
|---|---|
| Images | ImageDescription, IPTC:Caption-Abstract |
| Videos | Comment, Description |
Description Format Examples
Source: iMessage/mac - John Doe in "DM with +14045551234"
Source: Instagram/username/messages - Best Friends - John Doe
Source: Google Photos/john.doe@gmail.com
Source: Snapchat/username/memories - Story from 2023-01-15
Platform captions and message text are preserved inline with the metadata.
File Naming
Files are renamed with descriptive, sortable names that include platform, username, and date:
| Platform | Example Filename |
|---|---|
| Google Chat | gchat-john.doe-Family Chat-20230115.jpg |
| iMessage | imessage-mac-14045551234-20230115.heic |
| Instagram Messages | instagram-messages-jane_doe-Best Friends-20230220.mp4 |
| Snapchat Messages | snap-messages-user123-john-20230310.jpg |
| Instagram Posts | insta-posts-user123-20230405.jpg |
| Google Photos | gphotos-john.doe-IMG_1234.jpg |
Organization Structure
Processed files are organized by platform and service/media type:
platform-username-YYYYMMDD/
├── photos/ # Google Photos
│ └── gphotos-john.doe-*.jpg
├── chat/ # Google Chat
│ └── gchat-john.doe-*.jpg
├── messages/ # iMessage/Instagram/Snapchat Messages
│ └── imessage-mac-*.heic
│ └── *-messages-*.jpg
└── memories/ # Snapchat Memories
└── snap-*.mp4
Additional Features
- File modification times set to match original capture dates
- Files sort correctly in any file browser
- Easy to navigate and find specific content
Your media becomes truly portable and future-proof
Every file carries its complete history in industry-standard formats
| What's Preserved | How It's Stored |
|---|---|
| When it was taken | EXIF timestamps |
| Where you were | GPS coordinates |
| Who sent it | Description metadata |
| What platform it came from | Source tags |
Compatible with any photo management application, cloud service, or future software you might use.
Memoria makes specific design choices that prioritize data portability and future-proofing.
-
Metadata-First Approach: All context is embedded directly in files using industry-standard EXIF tags, not stored in sidecar files or databases
-
Flat Organization: Files are organized by platform/username, not by albums or conversations, to simplify deduplication and avoid complex folder structures
-
Deduplication by Default: Google Photos automatically deduplicates across albums to save space and reduce processing time
-
Non-Destructive Processing: Original exports are never modified; all operations work on copies
Note
For detailed rationale behind these decisions, see the Design Decisions document.
Memoria can process exports from the following platforms:
| Platform | Service | What's Supported |
|---|---|---|
| Apple | iMessage | Mac and iPhone message exports with cross-export deduplication |
| Photos | Albums, shared libraries, and photo metadata | |
| Chat | Group and direct message media | |
| Voice | SMS messages and media | |
| Messages | DM and group chat media | |
| Public Media | Posts, archived posts, stories, etc. | |
| Old Format | Legacy timestamped exports | |
| Snapchat | Memories | Saved snaps and stories with overlay embedding |
| Messages | Chat media from conversations |
Tip
Each platform has specific export requirements. See our export guides for detailed instructions.
First, install system dependencies:
# Ubuntu/Debian
sudo apt-get install exiftool ffmpeg
# macOS
brew install exiftool ffmpegThen install Python dependencies:
pip install -r requirements.txt
# or for development
pip install -e .# Process a single export
./memoria.py /path/to/export -o /path/to/output
# Process multiple exports in parallel
./memoria.py --originals /path/to/all-exports -o /path/to/output
# List available processors
./memoria.py --list-processors
# Enable verbose logging
./memoria.py /path/to/export -o /path/to/output --verboseTip
See the Getting Started Guide for detailed installation instructions and the Usage Guide for all command-line options.
Before processing, export your data from the platforms:
| Platform | Guide | What to Export |
|---|---|---|
| Apple | iMessage Export Guide | Messages from Mac or iPhone |
| Google Export Guide | Photos, Chat, Voice | |
| Instagram Export Guide | Messages, Posts, Stories | |
| Snapchat | Snapchat Export Guide | Memories, Messages |
Getting Started
- Getting Started - Installation, system requirements, and initial setup
- Usage Guide - Complete command-line reference and workflows
Platform-Specific Guides
- Google Export - Google Photos, Chat, and Voice export setup
- iMessage Export - Mac and iPhone message exports
- Instagram Export - Instagram Messages, posts, and legacy formats
- Snapchat Export - Snapchat Memories and Messages setup
Advanced Topics
- Immich Upload - Immich upload configuration and ignore patterns
- Parallel Processing - Process multiple exports in parallel
- Upload Only Mode - Upload previously processed exports
- Upload Queuing - Parallel processing upload queuing
- Logging - Logging configuration and verbose mode
- Deduplication - Google Photos deduplication system
- Standalone Tools - Standalone utility scripts for analysis and comparison
Reference
- FAQ - Frequently asked questions
- Common Gotchas - Important behaviors and surprises to know
- Design Decisions - Rationale for architectural choices
| Scenario | Recommendation |
|---|---|
| First Time? | Start with the Getting Started Guide for setup instructions |
| Important Behaviors | Read Common Gotchas to avoid surprises |
| Export Setup | See platform-specific guides for export preparation |
| Performance | Use --workers N to control parallelism |
| Multiple Exports | Use --originals to batch process everything at once |
| Debugging | Enable --verbose for detailed logs |
| Immich Upload | Configure automatic upload to your Immich server |
| Questions? | Check the FAQ for common questions |
Contributions are welcome! We'd love your help making Memoria better.
Quick Start for Contributors
- Fork the repository
- Create a feature branch (
git checkout -b feature/amazing-feature) - Make your changes
- Run tests and linting
- Submit a pull request
See CONTRIBUTING.md for detailed guidelines on development setup, code standards, and adding new processors.
Special thanks to the immich-go project, which provided valuable insights into understanding the structure and handling of Google Photos takeout formats.
This project is licensed under the MIT License - see the LICENSE file for details.
Disclaimer: This project is provided as-is for personal use in organizing and preserving your social media exports.
Common Issues & Solutions
| Issue | Solution |
|---|---|
exiftool is not installed or ffmpeg not found |
Install required system dependencies (see Quick Start) |
No processors matched input directory |
Check export structure against platform guides |
| Import errors | Try installing in development mode: pip install -e . |
| Performance issues | See Usage Guide for optimization |
For more help, see the Getting Started Guide.