Rebuilding the Graph
When and how to rebuild the Graphify knowledge graph after code changes branch merges, or configuration updates.
On this page
Rebuilding the Graph
When and how to refresh your Graphify knowledge graph to stay current with your codebase.
🔄 When to Rebuild
✅ Rebuild Triggers
| Trigger | Reason | Command |
|---|---|---|
| 5+ files changed | Significant code changes since last build | graphify update . --code-only |
| Branch merged / PR merged | New code from other branches | graphify update . --code-only |
| Switched branches | Different codebase state | graphify update . --code-only |
| Graph >4 hours old | Stale during active development | graphify update . --code-only |
| API key added/changed | Enable/disable full graph | graphify update . |
| Deleted file referenced | Graph has stale references | graphify update . --code-only |
| Major refactor | Structural changes | graphify update . --code-only |
❌ Don’t Rebuild When
- 1-2 small edits (query existing graph)
- Graph <1 hour old, no code changes
- Only documentation typos fixed (code-only unaffected)
- Just exploring — query current graph
🛠️ Rebuild Commands
Code-Only Rebuild (Fast, No API Key)
1# 1. Signal activity (REQUIRED)
2mkdir -p graphify-out && touch graphify-out/.graphify-activity
3
4# 2. Rebuild
5graphify update . --code-only
6
7# Typical time: 30-60 seconds
8# Output: Updated graphify-out/graph.json
Full Graph Rebuild (Needs API Key)
1# 1. Ensure API key is set
2export GEMINI_API_KEY="your-key"
3
4# 2. Signal activity
5mkdir -p graphify-out && touch graphify-out/.graphify-activity
6
7# 3. Rebuild
8graphify update .
9
10# Typical time: 60-120 seconds
11# Output: Updated graphify-out/graph.json (larger, includes docs)
First Build (No graphify-out/)
1# Same as rebuild but initial
2mkdir -p graphify-out && touch graphify-out/.graphify-activity
3graphify . --code-only # or without flag for full
⚡ Quick Rebuild Alias
1# Add to ~/.bashrc
2alias graphify-rebuild='mkdir -p graphify-out && touch graphify-out/.graphify-activity && graphify update . --code-only'
3alias graphify-rebuild-full='mkdir -p graphify-out && touch graphify-out/.graphify-activity && graphify update .'
4
5# Usage
6graphify-rebuild
7graphify-rebuild-full
🔍 Verification After Rebuild
1# 1. Check graph size
2ls -lh graphify-out/graph.json
3# Should be > 500 KB (3.3 MB in this project)
4
5# 2. Test query
6mkdir -p graphify-out && touch graphify-out/.graphify-activity
7graphify query "project overview"
8# Should return fresh architectural summary
9
10# 3. Check timestamp
11stat graphify-out/graph.json
12# Modified time should be recent
🤖 CI/CD Integration
GitHub Actions: Auto-Rebuild on Main
1# .github/workflows/graphify-rebuild.yml
2name: Rebuild Graphify Graph
3on:
4 push:
5 branches: [main]
6 paths:
7 - 'scripts/**'
8 - 'tasks/**'
9 - '.github/skills/**'
10 - 'content/docs/**'
11
12jobs:
13 rebuild:
14 runs-on: ubuntu-latest
15 steps:
16 - uses: actions/checkout@v4
17 - name: Install Graphify
18 run: |
19 curl -LsSf https://astral.sh/uv/install.sh | sh
20 echo "$HOME/.local/bin" >> $GITHUB_PATH
21 uv tool install graphifyy
22 graphify install
23 - name: Build code-only graph
24 run: |
25 mkdir -p graphify-out
26 touch graphify-out/.graphify-activity
27 graphify update . --code-only
28 - name: Upload graph artifact
29 uses: actions/upload-artifact@v4
30 with:
31 name: graphify-graph
32 path: graphify-out/graph.json
33 retention-days: 7
Pre-Commit Hook (Optional)
1# .git/hooks/pre-commit
2#!/bin/bash
3# Rebuild if Python/JS files changed
4if git diff --cached --name-only | grep -E '\.(py|js|ts|go|rs)$' | head -5 | grep -q .; then
5 echo "Rebuilding Graphify graph..."
6 mkdir -p graphify-out && touch graphify-out/.graphify-activity
7 graphify update . --code-only
8fi
📊 Rebuild Performance
| Mode | Files | Time | Graph Size |
|---|---|---|---|
| Code-only (incremental) | ~100 | ~15s | 3.3 MB |
| Code-only (full) | ~944 | ~45s | 3.3 MB |
| Full (incremental) | ~100 | ~30s | ~15 MB |
| Full (full) | ~3,000 | ~90s | ~15 MB |
🚨 Common Rebuild Issues
| Issue | Solution |
|---|---|
graph.json not updated | Forgot to signal activity: touch graphify-out/.graphify-activity |
| Stale references persist | Full rebuild: graphify . --code-only (not update) |
| API key error on full rebuild | Check GEMINI_API_KEY env var; fallback to --code-only |
| Build hangs | Kill with Ctrl+C; check disk space; try --code-only |
| Graph still empty after rebuild | Run graphify . --code-only (initial build, not update) |
📋 Rebuild Checklist
- Signaled activity (
mkdir -p graphify-out && touch graphify-out/.graphify-activity) - Chose correct mode (
--code-onlyvs full) - API key set (if full graph)
- Command completed without errors
- Graph file updated (check
stat graphify-out/graph.json) - Test query works (
graphify query "project overview") - (Optional) Regenerate clusters:
graphify cluster-only .
Next Steps
- Daily Usage - Use the fresh graph
- VS Code Integration - Auto-signal activity in editor