# Graphify's Global Cross-Project Graph: Unified Multi-Repository Knowledge Base

> Discover Graphify's global cross-project graph, a unified knowledge base enabling multi-repository analysis with prefixed IDs and deduplication. Unlock cross-project insights.

- Repository: [Graphify Labs/graphify](https://github.com/Graphify-Labs/graphify)
- Tags: deep-dive
- Published: 2026-07-15

---

**Graphify's global cross-project graph is a unified knowledge base stored at `~/.graphify/global.json` that merges individual project graphs using prefixed IDs and deduplication to enable multi-repository analysis.**

Graphify builds individual knowledge graphs for each codebase it processes. To support analysis across multiple repositories, Graphify implements a **global cross-project graph** that aggregates these individual graphs into a single queryable view. This feature, available in the Graphify-Labs/graphify repository, allows developers to trace relationships and dependencies across their entire codebase ecosystem.

## What is the Global Cross-Project Graph?

The global cross-project graph is a merged representation of multiple project-level knowledge graphs. When you process a codebase with Graphify, it creates a standalone graph for that project. The global graph collects these individual graphs into a single JSON file, enabling queries that span across repository boundaries. This unified view preserves the same schema used for single-project graphs—defined in [`ARCHITECTURE.md`](https://github.com/Graphify-Labs/graphify/blob/main/ARCHITECTURE.md)—so all downstream analysis tools operate unchanged on the global view.

## How the Global Graph Works

### Registration and Storage

Projects enter the global graph through the `--global` flag during extraction or via manual registration. When you run `graphify extract ./my-project --global --as myproject`, the CLI automatically registers the freshly built graph using the `graphify global add` command. All registered graphs persist in a JSON file at `~/.graphify/global.json`. You can locate this file at any time by running `graphify global path`.

### Collision-Free ID Management

To prevent namespace collisions when merging graphs from different sources, Graphify automatically prefixes every node ID with `<repo>::` (the repository name or tag). This prefixing ensures that a function named `parse_data` in project A remains distinct from `parse_data` in project B, avoiding silent overwrites while maintaining relationships within each original project.

### Deduplication Logic

The global graph implements intelligent deduplication for external dependencies. When two projects reference the same third-party library—such as both importing `requests`—Graphify creates a single canonical node for that dependency and rewires all edges to point to this unified representation. This deduplication reduces graph size and accurately reflects shared dependencies across your codebase ecosystem.

### Incremental Update Mechanism

Adding a project to the global graph multiple times is computationally cheap. Graphify computes a hash of the incoming graph and compares it against already-registered versions. If the hash matches an existing entry, the system skips re-ingestion entirely. This hashing mechanism keeps the global graph up-to-date without unnecessary processing overhead.

## Working with the Global Graph

You can interact with the global graph through both the CLI and Python API.

**CLI Commands:**

```bash

# Extract and automatically register a project

graphify extract ./my-project --global --as myproject

# Manually add an existing graph file

graphify global add graphify-out/graph.json --as myproject

# List all registered projects with node/edge counts

graphify global list

# Remove a project from the global graph

graphify global remove myproject

# Display the path to global.json

graphify global path

```

**Python API:**

For programmatic access, import the `global_graph` module and load the unified graph:

```python
from graphify import global_graph

# Load the current global graph

g = global_graph.load_global()

# Find all projects that import the same library

libs = [n for n, data in g.nodes(data=True) if "requests" in data.get("label", "")]
print(f"Projects using `requests`: {set(n.split('::')[0] for n in libs)}")

```

## Core Implementation Files

The global graph functionality spans several key files in the Graphify codebase:

- **[`graphify/cli.py`](https://github.com/Graphify-Labs/graphify/blob/main/graphify/cli.py)**: Implements the `global add`, `global remove`, `global list`, and `global path` subcommands that manage the registry of projects.
- **[`graphify/global_graph.py`](https://github.com/Graphify-Labs/graphify/blob/main/graphify/global_graph.py)**: Handles the loading, merging, deduplication logic, and persistence operations for the `~/.graphify/global.json` file.
- **[`graphify/export.py`](https://github.com/Graphify-Labs/graphify/blob/main/graphify/export.py)**: Generates the project-level [`graphify-out/graph.json`](https://github.com/Graphify-Labs/graphify/blob/main/graphify-out/graph.json) files that serve as input to the global graph system.
- **[`ARCHITECTURE.md`](https://github.com/Graphify-Labs/graphify/blob/main/ARCHITECTURE.md)**: Documents the extraction schema and overall pipeline (detect → extract → build → cluster → analyze → report → export) used by both project-level and global graphs.

## Summary

- **Storage Location**: The global graph resides at `~/.graphify/global.json`, accessible via `graphify global path`.
- **ID Prefixing**: Node IDs use `<repo>::` prefixes to prevent collisions across projects.
- **Deduplication**: External dependencies automatically merge into canonical nodes, creating accurate cross-project dependency maps.
- **Incremental Updates**: Hash-based comparison prevents redundant re-ingestion of unchanged projects.
- **Unified Schema**: The global graph uses the same schema as individual projects, ensuring compatibility with existing analysis tools.

## Frequently Asked Questions

### Where is the global cross-project graph stored?

Graphify stores the global graph at `~/.graphify/global.json` on your local filesystem. You can verify the exact path by running the command `graphify global path` in your terminal. This JSON file contains the merged nodes and edges from all registered projects.

### How does Graphify prevent ID collisions between different projects?

Graphify automatically prefixes every node ID with `<repo>::` (using the repository name or tag you specified during registration). This namespace prefixing ensures that identical identifiers from different projects remain distinct in the merged graph, preventing silent data overwrites.

### Can I incrementally update the global graph without rebuilding everything?

Yes. Graphify computes a hash of each incoming project graph and compares it against existing entries. If the hash matches a previously registered version, the system skips re-ingestion. This makes it efficient to run `graphify extract --global` repeatedly as your codebase evolves.

### How do I query dependencies across multiple repositories?

Use the Python API to load the global graph with `global_graph.load_global()`, then traverse nodes using standard graph methods. Filter nodes by their `label` attribute and extract the repository prefix from the node ID (splitting on `::`) to identify which projects share specific dependencies or call relationships.