Ingestion and syncing
Local processing comes before cloud sync.
Contextify first reads transcript files on your device and indexes them into a local database. Cloud sync is a separate step that moves eligible indexed history to or from hosted Contextify Cloud or your self-hosted server.
If you have years of Claude Code or Codex sessions, the first local processing pass can take time. That does not mean Cloud is stuck.
The two jobs
| Job | What it does | Where it happens |
|---|---|---|
| Ingestion and indexing | Reads transcript files, parses messages, groups them by project, and updates local search indexes. | Your Mac, or the Linux device running contextify ingest. |
| Cloud sync | Uploads and downloads eligible indexed records for the selected Cloud workspace. | Between your device and hosted Contextify Cloud, or your self-hosted Cloud server. |
A long first run is usually ingestion, not sync. Cloud cannot upload a conversation until Contextify has read and indexed it locally.
What happens on the Mac
First discovery
The app scans supported Claude Code and Codex transcript folders, creates local project records, and starts processing the conversations it can read.
Ongoing updates
As conversations continue, Contextify picks up new transcript changes and indexes the new messages. This is normal background work, not a one-time import.
Summaries and metadata
After messages are indexed, local summary and metadata queues may keep working. You may see Processing N items even after search already works.
During large local processing runs, the app can show statuses such as Indexing 3/40 projects, Processing many items..., or Up to date. These describe local work.
Why the first run can take time
Contextify is optimized for large histories, including a bulk ingestion path for high-volume first runs. It still has to parse real files, write many database rows, and build search indexes.
What affects the first run: number of transcripts, very large sessions, disk speed, battery and sleep behavior, folder access, and whether the app is rebuilding a fresh database.
What to do: keep the app open, let the Mac stay awake if the history is large, and check the status bar before assuming Cloud has failed.
If you quit during a large run, Contextify is designed to resume later. The safest first-run experience is still to let the initial pass finish.
How Cloud sync fits in
Cloud sync starts from the local database. It uploads eligible local records and pulls eligible remote records for the configured workspace.
- Hosted Cloud and self-hosted Cloud use the same basic client model.
- Project Sync controls which local projects upload from this device.
- Sync may wait while ingestion is active so local database writes do not fight each other.
- If a cloud target is unreachable, indexed history stays in the local database. Sync can retry after the target is reachable again, though authentication, Project Sync settings, or server errors may still require attention.
Switching cloud targets is not a server-to-server migration. It changes where this device syncs next. Read the cloud switching guide before moving between hosted and self-hosted Cloud.
Linux and CLI behavior
On Linux there is no Mac app watching transcripts in real time. The CLI ingests in batches.
contextify status
contextify ingest
contextify install-service
contextify ingest runs once and exits. contextify install-service sets up periodic background ingestion on Linux, using a systemd timer when available. The default interval is 15 minutes.
Cloud commands are separate from ingestion commands:
contextify cloud status
contextify cloud projects
contextify cloud syncCommon status words
Some labels vary slightly by app version and surface, but these are the common categories.
| Status | Usually means | What to do |
|---|---|---|
| Processing N items | Local summary or metadata queues are still working. | Wait, then search again if the newest context is not visible yet. |
| Indexing X/Y projects | The app is still ingesting known projects locally. | Let the first pass finish before judging Cloud sync progress. |
| Waiting | Cloud sync is waiting for transcript ingestion to finish. | No action is usually needed. |
| Deferred | Sync paused because local ingestion or database writes were active. | It retries automatically, or you can sync manually later. |
| Syncing | The device is uploading or downloading Cloud changes. | Keep the app open for large catch-up uploads. |
| Offline | The configured Cloud target is unreachable. | Check the exact hosted or self-hosted target, not just general internet access. |
| Attention needed | A server-side catch-up session appears stalled or completed with issues. | Use Retry, then check Cloud sync troubleshooting if it returns. |
Where to go next
Last updated: May 6, 2026