How the Auto-Update Post-Commit Hook Incrementally Patches the Knowledge Graph in Egonex-AI

The auto-update post-commit hook uses a deterministic four-phase pipeline that fingerprints changed files to distinguish cosmetic from structural changes, then re-analyzes only the modified files and patches the existing graph rather than rebuilding it from scratch.

The Egonex-AI/Understand-Anything repository maintains a persistent knowledge graph of your codebase in .understand-anything/knowledge-graph.json. When you enable the --auto-update flag, the system installs a post-commit hook that incrementally patches this graph after every Git commit, avoiding costly LLM token consumption by re-analyzing only what has actually changed.

The Four-Phase Incremental Update Pipeline

The hook operates as a deterministic pipeline defined in understand-anything-plugin/hooks/auto-update-prompt.md, progressing through four distinct phases to minimize token usage while ensuring graph accuracy.

Phase 0: Pre-Flight Zero-Token Checks

Before invoking any LLM calls, the hook performs environment validation and change detection. According to lines [9-25] of the prompt definition, the system first verifies that .understand-anything/knowledge-graph.json and .understand-anything/meta.json exist; if either is missing, the hook aborts and instructs the user to run a full /understand command.

The hook then obtains the current Git hash using git rev-parse HEAD and compares it against the stored hash in meta.json. If the hashes match and the --force flag is not set, the process terminates immediately. When hashes differ, the hook executes git diff <lastCommitHash>..HEAD --name-only to collect changed files, filters them to source files, and applies exclusions from .understandignore (see the exclusion logic at lines [40-48]).

Phase 1: Structural Fingerprint Classification

Phase 1 runs a lightweight Node.js script that extracts structural fingerprints—hashes of functions, classes, imports, and exports—from each changed file without LLM involvement. As defined in lines [94-122] of the prompt, the system compares these fingerprints against the stored values in .understand-anything/fingerprints.json.

If all fingerprints match, the action is set to SKIP. Otherwise, the script classifies changes as either COSMETIC or STRUCTURAL and determines one of four actions: SKIP, FULL_UPDATE, PARTIAL_UPDATE, or ARCHITECTURE_UPDATE. This classification determines whether Phase 2 and Phase 3 need to run.

Phase 2: Targeted Re-Analysis with Minimal Token Use

Only files flagged as STRUCTURAL during Phase 1 proceed to Phase 2, the only stage that incurs LLM token costs. The system loads the existing knowledge graph and batches changed files (maximum 10 files per batch) for dispatch to the file-analyzer agent, as described in lines [150-176] of the prompt specification.

The file-analyzer agent (defined in understand-anything-plugin/agents/file-analyzer.md) generates new nodes and edges for the affected files. These new graph elements replace the old entries for those specific files while the rest of the graph remains untouched, achieving true incremental patching.

Phase 3: Conditional Architecture Updates and Persistence

If Phase 1 flagged an ARCHITECTURE_UPDATE, the architecture-analyzer agent runs to adjust high-level architectural relationships. Otherwise, only a lightweight layer adjustment executes. The merged graph undergoes validation to remove dangling edges before the system writes the updated graph back to .understand-anything/knowledge-graph.json and updates meta.json with the new Git hash.

Crucially, the fingerprints file is patched rather than overwritten. The guard logic at lines [57-86] ensures that only the fingerprints of changed files are updated, preventing the "all files become new" bug that would otherwise trigger a full rebuild. Finally, intermediate files are removed and a summary report is printed (lines [92-100]).

Enabling and Configuring the Auto-Update Hook

To activate the incremental patching system in your repository:

# Configure Git to use the repository's hooks directory

git config core.hooksPath .git/hooks

# Run initial full analysis to establish baseline

understand --full

# Subsequent commits trigger automatic patching

git commit -am "Add authentication middleware"

# Output: "Partial update: 1 structural file changed, graph patched."

Force Rebuild and Graph Inspection

When you perform massive refactors that change the fundamental structure of many files, bypass the incremental logic to ensure completeness:

# Force full rebuild bypassing hash checks

understand --auto-update --force

To verify the current state of the knowledge graph after an update:

# Check node count in the patched graph

cat .understand-anything/knowledge-graph.json | jq '.nodes | length'

Key Implementation Files

The incremental update mechanism relies on these specific components:

• understand-anything-plugin/hooks/auto-update-prompt.md — Defines the complete four-phase pipeline including the decision matrix and fingerprint patching logic (lines [57-86], [94-122], [150-176])
• understand-anything-plugin/agents/file-analyzer.md — Performs targeted re-analysis of structurally changed files during Phase 2
• understand-anything-plugin/agents/architecture-analyzer.md — Handles architectural updates when Phase 1 triggers ARCHITECTURE_UPDATE
• .understand-anything/meta.json — Stores the last analyzed Git hash used for Phase 0 change detection
• .understand-anything/fingerprints.json — Persistent structural fingerprints patched during Phase 3 to avoid full rebuilds

Summary

• The auto-update hook runs a four-phase pipeline after each Git commit when --auto-update is enabled.
• Phase 0 performs zero-token validation by checking file existence and Git hashes, filtering changed files through .understandignore.
• Phase 1 classifies changes as cosmetic or structural using Node.js fingerprints without LLM cost.
• Phase 2 dispatches only structural files to the file-analyzer agent in batches of ≤10, patching the graph rather than rebuilding it.
• Phase 3 conditionally runs the architecture-analyzer and patches the fingerprints file using guard logic to prevent unnecessary full rebuilds.

Frequently Asked Questions

What triggers a full rebuild versus an incremental patch?

The auto-update hook triggers a FULL_UPDATE action only when Phase 1 detects massive structural changes across the codebase or when you explicitly pass the --force flag. In normal operation, if the fingerprint check in Phase 1 finds only cosmetic changes (whitespace, comments), the action is SKIP. When individual files change structurally, the action is PARTIAL_UPDATE, which re-analyzes only those specific files.

How does the system prevent analyzing unchanged files?

The system maintains persistent structural fingerprints in .understand-anything/fingerprints.json. During Phase 1, a lightweight Node.js script hashes the functions, classes, and exports of each changed file and compares them to stored values. Only files with mismatched fingerprints proceed to the LLM-based analysis phase, ensuring unchanged files incur zero token cost.

Where is the incremental update logic defined?

The complete workflow specification resides in understand-anything-plugin/hooks/auto-update-prompt.md. This file defines the Phase 0 pre-flight checks (lines [9-25]), the exclusion logic (lines [40-48]), the fingerprint patching guard (lines [57-86]), the structural classification decision matrix (lines [94-122]), and the batching logic for the file-analyzer agent (lines [150-176]).

Can I inspect the knowledge graph after an incremental update?

Yes. After the hook completes Phase 3, the updated graph is available at .understand-anything/knowledge-graph.json. You can inspect it using standard JSON tools like jq to verify node counts or query specific relationships, confirming that only the changed files were modified while the rest of the graph structure remained intact.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}