Prerequisites
Data format
Everything is a session of messages. Each message names its speaker withsender_id. A one-on-one conversation uses the user’s id plus "assistant"; a
group conversation uses several ids. Same format either way.
Convert your data
Map your source export into the session format. Sort chronologically, because EverOS uses timestamps for boundary detection.Batch importer
The importer sends each conversation in chunks (theadd endpoint takes up to
500 messages per call), retries transient failures, and flushes at the end so
extraction starts promptly. Conversations are imported in parallel with a thread
pool; chunks within a conversation go in order to preserve the timeline.
Writes are asynchronous server-side. Add returns as soon as messages are
accepted, and extraction runs in the background. The
flush at the end
accelerates extraction for that session; it isn’t required for the data to be
processed.Resumable imports
For large jobs, checkpoint completed sessions so a re-run skips them.Best practices
Sort by timestamp
Sort by timestamp
Always sort messages chronologically before importing. Boundary detection
depends on it. Include real
timestamps (in ms) so historical time-based
recall works.Chunk size
Chunk size
Keep chunks at or below the 500-message limit. 100–200 is a good balance of
throughput and per-request size.
Concurrency and rate limits
Concurrency and rate limits
Parallelize across conversations with the thread pool; keep chunks within a
conversation ordered. If you hit
429, lower max_workers. The retry
helper already backs off.Stream large directories
Stream large directories
Read one file at a time (as the importer does) rather than loading every
export into memory at once.
Next steps
Python Integration
Client management, error handling, and concurrency patterns.
Multi-Party Conversations
Work with imported group chat memories.

