Skip to main content

Knowledge Base Sync Guide

✅ Automatic Sync Enabled​

KB entries are automatically synced to Vertex AI Search - no manual sync needed!

When Sync Happens​

  • ✅ On Server Startup - Syncs automatically when server starts
  • ✅ After Adding KB Entry - Syncs automatically after creation
  • ✅ After Updating KB Entry - Syncs automatically after update
  • ✅ After Deleting KB Entry - Syncs automatically after deletion

Manual Sync (Only if Needed)​

Run npm run sync-kb-to-vertex only in these situations:

  1. Troubleshooting - If automatic sync fails
  2. Bulk Operations - After importing many entries at once
  3. Initial Verification - To verify sync is working

Scenarios​

1. Initial Setup (Required)​

When: First time using Vertex AI Search integration

Why: Vertex AI Search needs to be populated with KB entries from Firestore

Command:

cd toto-ai-hub
npm run sync-kb-to-vertex

Result: All KB entries are indexed in Vertex AI Search

2. After Adding New KB Entry (Recommended)​

When: You add a new KB entry via toto-bo UI (/dashboard/ai-hub/knowledge)

Why: New entries need to be available in Vertex AI Search fallback

Example:

  • You add a new entry: "How to verify donations"
  • Run sync to make it searchable in Vertex AI Search

Command:

npm run sync-kb-to-vertex

Note: RAGService will pick up new entries automatically (loads from Firestore), but Vertex AI Search needs manual sync

3. After Updating KB Entry (Recommended)​

When: You modify an existing KB entry via toto-bo UI

Why: Updated content needs to be reflected in Vertex AI Search

Example:

  • You update "Donation Process" entry with new information
  • Run sync to update Vertex AI Search

Command:

npm run sync-kb-to-vertex

4. After Deleting KB Entry (Recommended)​

When: You delete a KB entry via toto-bo UI

Why: Deleted entries should be removed from Vertex AI Search

Command:

npm run sync-kb-to-vertex

Note: The sync script re-indexes all entries, so deleted ones will be removed

5. Periodic Maintenance (Optional)​

When: Weekly or monthly, or after bulk changes

Why: Ensures Vertex AI Search is in sync with Firestore

Command:

npm run sync-kb-to-vertex

How It Works​

KB entries are stored in Firestore (shared toto-bo project) and automatically synced to Vertex AI Search for fallback search when RAGService confidence is low.

Troubleshooting​

"No Knowledge Base entries found"​

  • Check that KB entries exist in Firestore (toto-bo project)
  • Verify TOTO_BO_SERVICE_ACCOUNT_KEY is set
  • Check Firestore collection: knowledge_base

"Sync completed but agents don't see new entries"​

  • RAGService loads on startup - restart server
  • Vertex AI Search is fallback - check if RAGService confidence is high enough
  • Verify entries are actually in Firestore

"Sync is slow"​

  • Normal for large KB (100+ entries)
  • Sync re-indexes all entries (not incremental)