OAuth Connectors Guide

Complete guide to connecting external platforms to Kybernesis.

Overview
Google Drive Setup
Notion Setup
How Syncing Works
Sync Frequency
Managing Connectors
Troubleshooting
Security and Privacy

Overview

Connectors allow Kybernesis to automatically sync content from external platforms into your memory collection.

Supported Platforms

Platform	Content Types	Status
Google Drive	Documents, Sheets, Presentations, PDFs	Active
Notion	Pages, Databases, Workspaces	Active

Benefits of Connectors

Automatic synchronization:

No manual uploads needed
Content stays up-to-date
Changes detected and synced

Centralized search:

Search across all platforms
Unified knowledge base
Hybrid retrieval across sources

Preserved context:

Source metadata maintained
Original links preserved
File structure retained

How Connectors Work

terminal

1. OAuth Authentication
   └─ Authorize Kybernesis to access your account

2. Initial Sync
   └─ Fetch all accessible documents/pages

3. Incremental Updates
   └─ Detect and sync changes periodically

4. Memory Creation
   └─ Each document becomes a memory with chunks

5. Ongoing Sync
   └─ Automatic updates every 60 minutes

Google Drive Setup

Connect your Google Drive to sync documents, sheets, and presentations.

Prerequisites

Google account
Access to Google Drive
Documents you want to sync

Step-by-Step Setup

1. Open Connectors Panel

In Kybernesis UI:

terminal

Cmd/Ctrl + C

Or click the Connectors button in the toolbar.

2. Start Google Drive Connection

terminal

┌──────────────────────────────────────┐
│ Connectors                      [X]  │
├──────────────────────────────────────┤
│ Google Drive                         │
│ Status: Not Connected                │
│ [Connect to Google Drive]            │
└──────────────────────────────────────┘

Click [Connect to Google Drive].

3. OAuth Authorization

You'll be redirected to Google's OAuth consent screen:

terminal

┌────────────────────────────────────────┐
│ Google Account Selection               │
│                                        │
│ Choose an account to continue to       │
│ Kybernesis                             │
│                                        │
│ ○ alice@example.com                    │
│ ○ work@company.com                     │
│ ○ Use another account                  │
└────────────────────────────────────────┘

Select the Google account you want to connect.

4. Grant Permissions

Google will ask for permission to access your Drive:

terminal

┌────────────────────────────────────────┐
│ Kybernesis wants to access your        │
│ Google Account                         │
│                                        │
│ This will allow Kybernesis to:         │
│                                        │
│ ☑ See and download all your Google    │
│   Drive files                          │
│                                        │
│ Make sure you trust Kybernesis         │
│                                        │
│        [Cancel]    [Allow]             │
└────────────────────────────────────────┘

Click [Allow] to grant access.

Permissions requested:

Read access to Google Drive files
Metadata access (file names, types, dates)
Download access to file content

What Kybernesis CANNOT do:

❌ Modify or delete your files
❌ Share your files with others
❌ Create new files in your Drive
❌ Access files not shared with the authorized account

5. Callback and Confirmation

You'll be redirected back to Kybernesis:

terminal

┌────────────────────────────────────────┐
│ Google Drive Connected Successfully!   │
│                                        │
│ Account: alice@example.com             │
│ Initial sync starting...               │
│                                        │
│           [Continue]                   │
└────────────────────────────────────────┘

Click [Continue] to return to the topology.

6. Initial Sync

The first sync begins automatically:

terminal

┌──────────────────────────────────────┐
│ Google Drive                         │
│ Status: Syncing... ⟳                 │
│ Progress: 12 / 47 documents          │
└──────────────────────────────────────┘

Initial sync process:

Fetches list of all Drive files
Filters supported file types
Downloads file content
Creates memory items
Generates chunks and embeddings
Updates connector status

Time estimate:

Small Drive (< 50 files): 2-5 minutes
Medium Drive (50-200 files): 5-15 minutes
Large Drive (200+ files): 15-60 minutes

Supported File Types

Type	Extensions	Notes
Google Docs	.gdoc	Converted to text
Google Sheets	.gsheet	Converted to CSV/text
Google Slides	.gslides	Text content extracted
PDFs	.pdf	Text extracted
Text Files	.txt, .md	Direct import
Word Documents	.doc, .docx	Converted to text

Not supported:

Images (JPEG, PNG, etc.)
Videos (MP4, MOV, etc.)
Audio files (MP3, WAV, etc.)
Zip archives
Executable files

What Gets Synced

For each file:

File name → Memory title
File content → Memory chunks
File type → Auto tag
Last modified date → Memory timestamp
Google Drive link → Source reference

Metadata preserved:

source: "connector"
sourceRef: "google-drive:file-id"
metadata.connectorType: "google-drive"
metadata.mimeType: "application/pdf"
metadata.driveId: "abc123..."

Access Scope

Kybernesis syncs:

Files owned by you
Files shared with you (if read access granted)
Files in shared drives (if you have access)

Kybernesis does NOT sync:

Files you don't have access to
Trashed files
Files in restricted folders

Notion Setup

Connect your Notion workspace to sync pages and databases.

Prerequisites

Notion account
Workspace access
Pages you want to sync

Step-by-Step Setup

1. Open Connectors Panel

terminal

Cmd/Ctrl + C

2. Start Notion Connection

terminal

┌──────────────────────────────────────┐
│ Connectors                      [X]  │
├──────────────────────────────────────┤
│ Notion                               │
│ Status: Not Connected                │
│ [Connect to Notion]                  │
└──────────────────────────────────────┘

Click [Connect to Notion].

3. OAuth Authorization

Redirected to Notion's OAuth page:

terminal

┌────────────────────────────────────────┐
│ Select pages that Kybernesis can access│
│                                        │
│ Workspace: Personal                    │
│                                        │
│ ☑ Project Roadmap                     │
│ ☑ Meeting Notes                       │
│ ☑ Research Database                   │
│ ☐ Private Journal (not shared)        │
│                                        │
│ Select all pages                       │
│                                        │
│        [Cancel]    [Allow Access]      │
└────────────────────────────────────────┘

Select the pages and databases you want to sync.

Important: You must explicitly select each page. Kybernesis can only access pages you grant permission to.

4. Grant Integration Access

terminal

┌────────────────────────────────────────┐
│ Kybernesis Integration                 │
│                                        │
│ This integration will be able to:      │
│                                        │
│ ☑ Read content from selected pages    │
│ ☑ Read user information                │
│                                        │
│ It will NOT be able to:                │
│ ☐ Edit or delete pages                │
│ ☐ Create new pages                    │
│ ☐ Access pages not selected           │
│                                        │
│        [Deny]    [Allow Access]        │
└────────────────────────────────────────┘

Click [Allow Access].

5. Callback and Confirmation

terminal

┌────────────────────────────────────────┐
│ Notion Connected Successfully!         │
│                                        │
│ Workspace: Personal                    │
│ Pages: 12 selected                     │
│ Initial sync starting...               │
│                                        │
│           [Continue]                   │
└────────────────────────────────────────┘

6. Initial Sync

terminal

┌──────────────────────────────────────┐
│ Notion                               │
│ Status: Syncing... ⟳                 │
│ Progress: 5 / 12 pages               │
└──────────────────────────────────────┘

Sync process:

Fetches selected pages
Retrieves page content (blocks)
Converts Notion blocks to text
Creates memory items
Generates embeddings
Updates connector status

Supported Content Types

Type	Description	Synced
Pages	Standard Notion pages	✓ Yes
Databases	Tables, boards, galleries	✓ Yes (as rows)
Sub-pages	Nested pages	✓ Yes
Inline databases	Embedded tables	✓ Yes
Text blocks	Paragraphs, headings	✓ Yes
Code blocks	Code snippets	✓ Yes
Lists	Bulleted, numbered, toggle	✓ Yes
Embeds	External content	✗ No
Files	Uploaded files	✗ No
Images	Inline images	✗ No

What Gets Synced

For each page:

Page title → Memory title
Page content → Memory chunks (blocks converted to text)
Page type → Auto tag
Last edited time → Memory timestamp
Notion page link → Source reference

Metadata preserved:

source: "connector"
sourceRef: "notion:page-id"
metadata.connectorType: "notion"
metadata.workspaceId: "abc123..."
metadata.pageUrl: "https://notion.so/..."

Access Scope

Kybernesis syncs:

Pages you explicitly selected during OAuth
Sub-pages within selected pages
Database rows (if database selected)

Kybernesis does NOT sync:

Pages not selected during OAuth
Pages in other workspaces
Private pages you don't own

Re-selecting Pages

To add more pages after initial setup:

terminal

1. Open Connectors panel (Cmd+C)
2. Click [Disconnect] on Notion
3. Click [Connect to Notion] again
4. Select additional pages
5. Re-authorize

How Syncing Works

Sync Mechanics

Cursor-Based Pagination

Connectors use cursor-based pagination to track sync progress:

terminal

Initial sync:
  cursor = null (start from beginning)
  ↓
Fetch batch of items
  ↓
Process and store
  ↓
Update cursor to last item ID
  ↓
Repeat until all items fetched

Cursor stored in database:

terminal

{
  connectorId: "conn_abc123",
  cursor: "page-token-xyz789",
  lastSyncedAt: 1698765555000
}

Incremental Updates

After initial sync, only changes are synced:

terminal

Incremental sync:
  cursor = last sync position
  ↓
Fetch items modified since cursor
  ↓
Process changes (new, updated)
  ↓
Update cursor
  ↓
Mark sync complete

Change detection:

Google Drive: Uses modifiedTime field
Notion: Uses last_edited_time field

Sync Pipeline

terminal

1. Scheduler triggers sync job
   └─ Every 60 minutes

2. Queue worker receives job
   └─ Job type: "connector_sync"

3. Fetch items from platform
   └─ OAuth credentials used for authentication

4. Download content
   └─ Convert to text format

5. Create/update memories
   └─ Store in Convex
   └─ Generate chunks
   └─ Create embeddings
   └─ Store in Chroma

6. Update connector status
   └─ lastSyncedAt timestamp
   └─ cursor position
   └─ item count

Content Processing

For each synced item:

terminal

1. Extract text content
   └─ Convert proprietary formats (gdoc, notion blocks)

2. Create memory item
   └─ Title, source, metadata

3. Chunk content
   └─ Up to 1200 char chunks with 120 char overlap

4. Generate embeddings
   └─ OpenAI text-embedding-3-small

5. Store chunks
   └─ Convex (metadata) + Chroma (vectors)

6. Auto-tag
   └─ Add connector type, file type tags

7. Link to connector
   └─ sourceRef for traceability

Sync Frequency

Automatic Sync Schedule

Default schedule:

Every 60 minutes via Durable Object scheduler
Syncs all connected connectors
Incremental updates only

Sync timing:

terminal

00:00 → Sync
01:00 → Sync
02:00 → Sync
...

Manual Sync

Trigger sync on-demand:

terminal

1. Open Connectors panel (Cmd+C)
2. Find connector (e.g., Google Drive)
3. Click [Sync Now]
4. Wait for completion

Use manual sync when:

You just added new files
You want immediate updates
Automatic sync failed

Sync Status

Possible states:

Status	Description	Action Available
Connected	Ready to sync	[Sync Now]
Syncing	Currently syncing	(Wait)
Error	Sync failed	[Retry]
Disconnected	Not authorized	[Reconnect]

Rate Limits

API rate limits:

Google Drive: 1000 requests/100 seconds
Notion: 3 requests/second

Kybernesis respects these limits by:

Batching requests
Throttling sync speed
Retrying on 429 errors

Managing Connectors

Viewing Connector Status

Connectors panel shows:

terminal

┌──────────────────────────────────────┐
│ Google Drive                         │
│ Status: Connected                    │
│ Last Sync: 2024-10-24 14:30          │
│ Items: 47 documents                  │
│ [Sync Now] [Disconnect]              │
└──────────────────────────────────────┘

Status fields:

Status - Connection state
Last Sync - Timestamp of last successful sync
Items - Number of synced memories
Actions - Available operations

Syncing a Connector

Click [Sync Now]:

terminal

Status: Syncing... ⟳
Progress: 12 / 47 documents processed

Sync completes:

terminal

Status: Connected
Last Sync: 2024-10-24 15:45

Disconnecting a Connector

Steps:

terminal

1. Click [Disconnect]
2. Confirmation dialog appears
3. Confirm disconnection

Confirmation dialog:

terminal

┌────────────────────────────────────────┐
│ Disconnect Google Drive?               │
│                                        │
│ This will:                             │
│ ☑ Revoke access to your Google Drive  │
│ ☑ Stop automatic syncing               │
│                                        │
│ Synced memories will NOT be deleted.   │
│ You can reconnect anytime.             │
│                                        │
│        [Cancel]    [Disconnect]        │
└────────────────────────────────────────┘

After disconnection:

OAuth credentials deleted
Sync stops
Existing memories remain
Can reconnect anytime

Reconnecting a Connector

To reconnect:

terminal

1. Open Connectors panel
2. Click [Connect to Google Drive]
3. Follow OAuth flow again
4. Grant permissions
5. Initial sync resumes

Reconnection behavior:

Duplicate prevention: Existing memories not re-created
Incremental sync: Only new/changed items synced
Cursor preserved: Picks up from last position (if recent)

Troubleshooting

Issue: OAuth Authorization Failed

Symptoms:

"Authorization failed" error
Redirected back without success message

Possible causes:

Permission denied during OAuth
Invalid redirect URI configuration
Expired state token
Network error

Solutions:

✓ Try again:

terminal

1. Click [Connect] again
2. Ensure you click [Allow] on OAuth screen
3. Check browser console for errors

✓ Check browser settings:

terminal

- Ensure cookies enabled
- Disable ad blockers temporarily
- Try incognito/private mode

✓ Verify account access:

terminal

- Ensure you have access to the workspace
- Check if account is active
- Verify email confirmation (for Notion)

Issue: Sync Failing Repeatedly

Symptoms:

Status shows "Error"
Last sync timestamp not updating
Error message in connector panel

Possible causes:

OAuth token expired
Permissions revoked
API rate limit exceeded
Network connectivity issues
File access denied

Solutions:

✓ Refresh credentials:

terminal

1. Disconnect connector
2. Reconnect and re-authorize
3. Grant all requested permissions

✓ Check error message:

terminal

Status: Error
Message: "Invalid credentials"
→ Indicates token expired, reconnect needed

Message: "Rate limit exceeded"
→ Wait 15 minutes, retry

✓ Verify file access:

terminal

- Ensure files still exist
- Check if files moved to trash
- Verify sharing permissions (for shared files)

Issue: Files Not Syncing

Symptoms:

Some files missing from memories
Item count lower than expected

Possible causes:

File type not supported
File access denied
File size too large
Sync in progress (partial)

Solutions:

✓ Check file type:

terminal

Supported: .gdoc, .gsheet, .pdf, .txt, .md, .doc, .docx
Not supported: .jpg, .png, .mp4, .zip

→ Unsupported files are skipped

✓ Verify access:

terminal

- Open file in Google Drive/Notion
- Ensure you have read access
- Check if file is in trash

✓ Check file size:

terminal

Files > 10MB may be skipped
Check connector logs for size errors

✓ Wait for sync completion:

terminal

Initial sync may take 15-60 minutes
Check "Progress: X / Y" indicator

Issue: Duplicate Memories

Symptoms:

Same file appears multiple times
Multiple memories with same title

Possible causes:

Reconnected without cursor
File moved/renamed in source
Sync interrupted and retried

Solutions:

✓ Delete duplicates manually:

terminal

1. Open Memory List (Cmd+L)
2. Sort by title
3. Identify duplicates
4. Delete redundant memories

✓ Prevent future duplicates:

terminal

- Avoid disconnecting/reconnecting frequently
- Let syncs complete fully
- Use manual sync sparingly

Issue: Slow Sync Performance

Symptoms:

Sync takes very long
Progress bar stuck
Timeout errors

Possible causes:

Large number of files
Large file sizes
Slow network connection
API rate limits

Solutions:

✓ Be patient:

terminal

Large syncs (200+ files) can take 30-60 minutes
This is normal for initial sync

✓ Check progress:

terminal

Progress: 45 / 200 documents
→ Still running, wait for completion

✓ Retry if stuck:

terminal

If progress doesn't change for 10+ minutes:
1. Refresh page
2. Check connector status
3. Click [Sync Now] again

Issue: Permission Errors

Symptoms:

"Access denied" errors
"Insufficient permissions" message

Possible causes:

OAuth permissions revoked
Workspace access changed
File sharing settings changed

Solutions:

✓ Re-authorize:

terminal

1. Disconnect connector
2. Reconnect
3. Grant all requested permissions

✓ Check workspace access:

terminal

- Verify you're still a member
- Check if admin removed access
- Ensure workspace subscription active

✓ Verify file permissions:

terminal

- Open file directly in source platform
- Ensure you still have read access
- Check if owner changed sharing settings

Security and Privacy

Authentication

OAuth 2.0 standard:

Secure authorization flow
No password storage
Token-based access
Industry-standard encryption

Stored Credentials

What Kybernesis stores:

Access token (encrypted)
Refresh token (encrypted, if applicable)
Token expiration time
Connector metadata

What Kybernesis does NOT store:

Your password
Full file contents permanently
Personal identifiable info beyond what you grant

Data Access

Kybernesis can:

Read files you grant access to
Download file content for indexing
Store text content in memory database
Generate embeddings from content

Kybernesis cannot:

Modify or delete your files
Share your files with others
Access files you haven't granted permission to
Access accounts you haven't connected

Revoking Access

To revoke Kybernesis access:

Google Drive:

terminal

1. Visit https://myaccount.google.com/permissions
2. Find "Kybernesis" in connected apps
3. Click [Remove Access]
4. Confirm revocation

Notion:

terminal

1. Open Notion Settings
2. Go to "My connections"
3. Find "Kybernesis"
4. Click [Disconnect]

In Kybernesis:

terminal

1. Open Connectors panel (Cmd+C)
2. Click [Disconnect]
3. Confirm disconnection

After revocation:

Kybernesis can no longer access your files
Existing memories remain in Kybernesis
Sync stops immediately
Credentials deleted from database

Data Retention

Synced memories:

Remain in Kybernesis after disconnection
Not automatically deleted
You can delete manually via UI

To delete all connector memories:

terminal

1. Open Memory List (Cmd+L)
2. Filter by source: "connector"
3. Select all
4. Bulk delete (if available) or delete individually

Best Practices

Security tips:

terminal

✓ Only connect accounts you own
✓ Review OAuth permissions carefully
✓ Disconnect unused connectors
✓ Rotate credentials periodically
✓ Monitor sync activity
✓ Revoke access if suspicious activity

Privacy tips:

terminal

✓ Don't grant access to personal/sensitive files
✓ Use separate Google/Notion accounts if needed
✓ Review synced content regularly
✓ Delete memories containing sensitive data
✓ Export data before disconnecting (if backup needed)

Next Steps

UI Guide - Learn to use the connectors panel
Core Concepts - Understand memory sources
Retrieval Guide - Search across connector-synced content
Memory System - How connector content is processed

OAuth Connectors Guide

Table of Contents

Overview

Supported Platforms

Benefits of Connectors

How Connectors Work

Google Drive Setup

Prerequisites

Step-by-Step Setup

1. Open Connectors Panel

2. Start Google Drive Connection

3. OAuth Authorization

4. Grant Permissions

5. Callback and Confirmation

6. Initial Sync

Supported File Types

What Gets Synced

Access Scope

Notion Setup

Prerequisites

Step-by-Step Setup

1. Open Connectors Panel

2. Start Notion Connection

3. OAuth Authorization

4. Grant Integration Access

5. Callback and Confirmation

6. Initial Sync

Supported Content Types

What Gets Synced

Access Scope

Re-selecting Pages

How Syncing Works

Sync Mechanics

Cursor-Based Pagination

Incremental Updates

Sync Pipeline

Content Processing

Sync Frequency

Automatic Sync Schedule

Manual Sync

Sync Status

Rate Limits

Managing Connectors

Viewing Connector Status

Syncing a Connector

Disconnecting a Connector

Reconnecting a Connector

Troubleshooting

Issue: OAuth Authorization Failed

Issue: Sync Failing Repeatedly

Issue: Files Not Syncing

Issue: Duplicate Memories

Issue: Slow Sync Performance

Issue: Permission Errors

Security and Privacy

Authentication

Stored Credentials

Data Access

Revoking Access

Data Retention

Best Practices

Next Steps