Synchronization

nao sync

The nao sync command populates your context folder with content from configured sources.

nao sync

You can limit a sync to specific providers with --provider (or -p).

nao sync --provider databases

Supported provider values are:

databases (aliases: db, dbs, database)
repositories (aliases: repo, repos, repository)
notion

You can also target one configured connection by using provider:connection-name:

nao sync --provider databases:my-db
nao sync -p repositories:dbt_project
nao sync -p databases -p notion

Use this when you want to refresh only part of your context instead of running every configured sync provider. Sync specific schemas or tables with --select By default, if you narrow a database sync to a subset of tables, nao sync removes any previously-synced table or schema that was not part of the run. Use --select (or -s) to refresh only a selection without deleting the rest of your synced context.

# Sync a single table
nao sync --select analytics.orders

# Sync a whole schema
nao sync --select analytics

# Multiple selections and glob patterns
nao sync -s analytics.orders -s staging.dim_*

# Combine with a specific connection
nao sync -p databases:my-warehouse -s analytics.orders

Behavior:

A pattern with no dot (analytics) selects every table in that schema (analytics.*).
A pattern with a dot (analytics.orders) selects a specific table; glob wildcards are supported (staging.dim_*).
Selection is applied on top of the existing include / exclude config in nao_config.yaml: it narrows further, never widens.
When --select is passed, stale-path cleanup is skipped, so tables and schemas outside the selection are preserved.
Tables and Snowflake semantic views both respect the selection.

Use this to refresh one table on a large warehouse without re-syncing everything. Run the sync in parallel By default nao sync uses a single worker thread. Speed up large syncs with -t / --threads:

nao sync --threads 4

This overrides the threads value in nao_config.yaml (which itself defaults to 1). The value must be 1 or greater. What Gets Synced When you run nao sync, the following happens: 1. Database Schemas For each database in your nao_config.yaml:

Connect to the database
Extract schema information (tables, columns, data types)
Generate context files in databases/ folder
Create structured files for each table:
- columns.md - Column definitions and types, table description, row count, and partitioning
- preview.md - Sample data preview
- profiling.md - Data profiling information
- annotations.md - Your own notes for the agent, created once and never overwritten

Example structure after sync:

databases/
└── type=snowflake/database=analytics/
    ├── table=customers/
    │   ├── annotations.md
    │   ├── columns.md
    │   ├── preview.md
    │   └── profiling.md
    └── table=orders/
        ├── annotations.md
        ├── columns.md
        ├── preview.md
        └── profiling.md

Who owns each file Every file written during a sync starts with a frontmatter header declaring its origin, so you can tell what a re-sync will overwrite:

type: generated - written by the agent on every sync. Edits are lost on the next run.
type: manual - written once and left alone afterwards. Safe to edit.

annotations.md is the manual file: nao sync creates it per table folder with only the header, and skips it on later runs if it already exists. Everything else under databases/ is regenerated. See Databases for details. 2. Repositories For each repository in your configuration:

Clone or pull the latest code
Extract relevant files from specified paths
Index content for the agent
Store in docs/ folder

3. Indexing After syncing:

Content is indexed for fast semantic search
Embeddings are created for relevant context retrieval
Agent can access all synced information

Scheduling

GitHub Actions

Set up automated syncing with GitHub Actions to keep your context up to date. 1. Create Workflow File This workflow will regularly run nao sync on GitHub’s servers, commit any changes to your context files (like updated database schemas or docs), and push them back to your repository so your context stays in sync without manual commands. Create .github/workflows/nao-sync.yml in your repository:

name: Nao Sync

on:
  schedule:
    - cron: "0 0 */2 * *"  # every 2 days at 00:00 UTC
  workflow_dispatch:  # allows manual triggering

jobs:
  nao-sync:
    runs-on: ubuntu-latest
    permissions:
      contents: write  # needed to commit changes

    env:
      NAO_CONFIG_PATH: ./nao_config.yaml

    steps:
      - name: Checkout repository
        uses: actions/checkout@v4
        with:
          ref: ${{ github.ref }}

      - name: Set up Python
        uses: actions/setup-python@v5
        with:
          python-version: '3.11'

      - name: Install Nao CLI
        run: |
          pip install --upgrade pip
          pip install nao-core
          pip install "ibis-framework[bigquery]"  # warehouse driver for your DB

      - name: Run nao sync
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
          GOOGLE_APPLICATION_CREDENTIALS_JSON: ${{ secrets.GCP_SERVICE_ACCOUNT_KEY_JSON }}
          # Add other secrets as needed (e.g., NOTION_API_KEY, etc.)
        run: nao sync

      - name: Configure Git
        run: |
          git config --local user.email "action@github.com"
          git config --local user.name "GitHub Action"

      - name: Commit and push changes
        run: |
          git add -A
          if git diff --staged --quiet; then
            echo "No changes to commit"
          else
            git commit -m "nao sync update"
            git push origin HEAD:${{ github.ref_name }}
          fi

2. Configure Repository Secrets In your GitHub repository:

Go to Settings → Secrets and variables → Actions
Click “New repository secret”
Add secrets for all environment variables used in your nao_config.yaml:
- ANTHROPIC_API_KEY - Required for nao sync to run the agent
- GCP_SERVICE_ACCOUNT_KEY_JSON - Full JSON content of your BigQuery service account
- NOTION_API_KEY - If using Notion integration
- Any other credentials referenced in your config

Never commit secrets directly in your workflow file. Always use GitHub Secrets.

3. Customize Schedule Adjust the cron schedule to match your needs:

on:
  schedule:
    - cron: "0 0 * * *"      # Daily at midnight UTC
    - cron: "0 0 */2 * *"    # Every 2 days
    - cron: "0 0 * * 1"      # Weekly on Monday
    - cron: "0 3 * * *"      # Daily at 3 AM UTC

4. Manual Trigger You can manually trigger the sync:

Go to Actions tab in your repository
Select “Nao Sync” workflow
Click “Run workflow”

5. Monitor Sync Results

Check the Actions tab to see sync history
Review logs if sync fails
Verify changes are committed to your repository

The workflow automatically commits and pushes any changes from nao sync back to your repository, keeping your context files up to date.

Next Steps

Context Providers

Learn about configuring databases and repos

Context Engineering Playbook

Learn how to measure, iterate, and optimize your context

Start Chatting

Use your synced context with the agent

Context Principles

Understand core principles for effective context engineering

Get Started

Context Builder

Context Engineering

Chat Interface

Connectors

Self-Hosting

nao Cloud

nao Enterprise

Developers

nao sync

Scheduling

GitHub Actions

Context Providers

Context Engineering Playbook

Start Chatting

Context Principles

​nao sync

​Scheduling

​GitHub Actions

Context Providers

Context Engineering Playbook

Start Chatting

Context Principles

nao sync

Scheduling

GitHub Actions