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. Two sources carry an experimental tag: Plaid and Local Files need more testing, and a collector offers them only when it runs with OMNESIS_EXPERIMENTAL=1. Experimental sources covers turning them on.

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.

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

Web

Phone & device activity

Finance & fitness

Omnesis itself

Experimental sources

A collector offers experimental sources only when it runs with OMNESIS_EXPERIMENTAL=1. The collector reads the flag from its own environment, so set it on each collector that should offer them; a flag on the gateway alone does not add them to + Add source. With the flag off, the picker leaves them out and a collector skips any it already hosts, saying why in its log.

For a collector installed as a service, add the variable to its unit. Re-running service install rewrites the unit from the flags you pass, so repeat the ones it was installed with, such as its keyring flags, then restart it:

Plaid (experimental)

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.

Local Files (experimental)

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.
• Ranked low. A working disk holds far more documents than any other source, so Local Files results rank below other sources' until its ranking is proven.
• 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.

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.

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.

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.

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 anything 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.

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.