Best Practices for Committing Egonex Knowledge Graph to Shared Repositories

Commit the canonical knowledge-graph.json file to version control while excluding intermediate artifacts, enabling auto-update hooks, and validating the graph before pushing to ensure the dashboard remains functional.

The Egonex (Understand-Anything) pipeline generates a knowledge graph that captures structural, semantic, and domain-specific information from your codebase. This graph is persisted as knowledge-graph.json inside the /.understand-anything/ directory and serves as a first-class artifact driving the interactive dashboard and AI agents. Following these guidelines when committing the Egonex knowledge graph to shared repositories ensures that every checkout can render the dashboard without requiring a full recompute.

Commit the Canonical Egonex Knowledge Graph File

The primary artifact to version is .understand-anything/knowledge-graph.json. This file is referenced by multiple skills including understand-chat and understand-dashboard according to the documentation in understand-anything-plugin/skills/understand/SKILL.md.

git add .understand-anything/knowledge-graph.json

Committing this file guarantees that team members can immediately access the dashboard without running the analysis pipeline. The graph file is defined as a constant in the core package at understand-anything-plugin/packages/core/src/persistence/index.ts, where GRAPH_FILE = "knowledge-graph.json" determines the canonical filename.

Exclude Intermediate Files from Shared Repository Commits

Do not commit temporary or intermediate files generated during the analysis process. Files such as intermediate/assembled-graph.json or temporary batch files are regenerated on each run and contain non-canonical data that pollutes repository history.

Add the intermediate directory to your .gitignore:

# Do not commit temporary analysis artefacts

.understand-anything/intermediate/

Enable Auto-Update on Commit

Configure the pipeline to automatically keep the graph synchronized with your codebase by setting "autoUpdate": true in .understand-anything/config.json. When enabled, a post-commit hook defined in understand-anything-plugin/hooks/hooks.json triggers the incremental update script, eliminating manual intervention.

{
  "autoUpdate": true,
  "ignorePatterns": ["**/*.test.ts", "node_modules/**"]
}

The hook logic, detailed in understand-anything-plugin/hooks/auto-update-prompt.md, detects staleness by comparing the stored gitCommitHash in meta.json against the current repository state. This ensures incremental analysis only runs when the actual code changes.

Merge Sub-Domain Graphs Before Committing

For projects containing multiple sub-graphs (such as frontend-knowledge-graph.json), run the bundled merge-subdomain-graphs.py script before committing. This script, located at understand-anything-plugin/skills/understand/merge-subdomain-graphs.py, consolidates disparate graphs into the canonical knowledge-graph.json.

cd understand-anything-plugin/skills/understand
python merge-subdomain-graphs.py

The script scans for *knowledge-graph*.json files, deduplicates nodes and edges, and rewrites the canonical file, ensuring a single source of truth across sub-domains.

Validate the Egonex Knowledge Graph Before Pushing

The dashboard employs Zod schema validation to prevent malformed graphs from breaking the user interface. Validation occurs automatically when the core package writes the graph, as implemented in understand-anything-plugin/packages/core/src/persistence/index.ts.

Run the core package tests locally to verify graph integrity before pushing:

pnpm --filter @understand-anything/core test

This prevents CI failures and ensures the dashboard build completes successfully.

Document the Egonex Knowledge Graph in Your README

Add a dedicated "Knowledge Graph" section to your repository's README explaining the purpose of knowledge-graph.json and how it is generated via the /understand skill. This documentation prevents contributors from manually editing the file and clarifies that it is a generated artifact, not source code.

Summary

• Commit the canonical file: Version .understand-anything/knowledge-graph.json alongside your source code to ensure dashboard availability.
• Ignore intermediate artifacts: Exclude the .understand-anything/intermediate/ directory to prevent noisy diffs.
• Enable auto-updates: Set "autoUpdate": true in config.json to leverage post-commit hooks for incremental analysis.
• Merge sub-domain graphs: Run merge-subdomain-graphs.py before committing when working with multiple graph fragments.
• Validate before pushing: Execute core package tests to verify graph schema compliance and prevent CI failures.
• Document the process: Explain the knowledge graph's purpose in your README to guide new contributors.

Frequently Asked Questions

Should I commit the intermediate files in the .understand-anything/intermediate/ directory?

No, you should not commit intermediate files. These files are regenerated on each analysis run and contain temporary, non-canonical data that will pollute your repository history. Add the entire intermediate/ folder to your .gitignore file to exclude it from version control.

How does the auto-update hook detect when the knowledge graph needs regeneration?

The pipeline stores the current git commit hash in meta.json under the gitCommitHash field. The post-commit hook, defined in understand-anything-plugin/hooks/hooks.json and implemented according to understand-anything-plugin/hooks/auto-update-prompt.md, compares this stored hash against the current repository state. When they differ, the hook triggers incremental analysis to update the graph automatically.

What happens if I commit a malformed knowledge graph?

Committing a malformed graph will cause the dashboard to fail at runtime because the UI validates the graph against a Zod schema. The validation occurs automatically when the core package writes the file in understand-anything-plugin/packages/core/src/persistence/index.ts, but running pnpm --filter @understand-anything/core test before pushing will catch errors early and prevent broken dashboard builds in CI.

Can I merge multiple domain-specific knowledge graphs into one file?

Yes, use the merge-subdomain-graphs.py script located in understand-anything-plugin/skills/understand/. This utility scans for all *knowledge-graph*.json files (excluding the canonical one), deduplicates nodes and edges across them, and consolidates the results into the single knowledge-graph.json file required by the dashboard.

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