How to Commit and Share the Knowledge Graph with Your Development Team

The Understand-Anything knowledge graph is serialized as knowledge-graph.json inside the .understand-anything/ directory, enabling version control through standard Git workflows so development teams can collaboratively track codebase architecture.

The Understand-Anything open-source project constructs a detailed knowledge graph representing every file, function, class, and dependency in your codebase. Because this graph is persisted as a flat JSON file rather than binary storage, it integrates seamlessly with existing Git workflows, allowing teams to share architectural insights through standard commits and pull requests.

Where the Knowledge Graph Is Stored

According to the source code in understand-anything-plugin/packages/core/src/persistence/index.ts, the graph is written to .understand-anything/knowledge-graph.json at the project root. This location is explicitly documented in the skill definition at understand-anything-plugin/skills/understand/SKILL.md, which specifies that the /understand skill outputs the committable graph to this hidden directory.

Step-by-Step Workflow to Commit and Share the Knowledge Graph

1. Generate the Graph

Execute the primary analysis skill to create the graph. The CLI command triggers the persistence layer that serializes the structured data:

# Run from project root

understand

# Or force a full rebuild rather than incremental

understand --full

This writes the complete graph structure to .understand-anything/knowledge-graph.json as specified in the skill documentation.

2. Verify the Output

Confirm the file exists and is readable. The dashboard validates this by serving the file via a dedicated route in understand-anything-plugin/packages/dashboard/vite.config.ts (lines 130-252), exposing it at /knowledge-graph.json. Start the dashboard to verify:

pnpm dev:dashboard

3. Configure Auto-Updates (Optional)

For teams wanting automatic graph updates on every commit, enable the post-commit hook. Modify .understand-anything/config.json:

{
  "autoUpdate": true
}

When enabled, the hook registered in understand-anything-plugin/hooks/hooks.json triggers incremental updates by comparing the commit hash stored in .understand-anything/meta.json against the current HEAD, as detailed in understand-anything-plugin/hooks/auto-update-prompt.md (lines 19-30).

4. Stage and Commit the Graph

Add the generated file to your repository:

git add .understand-anything/knowledge-graph.json
git commit -m "chore: add latest knowledge graph for team review"

5. Share with Your Development Team

Push the commit to your remote repository:

git push origin main

Team members pull the latest changes and launch the dashboard, which automatically loads the shared graph from the local .understand-anything/knowledge-graph.json file via the Vite dev server route.

6. Validate Continuously in CI

The repository includes a persistence test in understand-anything-plugin/packages/core/src/persistence/persistence.test.ts (line 78) that asserts the graph can be written to the expected directory. Run this in your CI pipeline to ensure committed graphs are well-formed:

pnpm test

Example GitHub Actions snippet:

- name: Install dependencies
  run: pnpm install --frozen-lockfile

- name: Validate graph persistence
  run: pnpm test

Understanding the Auto-Update Mechanism

The auto-update feature relies on git metadata to avoid unnecessary full rebuilds. When autoUpdate is enabled in the configuration, the system stores the last processed commit hash in .understand-anything/meta.json. The post-commit hook, registered in hooks/hooks.json, executes the logic from hooks/auto-update-prompt.md to determine whether to perform an incremental merge or a full regeneration based on whether the hash has changed.

Summary

• The knowledge graph is persisted as .understand-anything/knowledge-graph.json, making it fully version-controllable
• Run the /understand skill to generate the graph, which writes through the persistence layer in packages/core/src/persistence/index.ts
• Enable auto-updates by setting "autoUpdate": true in .understand-anything/config.json to trigger post-commit hooks defined in hooks/hooks.json
• The dashboard serves the shared graph via /knowledge-graph.json as configured in vite.config.ts, requiring no additional setup for teammates
• Include persistence tests in your CI pipeline to validate graph integrity on every build

Frequently Asked Questions

Does the knowledge graph need to be committed to the repository?

Yes. The JSON format is deliberately chosen to support Git-based collaboration. Without committing .understand-anything/knowledge-graph.json, teammates cannot view the architectural state through the dashboard, as the visualization layer reads from this specific file path.

What happens if two team members generate different graphs?

Git will flag the merge conflict in knowledge-graph.json. Teams should treat the graph like any generated artifact—either regenerate it after merging code changes or designate specific commits for graph updates. The persistence layer in packages/core/src/persistence/index.ts handles atomic writes to prevent corruption during generation.

Can the auto-update hook slow down my commits?

The post-commit hook defined in hooks/hooks.json runs asynchronously and performs incremental updates by comparing commit hashes stored in .understand-anything/meta.json. For large codebases, the initial generation may take time, but subsequent updates only process changed files unless a full rebuild is forced.

How do teammates access the shared graph after pulling?

After running git pull, team members simply execute pnpm dev:dashboard. The Vite configuration in packages/dashboard/vite.config.ts automatically serves the updated knowledge-graph.json at the /knowledge-graph.json endpoint, loading the latest architectural data in the browser without manual configuration.

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