Notion Connector
Ingest Notion pages and comments into CortexDB.
Tails Notion pages and comments and writes them to CortexDB as experiences, polling on
last_edited_time.
Two ways to run this connector
Self-hosted — pip install 'cortexdb-connectors[notion]' then cortexdb-sync sync notion.
Managed — CortexDB runs the connector as a worker. See the Connectors overview.
1. Prepare credentials
Create an internal integration at notion.so/my-integrations, copy its token, and share the pages /
databases you want ingested with the integration (Notion integrations only see explicitly shared
content).
What gets written
Each page (as a document) and comment becomes a POST /v1/experience on the resolved scope (default
org:<org>/source:notion), with an entity reference to the page.
Record keys and threads
- The
idempotency_keyisnotion:<page_id>:<last_edited_time>(a re-edit lands as a new version). - Comments link to their page via a
thread=…label, notcontext.preceded_by.
The key on the wire is derived
The key format above is this connector's internal record identity: it decides which source record an
event belongs to. The idempotency_key actually sent to CortexDB is a derived cxsrc:<56 hex> value
that also hashes the content, labels, observed time and actor, so an unchanged redelivery converges on
the same event while any edit lands as a new one, even where the key format itself is not
content-versioned. Every event also carries a source descriptor with the record's fingerprint. See
Source identity and keys.
Run it yourself
pip install 'cortexdb-connectors[notion]'
pip install cortexdb-cli && cortexdb init
export NOTION_TOKEN=secret_... # required (shared with the pages you want ingested)
cortexdb-sync --api-url http://localhost:3141 sync notion
cortexdb-sync --api-url http://localhost:3141 watch notion --interval 300Optional settings
Set these as environment variables (or the matching keys in the cortexdb-sync YAML config). Lists are comma-separated. For on/off settings, 1, true, yes or on turns the setting on and any other value turns it off.
| Setting | What it does | Default |
|---|---|---|
NOTION_DATABASES | Database IDs whose entries to sync | None |
NOTION_PAGES | Page IDs to sync, including after they are archived | None |
NOTION_LEDGER_PATH | File that records pages seen in earlier syncs | ~/.cortexdb/notion_pages_ledger.json |
Recently edited pages shared with the integration are always searched; the two lists add specific databases and pages on top.