Knowledge Sync

Overview

The asiyst knowledge sync command scans local directories, detects changed or newly added Markdown, MDX, and PDF documentation files, computes delta hashes, and pushes vector updates to the Asiyst Knowledge Engine.

How Knowledge Sync Operates

[Local ./docs folder] ──▶ [Compute SHA-256 Hashes]
                                     │
                                     ▼ (Diff against remote hashes)
[Asiyst Cloud Index] ◀── [Upload & Embed Changed Files Only]

• Delta Uploads: Only modified files are uploaded and re-embedded, saving compute time and conserving API limits.

• Automatic Pruning: If a local file is deleted, passing the --prune flag automatically removes its corresponding vectors from the remote index.

Command Syntax & Flags

asiyst knowledge sync <path> [options]
Options:
  --collection <id>   Target collection ID (default: project default)
  --prune             Remove remote documents that no longer exist locally
  --dry-run           Show what would be uploaded/deleted without making changes
  --include <pattern> Glob pattern to include (e.g. "**/*.md")
  --force             Re-embed all files regardless of hash match

Ignoring Files via .asiystignore

Create an .asiystignore file in your repository root to exclude drafts or internal files:

# Ignore draft articles
docs/drafts/**
docs/internal-sops/**
# Ignore test files
**/*.spec.md
**/*.test.ts

GitHub Actions Automation Recipe

Keep your production assistant's knowledge base continuously updated on every git push to main:

name: Sync Documentation Knowledge
on:
  push:
    branches: [main]
    paths:
      - "docs/**"
      - "content/**"
jobs:
  sync-knowledge:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Install Asiyst CLI
        run: npm install -g @asiyst/cli
      - name: Sync Docs to Knowledge Base
        run: asiyst knowledge sync ./docs --prune --project $ASIYST_PROJECT_ID
        env:
          ASIYST_PROJECT_ID: ${{ secrets.ASIYST_PROJECT_ID }}
          ASIYST_API_TOKEN: ${{ secrets.ASIYST_API_TOKEN }}