Reference

Available sources

Every source Omnesis can index, what each one adds to your index, and how to manage the sources you have connected. It is for anyone deciding what to connect, or looking after a running setup.

A source is one account's data from one platform, such as a Gmail mailbox or your Apple Notes. A provider is one sign-in that serves several source types: signing in to Google once covers Gmail, Calendar, Drive, and Contacts. Most sources run on a collector — some on any machine, some only on macOS because they read local Apple databases. A few run inside the phone apps and push straight to the gateway. A handful live on the gateway itself: Web Pages (type web), fed by the browser extension, and the Omnesis-native sources listed under Omnesis itself.

Every source follows the same deletion rule. An item goes when the platform reports it deleted, or when complete, successful reads stop listing it — and in that second case Omnesis waits for several reads over time to agree before removing it. A failed or partial read never deletes anything. Managing sources covers adding, pausing, re-syncing and removing them, and Sources on several devices covers what happens when two machines or phones host the same source.

In the tables below, the tags under each source's name say where it runs and how it connects — any collector OAuth, for example.

Email & messaging

Google sources share one sign-in too, through an OAuth client you register in your own Google Cloud project; the first Google source you add walks you through it (see Google's OAuth client). Microsoft sources share one sign-in, so consenting once covers Outlook Email, Outlook Calendar, and OneDrive. Omnesis supplies a public Azure app, so no Azure setup is needed; omnesis creds set outlook switches to an app registration you control. Microsoft sign-in supports personal Outlook.com, Hotmail, and Live accounts. Work and school accounts are not supported.

Discord

Discord is experimental: it appears in the source picker only when the Gateway runs with OMNESIS_EXPERIMENTAL=1, and its behavior may change between releases.

Discord hands message history to bots only — an ordinary account may not be automated, and no OAuth2 scope reads messages. So you create an application in Discord's Developer Portal, give it a bot, enable the Message Content Intent on its Bot page, and paste the bot token. Omnesis then builds the invite link itself, asking for View Channels and Read Message History and nothing else; open it and add the bot to each server you want indexed. Until the bot is in a server, the source reports that it is in none and shows the link.

• What the bot sees is what gets indexed. Only servers the bot was invited to, and only channels it may view; deny it View Channel on a channel to keep that channel out. Private threads and direct messages are never read. The guilds setting narrows the indexed servers further by id.
• One bot per server. Each Discord source indexes what its own bot sees. Two sources whose bots share a server index that server twice; give each bot its own servers, or name them in guilds.
• Your own messages. The bot is not you, so set the selfUserId setting to your Discord user id and your messages resolve to the self person. Other posters are people keyed by their Discord id.
• History and freshness. The first sync walks each channel from the beginning, or from the data cutoff when one is set. Later syncs re-read each channel's last indexed day, so an edit or a deletion there lands; an older day is never re-read, and a channel that disappears keeps its documents.
• Limits. An app visible to fewer than 10,000 users may turn the Message Content Intent on without review; past that Discord requires an intent review, and withdraws unreviewed access. Discord does not refuse a bot whose intent is off — it blanks every message body instead — so a sync that sees a long run of empty messages stops and names the intent rather than indexing nothing. The source honors Discord's rate limits and pauses for as long as Discord asks.

Maildir

Maildir indexes email that another program keeps on the collector's machine, such as mbsync, offlineimap or getmail. That program talks to the mail server; Omnesis only reads the files it writes and never connects to the server itself. That makes it a way in for an account that admits only approved mail apps, when one of them stores the mail as Maildir.

Omnesis does not run the mail tool. Schedule it yourself — cron, a launchd agent or a systemd timer — and Omnesis follows what it writes. The account the collector runs as needs read access to the folder; on macOS a folder under Documents, Desktop or an external drive also needs Full Disk Access for the collector, and a sync that cannot read it says so.

Add it with the folder that holds one account's mail — the folder, or a folder inside it such as INBOX, contains cur and new directories. Each folder you add is its own account, so two mail accounts are two sources.

Thunderbird. Thunderbird keeps each account's mail in its profile folder: Mail/Local Folders for local folders and ImapMail/<server> for an IMAP account. Maildir reads an account that uses Thunderbird's File per message (maildir) store; add the account's folder, and its folders and subfolders are read as Thunderbird keeps them. For a local account (Local Folders, or a POP account) stars and replies follow Thunderbird too. An IMAP account keeps those on the server rather than in its files, so for one its folders and deletions follow but a star added later does not; the IMAP source reads the server itself. A folder whose name is too long or has characters the disk does not allow appears under the name Thunderbird gave it on disk, which can be a hash of the original. By default Thunderbird stores an account as one mbox file per folder, which this source does not read; a sync over such a folder says so. To switch an account, in Thunderbird right-click the account, open Settings, and under Server Settings set Message Store Type to File per message (maildir). For an IMAP account, Thunderbird has local copies only of the folders it keeps for offline use.

• One document per message. A message stored in several folders — Gmail labels arrive as one folder each, plus All Mail — is one document tagged with the folders holding it. Gmail's own folders take the words its labels use in the Gmail source — SENT, STARRED, IMPORTANT — and All Mail adds no tag, so a search for starred mail finds it from either source. Messages are matched by their Message-ID; one without it is its own document in each folder.
• Changes follow the files. A new message, a folder added or removed, and a message starred or replied to update the document on the next sync. The collector watches the folder, so a sync follows the mail tool's writes. A message leaves the index when its last copy is gone — so deletions follow the mail tool, and a tool set never to remove local copies keeps them in Omnesis too.
• What it skips. Drafts, spam and trash folders, Thunderbird's templates and unsent messages, messages marked deleted, and any folder matching the Exclude folders setting, which takes folder names such as [Gmail]/All Mail; * matches within a folder name and ** across folders.
• A folder it cannot read. An unreadable folder, or a Maildir that is not there — an unmounted drive, a changed permission — deletes nothing. The sync reports the problem and removals wait until every folder reads again.
• Its index. The source keeps an index of the files it has read in the collector's configuration directory, so a large mailbox is read once. It holds folder and file names, dates, attachment names and hashes, not message text. Removing the source deletes it.
• One machine per mailbox. Each machine's Maildir is its own source. The same account mirrored on two machines and added on both is two sources with the same messages; add it on one.

WhatsApp full-history import

WhatsApp's linked-device sync only streams a companion a recent window of messages, not the full history on the phone. To recover older messages, import them once from a local phone backup. An import adds only the history actually present in the backup you provide — it is not a guaranteed universal lookback window. Run it with omnesis sources import-history <sourceId>; imported messages merge into the source by stable id, so re-running an import is safe and adds nothing already present, and a message already captured by live sync is never overwritten by a sparser imported copy.

• iPhone. Needs the encrypted backup folder Finder (or iTunes on Windows) writes — the folder containing Manifest.plist — and the password set when backup encryption was turned on.
• Android. Needs the exported msgstore.db.crypt15 file pulled from the device, and the 64-character encryption key WhatsApp showed once when end-to-end backup encryption was turned on (or the raw key file extracted alongside it). Only this single-file backup layout is supported; WhatsApp's chunked, incremental Google-Drive backup format is not.
• Limits. An imported attachment carries its filename, type, and size, but never the original file — a backup does not retain a live download session, so imported media is never downloadable the way a live-synced attachment is.
• Recovery. A wrong password or key fails the import with a clear message rather than a partial result. A backup in an unrecognized or unsupported format is refused by name instead of crashing. Cancelling stops the import and deletes its decrypted working files; messages already imported stay, and running the import again adds the rest without duplicating them.

Telegram

Telegram Messages archives your own Telegram account — signed in as you, not as a bot — into Omnesis. It reads your chats through the Telegram API with a developer app that you create, and never sends a message or marks anything as read.

Your own API app. Omnesis ships no Telegram app credential; the add flow asks for an api_id and api_hash, which stay on the collector's host.

1. Open https://my.telegram.org/apps and sign in with your phone number. The login code arrives inside the Telegram app, not by SMS.
2. Create an app with a title that does not contain the word "Telegram", such as Omnesis archive, a short name of 5 to 32 letters or digits, and the platform Desktop.
3. Paste the api_id (digits) and api_hash (32 hexadecimal characters) into the add flow.

Telegram allows one app per phone number: if you already created one, reuse its api_id and api_hash. If the form answers with a bare ERROR, turn off any VPN, proxy or ad blocker, try another browser or network, keep the title free of non-ASCII characters and of the word "Telegram", and try again later — a newly registered number is often refused for a while.

Signing in. The add flow shows a QR code; scan it in Telegram under Settings → Devices → Link Desktop Device. An account with a two-step password is asked for it once; it is used to sign in and never stored. The session appears in Telegram's device list as Omnesis. Ending it there stops the source, which then asks to be signed in again; run omnesis sources reauth telegram:<account> and scan a new code. One collector hosts an account: the session cannot be shared between machines.

The session is your whole account. The stored session is a full authorization of your Telegram account: anyone holding it can read your chats and act as you. The collector stores it encrypted, protected by its keyring.

• What it archives. Private chats, Saved Messages, basic groups, supergroups and forums, archived chats included: one document per chat per UTC day, with each message's time, sender, replies, forwards and edits. A forum message carries its topic's title, and the day lists its topics. Edits and deletions made in Telegram follow, and a day whose messages are all deleted leaves the index.
• Media. Voice notes are transcribed into the day when a transcriber model is assigned; until then the placeholder says why, as for WhatsApp. Photos and documents follow the shared attachment settings and become attachment documents of their day, with images OCR'd when an OCR model is assigned. Audio, video, round video messages, stickers and GIFs are placeholders such as [Video, 0:42] and are never downloaded. Media is downloaded a little at a time after its text is indexed, never in bulk.
• Channels are opt-in. Broadcast channels are left out until you turn on Include broadcast channels in the source's settings; turning it off again removes every channel's days and files from the index. Excluded chats takes chat IDs or @usernames to skip, and removes what was already archived from them.
• Never archived. Secret chats, which Telegram keeps only on the two devices in them; view-once photos and videos; messages under an auto-delete timer; and stories.
• History. The whole history is read in the background, most recent chats first, at a pace Telegram tolerates. The first read asks Telegram for a data export, which it limits less tightly. Telegram may hold the export until you approve it in the notification it sends to your other devices; until then history is read the slower way and the source's notice on the Sources page says so. After approving, re-sync the source to start the export at once. If Telegram asks Omnesis to slow down, the notice says when history resumes; the source's advanced settings lower the requests per sync page and raise the delay between them.
• Its archive. Messages are kept in an archive in the collector's configuration directory, encrypted with the collector's storage key, so a re-sync never reads Telegram again. Removing the source deletes the archive and ends the source's Telegram session: the collector logs that authorization out at Telegram, best effort, so it leaves your device list.

Telegram's terms. Using this source is subject to the Telegram Terms of Service and the Telegram API Terms of Service. It is your responsibility to read them before connecting the source and to follow them while you use it. Omnesis signs in as a third-party API client with the app you register; it paces its requests and backs off when Telegram asks.

Notes, tasks & meetings

Coding agents

These sources read session files written by coding agents on the collector host. Each session becomes one conversation document per local calendar day. Documents contain human prompts and completed assistant replies. Tool calls, tool results, hidden reasoning, system context, Claude Code sidechains, and Codex subagent sessions are excluded. Project, working-directory, branch, and model metadata remain available when the source records them.

The collector accepts at most 10,000 transcript files per source. It rejects a file above 1 GiB before or after decompression. It also rejects a daily document above 16 MiB. One session can contain at most 4,000 daily documents, and one source can track at most 100,000 daily documents. A rejected file does not delete its last indexed documents.

Code hosting

These sources index the repositories the token can list: the private ones it was granted, plus the public repositories you own or belong to. A token's Only select repositories choice governs its private access only — it does not narrow the public side, because a fine-grained token can read every public repository on GitHub.

What Omnesis indexes is therefore decided here, not on GitHub. The repos setting is an allow-list of owner/name entries — name them and exactly those are indexed; excludeRepos drops individual repositories whether that list is set or empty. Entries must be repositories you own, collaborate on, or whose organization you belong to: a public repository you have no connection to cannot be added this way. Both settings take effect on the next sync when changed, without re-issuing the token — set them with omnesis config set or by editing the config file.

A read-only token with Metadata, Contents, Issues, Pull requests, and Discussions is enough, and code itself is never indexed — no diffs, no file contents.

A fine-grained token belongs to exactly one resource owner, so an organization's private repositories need a token of their own. Connect it as a second account and give it a connection name — the organization's, say — because both tokens authenticate as the same person and would otherwise resolve to one account, the second replacing the first's credential. Give each account its own repos list too: both tokens can see the same public repositories, and without a list each account would index its own copy.

A thread and its replies are one document, rewritten whenever anything in it changes, so a new comment, an edited comment, or a closed issue updates the document in place rather than adding another one. References between threads become links in the graph: a #-number mention or a "Closes" line resolves to that issue, pull request, or discussion, and a merged pull request links to the commit it landed as.

Calendar & contacts

Files

For PDFs with repeated wide column gaps, extracted text preserves positioned segments in a labelled text block. Coordinates describe the source layout; they are not values or inferred table headings. This keeps otherwise empty columns distinguishable. Ordinary prose stays plain text. Existing extracted copies change only when fetched again; rebuilding a source deletes its indexed data before fetching it again.

Local Files

Local Files indexes documents on the collector's own machine — the folders you name, nothing else. There is no account and nothing to revoke. It runs on macOS and Linux collectors and reads plain text, markdown, CSV, JSON, HTML, PDF, Word, Excel, PowerPoint, OpenDocument, RTF, email (.eml), calendar (.ics) and wallet pass files.

The same file in two places is found once: a PDF or office document on disk is matched against mail attachments and cloud files by its extracted text, so a result can show where the file came from. It is a per-device source, so a result names the computer that holds the file.

• Folders you name. There are no default folders. Name each one when you add the source; each machine that joins it names its own. An Exclude setting takes glob patterns to skip inside those folders.
• What it refuses. System and configuration folders such as Library and .config, build and dependency folders, and files that look like keys or secrets are never read, even inside a chosen folder. Git working trees and Obsidian vaults are skipped whole — the Obsidian source indexes vaults — and naming one as a folder is refused at setup with the reason.
• Files it cannot read. A damaged PDF keeps the text of the pages that can be read. A file with no readable text at all — encrypted, corrupt, or a scan with OCR off — is set aside and tried again when it changes, or a day later.
• Ranked low. A working disk holds far more documents than any other source, so Local Files results rank below other sources'.
• Deletion, folder by folder. A file removed from disk leaves the index only once a scan has read its folder from end to end. A folder that could not be read — an unmounted drive, a changed permission — is left alone until it can be, and the other folders are unaffected. Remove the source to purge everything at once.

Immich

Immich indexes one Immich user's photo and video library from a server you run, version 3.0 or later. It reads text and metadata only: the capture time and place, the people Immich recognised by face and you named, album names, descriptions, favorites and the camera. Photos and videos themselves never leave the Immich server.

1. Sign in to Immich as the user whose library you want to index and open Account Settings → API Keys.
2. Create a key with the asset.read, album.read and user.read permissions.
3. Paste the key and the address you open Immich at, such as http://immich.local:2283, into the add flow. A plain http address works on a home network; the key then crosses that network unencrypted.

• One user, one source. Each source reads with one user's key, so Immich decides what it can see. A source is named by the user's email, so a gateway connects one Immich user per email; a second server whose user has the same email is refused. A key that belongs to an Immich administrator, or that is granted every permission, is accepted with a warning; the source still reads only that user's own view and never calls an administrator endpoint.
• Own photos only. Only the photos the user owns are indexed. Photos a partner shares, and photos in albums others share, are left out: they belong to the other person's library, which they can connect with their own key.
• People. Named faces become people in Omnesis. Face names belong to each Immich user, so the same person in two users' libraries, or already known from mail or messages, is a separate person until you merge them. Unnamed and hidden faces are left out.
• Albums are re-read once a day, so a photo added to an album shows the album by the next day. If the key cannot read albums, the source keeps syncing and shows a warning naming the permission to add.
• Links. Open in source opens the photo at the address the source was added with. When that is a home-network address, set the advanced Address for links setting to the address you open Immich at from elsewhere.
• Deletion. A photo moved to the trash leaves the index on the next sync. A photo deleted for good leaves after daily full reads have confirmed it is gone. Live photos are indexed once, as the still; locked photos are never indexed.
• Households. Several family members can each connect their own key to one gateway; each library is its own source, so a shared photo is indexed once, under its owner. Access levels then limit each connected agent to the sources you allow, but they are a boundary for agents, not isolation between people: whoever runs the gateway can see every source, and the people graph links faces across them.

Paperless-ngx

Paperless-ngx is experimental: it appears in the source picker only when the Gateway runs with OMNESIS_EXPERIMENTAL=1, and its behavior may change between releases.

Paperless-ngx indexes the documents a self-hosted Paperless-ngx instance has archived; it needs Paperless-ngx 2.16 or later. It reads the text Paperless-ngx already extracted, so Omnesis neither downloads the original files nor runs OCR on them. Adding the source asks for two things: the address you open Paperless-ngx at, including any path it is served under, and an API token from My Profile in Paperless-ngx. The collector must be able to reach that address.

• What the token sees is what gets indexed. A Paperless-ngx token carries every permission of its user, including editing and deleting, even though Omnesis only reads. A dedicated Paperless-ngx user with only the View permission on documents, tags, correspondents, document types, custom fields and UI settings is enough; Paperless-ngx names the user to Omnesis through the UI settings. On an instance several people share, documents owned by another user are indexed if the token can see them, but are not attributed to you. Each document becomes one document whose "Open in source" link opens it in the Paperless-ngx web UI.
• Tables. paperless_documents holds one row per document with its correspondent, document type, tags and its own date — the date on the letter, not the scan date. paperless_custom_field_values holds each custom field value with typed columns, so monetary amounts can be summed and due dates compared.
• Freshness. Each sync fetches the documents whose content, tags, correspondent, custom fields or notes changed. A bulk edit of custom fields does not mark the documents changed in Paperless-ngx, so it reaches Omnesis with the daily listing. Renaming or deleting a tag, correspondent, document type or custom field does not change the documents themselves either, so Omnesis re-reads every document once after it; adding one re-reads nothing.
• Deletion. Once a day the source lists every document id. A document that later listings keep leaving out is removed from the index. A document in the Paperless-ngx trash counts as deleted.
• Certificates and proxies. Plain http:// addresses on your own network work. For an https:// address with a certificate from your own certificate authority, start the collector with NODE_EXTRA_CA_CERTS pointing at that authority's certificate. A reverse proxy that puts a single sign-on page in front of Paperless-ngx must let requests under /api/ through with the token.
• Several instances. Each Paperless-ngx user on each instance is its own source; adding a second one leaves the first untouched. Use the same address for an instance everywhere: the same instance added under two addresses is indexed twice. Re-authenticating a source accepts only a token for the same user at the same address; to move a source to a new address, add the new address and remove the old source.

Web

Phone & device activity

Finance & fitness

Plaid

Plaid connects banks in the countries you choose; its coverage is strongest in the United States and Canada. Plaid has no shared application for third-party tools, so you create your own Plaid developer app and configure it once: its client ID, the secret for the environment you use, that environment (sandbox or production), and the countries whose banks you want offered. Sandbox is free and uses Plaid's test banks. Real banks need Production access, which Plaid grants per team and bills per connected bank. The first add walks you through the app credential, or set it directly:

Adding a bank opens a sign-in page that Plaid hosts. Omnesis shows you a link, you complete the sign-in there — including any redirect to the bank's own website — and the source appears once Plaid reports the connection. The gateway hosts no callback, so the link works from any browser on any device.

• One bank per add. A sign-in connects one bank and becomes one source, labelled with that bank's name. Add the source again to connect another bank; a bank that is already connected is refused rather than duplicated.
• What it adds. Transactions as searchable documents, plus daily balance and holdings snapshots in the plaid_transactions, plaid_balances and plaid_holdings tables. Access is read-only: it can never move money. Holdings are requested only where the bank supports them.
• History. The first sync asks for up to two years of transactions. Plaid assembles that history in the background, so a fresh connection can take a few syncs to fill in. The depth is fixed when the bank is connected.
• Re-consent. Banks require a fresh sign-in from time to time. Omnesis warns before the deadline and marks the source needs auth once the bank refuses. Signing in again reopens the same hosted page and keeps the source and its history.
• Removal disconnects the bank. Removing the source asks Plaid to disconnect the bank, which ends its per-bank billing. If Plaid cannot be reached, the source is still removed and the warning tells you to remove the connection from the Plaid dashboard yourself.
• An unfinished add is cleaned up later. If you close the sign-in page before Omnesis records the bank, Omnesis disconnects it at Plaid the next time you add a bank or the collector starts. A sign-in left for more than about half an hour, or a collector stopped between connecting a bank and storing it, can leave a connection behind; the log names it, and you remove it from the Plaid dashboard.

Omnesis itself

Managing sources

Every source-management task is available both in the portal's Sources page and under omnesis sources. Phone-hosted sources are the exception: they are turned on and off in the mobile apps, not from the portal or the CLI.

Adding a source

In the portal, open Sources and choose + Add source. In the CLI, omnesis sources add opens the same picker, or you can name the source type directly. The add flow walks you through the sign-in, API key, QR code or operating-system permission the source needs, then starts the first sync.

With more than one collector paired, the flow asks which one hosts the new source; --device <collector> answers that up front. A source that reads a folder, such as an Obsidian vault, also takes the path: omnesis sources add obsidian-notes ~/Vaults/Work --device <collector>. The path is checked on that collector, so ~ and relative paths refer to its machine, not the one running the CLI.

Adding a source from a script or an agent

Without a terminal (a script, an AI agent, ssh without a tty) the add asks nothing. Give every answer as a flag instead: --set key=value (repeatable) for each setting, or --config with the same keys as one JSON object, inline, as @file, or as - to read it from standard input, which keeps a secret such as an API key off the command line. omnesis sources describe lists the source types the connected collectors offer, and omnesis sources describe <type> lists the keys one takes (with --json, for a program).

The values are checked against what the source declares before anything is added: a key it does not take, a choice outside its options and a malformed value are refused, and a folder is checked on its collector. An answer the command line does not give is refused with the flag that supplies it. Every refusal, and a prompt cancelled on a terminal, ends with a non-zero exit status, so a script never reads a failed add as a success. One account found is added; several are refused until --account names the ones to add. A join onto a source another device hosts needs --yes, and with more than one collector able to host the source, --device is required.

A source that signs in still needs the sign-in: the add prints the URL or code and waits until it is completed in a browser. Its application credential, such as Google's OAuth client, is given the same way the first time (--set client_id=… --set client_secret=…) or set up once on a terminal with omnesis creds set <provider>; once the collector has one, an add does not replace it. A sign-in step that asks for a typed answer cannot be completed without a terminal; add that source on a terminal or from the portal.

Most sources take several accounts. Run the add flow again and sign in with a different account: two mailboxes, two Notion workspaces, or two phone numbers each become their own source, identified as <type>:<account> (for example gmail:maya@example.com) and synced, paused, and removed independently. Your browser may need to be signed out of the platform, or signed in to the account you want, for its account chooser to offer it. Sources that read one local store — the Apple sources, Things, Screen Time, Local Files, and the coding-agent sources — take one account per machine, and show as already configured once set up on that collector.

Google's OAuth client

Omnesis ships no Google OAuth client. Google requires a security assessment before one shared client may read Gmail, so each installation registers its own client, in a Google Cloud project you own, and signs in through it. The first time you add a Google source, the add flow walks you through the registration, which takes about five minutes: create a project, enable the Gmail, Google Calendar, Google Drive and People APIs, configure the consent screen for External users, publish it, then create an OAuth client of type Desktop app and paste its client ID and secret. In the portal the same wizard opens when you choose + Add source for a Google source and no client is configured. Additional Google accounts reuse the client you registered.

Publish the consent screen rather than leaving it in testing. A client in testing signs in only the accounts listed as its test users, and Google expires its sign-ins after seven days, so every Google source would ask you to sign in again each week. Publishing needs no Google verification for your own use: the first sign-in shows a “Google hasn't verified this app” warning, which you pass with Advanced → Continue.

Google won't publish the consent screen until it has an app home page and a privacy policy, but you don't need a website of your own: Google reviews these links only when an app is submitted for verification, which Omnesis doesn't need. Enter https://omnesis.dev as the home page, https://omnesis.dev/privacy as the privacy policy, and add omnesis.dev as an authorized domain, or use any public page you control. Don't submit the app for verification.

Day-to-day tasks

Each task names the portal action on the Sources page first, then the CLI command.

Sources hosted by more than one device have extra tasks — joining a device, detaching one, and re-syncing one device only. They are covered in Sources on several devices. When a source reports an error instead, start from Troubleshooting.

Accounts of one source type that write the same analytics table can leave rows from before Omnesis recorded which account wrote them. A table only one account has ever written labels them as that account's by itself, in the background, a batch at a time, whether or not the account syncs again. In a table several accounts share, syncing never waits on such a row: a deletion or a snapshot that names it leaves it in place, and the account that still holds the record labels it whenever it syncs that record again. omnesis sources legacy-rows <id> lists what remains; --claim marks those rows as the source's account, for rows no other account still syncs, and --drop deletes them. The CLI asks first; pass --yes in scripts.

Removing a source

Remove in the portal, or omnesis sources remove <id>, removes the whole source for every device that hosts it, including devices that are offline; they learn about it when they reconnect. Syncing stops immediately, and a source pushed from a phone or the browser extension stops being accepted. To keep the data instead, pause the source.

Everything the source ingested — documents, analytics rows, search-index entries, and the data derived from them — is then deleted in the background, queued behind indexing so it does not interrupt work in flight. On a large mailbox that takes several minutes. Until it finishes, the source stays in the list marked removing, and its document count falls as the purge drains. If the gateway stops partway through, it resumes the purge on the next start. You cannot add the same account again until the removing row has gone; the re-added source then syncs from scratch. Tasks and memories built on the removed documents stay, without their link to them.

People survive the removal on the strength of what remains. An email address or phone number is kept while any other connected source still names it, so removing a mailbox does not erase a contact your address book also holds. An identifier no remaining source names goes with the purge, and a person left with none goes with it.

Removal deletes data from the gateway only. It does not delete the originals on the provider or the phone, retained backups, or exported copies, and it does not promise physical secure erasure. To delete one document rather than a whole source, see deleting a document.

Sources on several devices

A source normally lives on one device: the collector or phone that syncs it. Some source types can also be hosted by several devices at once — Apple Notes on two Macs signed in to the same iCloud account, or Health Connect on two Android phones. Each device that hosts a source is a member of it, and the source type fixes how its members share the work. There are three ways:

The portal and omnesis sources name the mode with its code word, shown here under each plain name.

Adding a device to a source

Start + Add source for the source type and pick the new machine as the destination. The flow first discovers which account that machine has. If the account is already configured on another device and the type allows several members, it offers to join; a different account becomes a separate source. On a second Mac, for example, the same iCloud account joins Apple Notes, while a different iCloud account becomes a second Apple Notes source. For a type that allows one machine at a time, the flow names the current host and offers to move the source.

From the CLI, omnesis sources join <id> --device <device> adds a member, and the portal's Join a device… action does the same. Each member syncs with its own credentials, so if the source needs a sign-in, run omnesis sources reauth <provider>:<account> --device <device> for it. A join is refused when the device cannot host the type or holds a different account. Update a collector before joining it to a shared or per-device source; an out-of-date collector is not offered as a destination.

A source that reads a folder on each machine — Claude Code, Codex, and Pi sessions, or a custom Things database — asks for that path once the destination is chosen, and the path belongs to that member only. Where + Add source offers Configure <device>, use it to change one member's path without touching the others. The shorter omnesis sources join uses the source's default path.

Phones are different: each phone and tablet is paired separately, and phone sources are turned on in the app, before the operating-system permission prompt, rather than joined from the portal or the CLI. When another iPhone already sends Apple Health, the app offers Keep using the other iPhone, Use both iPhones, or Use only this iPhone. Turning on a per-device source on a second phone adds that phone's data and keeps the first phone's history. See Mobile apps.

Members, detaching, and re-syncing

omnesis sources members <id> lists a source's mode and each member with its own sync status; the portal's Sources page shows the same under the source.

omnesis sources detach <id> --device <device>, or Detach a device… in the portal, stops one member hosting the source without removing it. What happens to the data depends on the mode, as in the table above, so the CLI and the portal both say it before you confirm; pass --yes in scripts. The last member cannot be detached — pause the source to keep its data, or remove it. On a phone, turning a source off in the app asks the gateway to detach that phone, with the same outcome.

omnesis sources resync <id> --device <device> re-syncs one member of a shared or per-device source and leaves the others alone. On a per-device source, that member's data is deleted and synced again; on a shared source, only that member's sync progress starts over, because the data is shared.

If shared members disagree about whether an item was deleted — one reports it gone while another still has it — Omnesis keeps the item until every member that holds it agrees. omnesis sources counts them as deletions in dispute, the member holding them shows Keeping N items that <device> no longer has in the portal and the apps, and omnesis doctor warns. The disagreement clears once the item is deleted on the device that still holds it, or once you delete the document for good.

What a source contributes

Searchable documents. Most sources emit documents — emails, notes, messages, pages, per-day summaries — into the document store, where they are indexed for keyword and vector search and available to the agent.

Typed analytics rows. Structured sources emit typed rows into analytics tables instead of, or alongside, documents: heart-rate samples, bank transactions, browser visits, screen-time sessions. These are queryable with plain SQL — see Search. Many sources contribute both, binding a readable summary document to the underlying rows.

People-graph identities. Contacts, email correspondents, message participants, callers, and meeting attendees become identities in the people graph, so one person's activity is connected across every source they appear in.