Skip to main content

Connect Document Sources

Document sources automatically sync files from external platforms into your project's document library. Instead of uploading files manually, you connect a source -- a GitHub repository, a Google Drive folder, or a local directory -- and ORQO keeps your documents in sync.

When Long-Term Memory is enabled on the project, synced files are automatically classified into the knowledge graph. Your graph grows every time a source syncs new or updated content.

Prerequisites​

Source Types​

Document sources come in two kinds:

App-Backed Sources​

Connect to external platforms through installed Apps. The App's adapter handles authentication, file enumeration, and content fetching.

PlatformResource Path FormatExample
GitHubowner/repo or owner/repo:subpath/octocat/hello-world:docs/
Google DriveGoogle Drive folder ID1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgVE2upms

Runtime-Backed Sources​

Sync files from any directory accessible through a runtime -- a local workspace (via the ORQO Desktop App) or a remote server (via SSH).

Runtime TypeResource Path FormatExample
Desktop AppAbsolute path on local machine/Users/alice/Research/papers
SSHAbsolute path on remote server/var/data/reports

Runtime-backed sources use shell commands (find, md5sum, cat) to enumerate and fetch files. No adapter or App is required -- the runtime itself provides file access.

Steps​

1. Open the Documents page​

Navigate to your project and click Documents. At the top of the page, above the folder tree, you'll see the External Sources section.

2. Click "Connect Source"​

Click the + Connect Source button to expand the connection form.

3. Choose the source type​

Select whether you are connecting an App (GitHub, Google Drive) or a Runtime (Desktop App, SSH).

For App-backed sources, select the App from the dropdown. Only verified Apps with adapter URLs are listed.

For Runtime-backed sources, select the runtime from the dropdown. Only active (running or stopped) runtimes are listed.

4. Configure the source​

Fill in the connection details:

FieldRequiredDescription
NameYesDisplay name for this source (e.g., "Product Docs", "Research Papers")
Resource PathYesWhere to find the files -- depends on source type (see tables above)
Target FolderNoDestination folder in your document library. Files are organized under this path.
Sync IntervalYesHow often to check for changes (15 minutes to 24 hours, default: 1 hour)
File FilterNoGlob pattern to sync only specific files (e.g., *.md, *.txt,*.pdf)
tip

The target folder preserves the source's directory structure underneath it. For example, if your GitHub repo has docs/guide.md and your target folder is github/my-repo, the document appears at github/my-repo/docs/guide.md in your library.

5. Save and sync​

Click Create. ORQO immediately triggers the first sync. Depending on the number of files, this may take a few seconds to a few minutes.

You can see the sync progress on the source card:

StatusMeaning
ActiveSource is healthy and syncing on schedule
PausedSync is paused -- click Resume to restart
ErrorLast sync failed -- hover the card for the error message

6. Monitor synced documents​

Synced files appear in your document library under the target folder (or at the root if no target folder was set). Each document shows its origin -- the source name and the file path within the external resource.

If Long-Term Memory is enabled, synced documents go through the classification pipeline automatically. Watch the classification status badges to track progress.

How Sync Works​

Document sources use a poll-based sync strategy:

  1. On schedule -- Every 5 minutes, a sweeper job checks which sources are due for sync (based on their sync interval and last sync time).
  2. File enumeration -- The source lists all files at the resource path, collecting a fingerprint (hash) for each file.
  3. Change detection -- Fingerprints are compared with previously synced documents. Only new and modified files are fetched.
  4. Fetch and upload -- Changed files are downloaded and stored in ORQO's document storage.
  5. Classification -- If the project has Long-Term Memory enabled and the file type is classifiable (text, Markdown, PDF, etc.), the document is sent through the classification pipeline.

Deleted files at the source are logged but not automatically removed from your library. Documents and their knowledge graph entries are preserved until you manually delete them.

Managing Sources​

Pause and Resume​

Click a source card to open the detail drawer, then click Pause to stop syncing. Resume clears any error state and triggers an immediate sync.

Manual Sync​

Click Sync Now in the source drawer to trigger an immediate sync outside the regular schedule. This is useful after you know files have changed and don't want to wait for the next interval.

Edit Settings​

Update the name, target folder, sync interval, or file filter through the source drawer. The resource path cannot be changed after creation -- delete and recreate the source if you need a different path.

Delete a Source​

Deleting a source stops all future syncing. Documents already imported from the source remain in your library -- they are not deleted. Their knowledge graph entries are also preserved.

Example: Sync a GitHub Repository​

  1. Install and verify the GitHub App with a Personal Access Token.
  2. Navigate to your project's Documents page.
  3. Click + Connect Source, select GitHub as the App.
  4. Set the resource path to your-org/your-repo:docs/ to sync only the docs/ directory.
  5. Set the file filter to *.md to sync only Markdown files.
  6. Set the target folder to github/your-repo.
  7. Click Create.

Files sync immediately and then on the configured interval. New Markdown files committed to the repo's docs/ directory are automatically imported and classified.

Example: Sync a Local Directory via the ORQO Desktop App​

  1. Set up the ORQO Desktop App and add a workspace (e.g., ~/Research/papers).
  2. Navigate to your project's Documents page.
  3. Click + Connect Source, select the Desktop App runtime for your workspace.
  4. Set the resource path to the directory you want to sync (e.g., /Users/alice/Research/papers).
  5. Set the file filter to *.md,*.txt,*.pdf if you only want specific file types.
  6. Click Create.

The app reads files from your local directory, uploads them to ORQO's storage, and classifies them into the knowledge graph. When you add or modify files locally, the next sync picks up the changes.

What's Next​

Learn More​