When to Commit the Knowledge Graph to Git and Manage Large Graphs with Git LFS

TLDR: Commit the .understand-anything/knowledge-graph.json file immediately after completing a full /understand scan or before merging pull requests, and migrate the file to Git LFS by configuring .gitattributes once it exceeds a few megabytes to prevent repository bloat.

The Egonex-AI/Understand-Anything repository maintains a comprehensive knowledge graph that encodes your project's architecture in a JSON file. Knowing exactly when to commit this asset to Git—and how to handle it efficiently as it scales into a large binary file—is essential for preserving clean history and ensuring downstream agents like knowledge-graph-guide and domain-analyzer always read current data. This guide provides the specific timing strategies and Git LFS configuration steps derived from the source code implementation.

When to Commit the Knowledge Graph to Git

The persistence layer in understand-anything-plugin/packages/core/src/persistence/index.ts defines GRAPH_FILE = "knowledge-graph.json" and writes the complete graph to .understand-anything/knowledge-graph.json only after specific processing stages complete.

After a Full Scan

Commit the file immediately after a /understand run finishes. The skill documentation in understand-anything-plugin/skills/understand/SKILL.md describes this final write step, ensuring the graph contains a complete representation of the current architecture. The dashboard loads this file via /knowledge-graph.json, so committing at this point guarantees downstream agents access the latest data.

Before Merging Pull Requests

Every merge should contain an up-to-date graph because downstream agents read the file directly from the repository. Committing stale graphs triggers warnings in the dashboard when the file is missing or out-of-date relative to the code changes in the PR.

When Auto-Update Is Enabled

When autoUpdate: true is set in .understand-anything/config.json, the system leverages a hook defined in understand-anything-plugin/hooks/auto-update-prompt.md that watches for Git commits:

{
  "command": "[ -f .understand-anything/config.json ] && grep -q '\"autoUpdate\".*true' .understand-anything/config.json && [ -f .understand-anything/knowledge-graph.json ] && echo \"[understand-anything] Commit detected with auto‑update enabled. You MUST read the file at ${CLAUDE_PLUGIN_ROOT}/hooks/auto-update-prompt.md and execute its instructions to incrementally update the knowledge graph.\""
}

In this mode, you do not need to manually stage the graph; the hook automatically regenerates the file incrementally and includes it in the commit.

Why Frequent Commits Harm History

Do not commit after every minor change. The graph can contain thousands of nodes and edges, resulting in multi-megabyte files. Frequent commits create noisy history and large diffs that are difficult to review. A single, well-timed commit after a complete analysis is sufficient for most development workflows.

Handling Large Graphs with Git LFS

When the generated knowledge-graph.json exceeds a few megabytes—common for projects with over 3,000 nodes as demonstrated by scripts/generate-large-graph.mjs—storing it in standard Git blob storage becomes inefficient.

Installing Git LFS

Install Git Large File Storage (LFS) once per developer machine:

# macOS

brew install git-lfs

# Linux

sudo apt-get install git-lfs
git lfs install

Configuring LFS Tracking

Add a .gitattributes entry to track any knowledge-graph.json file under .understand-anything/:

echo ".understand-anything/knowledge-graph.json filter=lfs diff=lfs merge=lfs -text" >> .gitattributes
git add .gitattributes
git commit -m "Add LFS tracking for knowledge-graph.json"

Migrating Existing Graphs

If you already have a large graph in your history, migrate it to LFS:

git lfs track ".understand-anything/knowledge-graph.json"
git add .understand-anything/knowledge-graph.json
git commit -m "Migrate knowledge graph to LFS"

When you commit after a full scan, Git stores only the LFS pointer in the commit, while the actual JSON blob lives in the LFS store.

CI/CD Considerations

Ensure your CI agents run git lfs install in build scripts to fetch the graph for dashboard tests. Without this step, pipelines may fail when attempting to read the LFS-tracked file.

Best-Practice Commit Workflow

Follow this checklist to ensure proper knowledge graph management:

1. Run /understand --full to generate a fresh graph via the persistence layer.
2. Verify the file exists and check its size: du -h .understand-anything/knowledge-graph.json.
3. If the file exceeds a few MiB, confirm .gitattributes includes the LFS rule.
4. Stage the graph: git add .understand-anything/knowledge-graph.json.
5. Commit with a descriptive message: git commit -m "chore: update knowledge graph for v1.2.0".
6. Push to remote; Git LFS handles the large file transfer automatically.
7. When autoUpdate is enabled, allow the hook to trigger incremental updates on subsequent commits.

Summary

• Commit the knowledge graph immediately after a full /understand scan or before merging PRs to prevent stale data warnings.
• Enable Git LFS via .gitattributes once .understand-anything/knowledge-graph.json exceeds a few megabytes.
• Use the auto-update hook in hooks/auto-update-prompt.md to automate commits when autoUpdate: true is configured.
• Install git-lfs on CI agents to ensure pipelines can access the tracked file.

Frequently Asked Questions

How often should I commit the knowledge graph to Git?

Commit only after complete analysis runs or before merging pull requests. Avoid committing after every minor code change, as the multi-megabyte JSON file creates noisy history and large diffs that are difficult to review.

What file size triggers the need for Git LFS?

Once the .understand-anything/knowledge-graph.json file exceeds a few megabytes—typical for projects with over 3,000 nodes as shown in scripts/generate-large-graph.mjs—you should track it with Git LFS to prevent repository bloat and slow clone times.

How do downstream agents use the knowledge graph?

Agents such as knowledge-graph-guide and domain-analyzer read the graph directly from the repository at .understand-anything/knowledge-graph.json. If the file is missing or stale relative to the code, the dashboard displays warnings, making timely commits essential for agent accuracy.

Does auto-update work with Git LFS?

Yes. When autoUpdate: true is set in .understand-anything/config.json, the hook defined in understand-anything-plugin/hooks/auto-update-prompt.md automatically stages and commits the graph. If LFS is configured, the hook handles the pointer file transparently, ensuring the large JSON blob is stored in LFS while the commit remains lightweight.

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