Graphify knowledge graphs for AI-assisted development

ConnectSoft uses Graphify (PyPI package graphifyy) to turn repository source — code, project files, and selected docs — into a persistent, queryable knowledge graph that AI coding assistants (Cursor, Claude Code, Codex, and others) can traverse instead of re-reading raw files on every question.

The first pilot repository is ConnectSoft.Extensions. The same pattern applies to other ConnectSoft.* libraries and service templates.

Why Graphify in ConnectSoft?

Large ConnectSoft workspaces span dozens of NuGet libraries and templates. Asking an assistant to "understand the repo" by grepping and opening files is slow, expensive, and does not scale. Graphify builds a structural map once, stores it under graphify-out/, and answers focused questions with graphify query, graphify path, and graphify explain — typically far fewer tokens than naive file reads.

What Graphify produces

After a successful build, each repo contains:

Output	Purpose	Commit to git?
graphify-out/graph.json	Queryable graph (nodes, edges, communities)	Yes — team shares one map
graphify-out/GRAPH_REPORT.md	God nodes, communities, suggested questions	Yes
graphify-out/graph.html	Interactive browser visualization	Yes (optional --no-viz to skip)
graphify-out/manifest.json	Local mtime metadata	No — machine-specific
graphify-out/cost.json	Local cost tracking	No
graphify-out/cache/	Incremental AST / semantic cache	No (optional to commit for speed)

Architecture in ConnectSoft

flowchart LR
  subgraph repo [Repository e.g. ConnectSoft.Extensions]
    CS[C# / csproj / sln]
    MD[README and docs]
    GI[.graphifyignore]
  end
  subgraph graphify [Graphify CLI graphifyy]
    AST[Tree-sitter AST extract]
    SEM[Optional semantic LLM extract]
    BUILD[NetworkX graph + Leiden clusters]
  end
  subgraph out [graphify-out]
    JSON[graph.json]
    RPT[GRAPH_REPORT.md]
    HTML[graph.html]
  end
  subgraph assistants [AI assistants]
    CUR[Cursor rule + skill]
    Q[graphify query / path / explain]
  end
  CS --> AST
  MD --> SEM
  GI --> AST
  AST --> BUILD
  SEM --> BUILD
  BUILD --> JSON
  BUILD --> RPT
  BUILD --> HTML
  JSON --> Q
  CUR --> Q

Hold "Alt" / "Option" to enable pan & zoom

Two extraction modes

Mode	Command	API key	When to use
AST / code-only	python -m graphify update .	Not required	Day-to-day C# changes, .csproj, solution layout, README sections parsed structurally
Full semantic	python -m graphify extract . --backend <name>	Required (or local Ollama)	Rich doc semantics, images, papers, cross-file inferred relationships

PowerShell: graphify . is not the same as graphify update .

On the CLI, python -m graphify . is treated as graphify extract . and requires --backend (or a configured API key environment variable). For ConnectSoft library repos without a semantic backend, use python -m graphify update . for builds and refreshes.

Pilot: ConnectSoft.Extensions

Repository: ConnectSoft.Extensions

ConnectSoft.Extensions is a foundational Layer-1 NuGet library (extension methods, domain exception base types, shared utilities). It is a good pilot because the codebase is small but representative: solution layout, multi-target net8.0 / net9.0 / net10.0, unit tests, and README-driven install docs.

Example graph facts (AST-only build):

• DomainModelException → inherits Exception (extracted from DomainModelException.cs)
• Solution folders link ConnectSoft.Extensions.csproj and ConnectSoft.Extensions.UnitTests.csproj
• DomainModelExceptionUnitTests appears as a high-degree test hub

Query from the repo root:

python -m graphify explain "DomainModelException"
python -m graphify query "DomainModelException and unit tests"

Open graphify-out/graph.html in a browser to explore communities visually.

Prerequisites

Requirement	Notes
Python 3.10+	python --version
graphifyy on PATH	pip install graphifyy or uv tool install graphifyy
Git working tree	Graph reports record commit SHA for freshness checks

Official package name is graphifyy (double y). The CLI command remains graphify.

Per-repository setup (ConnectSoft standard)

Run once from the repository root (not the monorepo workspace root unless that repo is the root).

1. Install Graphify and project-scoped Cursor integration

pip install graphifyy

cd D:\Git\ConnectSoft\ConnectSoft.Extensions   # example path

python -m graphify install --project
python -m graphify cursor install --project

This writes (commit these):

Path	Role
.cursor/rules/graphify.mdc	Always-on Cursor rule: query graph before grepping
.cursor/skills/graphify/SKILL.md	/graphify skill for rebuild workflows
.claude/skills/graphify/SKILL.md	Same skill for Claude Code (Windows install)
CLAUDE.md	Query-first guidance for Claude Code

2. Configure .gitignore

Append Graphify team defaults (keep graph.json, GRAPH_REPORT.md, graph.html tracked):

### Graphify (https://graphify.net/) ###
graphify-out/manifest.json
graphify-out/cost.json
graphify-out/cache/

3. Configure .graphifyignore

Exclude build artifacts and Graphify meta-files so the graph reflects product source, not integration scaffolding:

graphify-out/
.cursor/skills/graphify/
.claude/skills/graphify/
CLAUDE.md
.claude/

**/bin/
**/obj/
.vs/
TestResults/
**/packages/

Adjust per repo (for example add node_modules/ for front-end templates).

4. Build the initial graph (no API key)

python -m graphify update .

Verify:

Test-Path graphify-out/graph.json   # should be True
python -m graphify query "solution structure"

5. Optional: semantic enrichment

When you need deeper doc/image semantics:

# Local Ollama (requires running Ollama + pip install openai)
python -m graphify extract . --backend ollama

# Cloud backends (set env var first)
$env:OPENAI_API_KEY = "..."
python -m graphify extract . --backend openai

Supported backends include gemini, claude, openai, deepseek, kimi, ollama, and bedrock.

6. Optional: auto-rebuild on commit

python -m graphify hook install

Hooks rebuild code AST after commits and register a merge driver for graph.json when multiple branches update the graph.

Daily workflow in Cursor

1. Pull latest graphify-out/ from git (shared team map).
2. Ask architecture questions — the .cursor/rules/graphify.mdc rule steers the agent to graphify query when graphify-out/graph.json exists.
3. After editing .cs files, run:

python -m graphify update .

1. Commit updated graphify-out/graph.json, GRAPH_REPORT.md, and optionally graph.html with your code change (or in a follow-up commit).

Prefer query over full report

Use graphify query "...", graphify path "A" "B", or graphify explain "Symbol" for focused context. Read GRAPH_REPORT.md only for broad architecture review.

Team git workflow

1. One developer runs graphify update . (or full extract) and commits graphify-out/ (except ignored cache/manifest/cost).
2. Everyone else pulls — assistants read the graph immediately.
3. On stale graphs, compare GRAPH_REPORT.md commit SHA with git rev-parse HEAD.
4. Re-run graphify update . after code merges.

Rollout to other ConnectSoft repositories

Recommended order:

1. ConnectSoft.Extensions.* libraries (same layout as the pilot).
2. Service templates (ConnectSoft.MicroserviceTemplate, ConnectSoft.BaseTemplate, etc.) — extend .graphifyignore for template bin//obj/ and generated base-template/ noise as needed.
3. Documentation repos — Graphify complements Documentation as Code; semantic extract adds value for long-form Markdown corpora.

For each repo, repeat: install --project, cursor install --project, .gitignore, .graphifyignore, initial update ., commit integration files + graphify-out/.

Security and privacy

• Code AST extraction runs locally via Tree-sitter — no network call.
• Semantic extraction sends document descriptions to the configured backend, not raw secret files. Do not index .env, keys, or secrets/ — add them to .graphifyignore.
• Graphify validates URLs and output paths; prefer official graphifyy on PyPI only.

Troubleshooting

Symptom	Fix
error: no LLM API key found when running graphify .	Use graphify update . for code-only, or pass --backend ollama / set an API key for extract
God nodes are /graphify skill text	Add .cursor/skills/graphify/ and .claude/skills/graphify/ to .graphifyignore, delete graphify-out/, rebuild with update .
Graph seems stale	Run graphify update .; check commit line in GRAPH_REPORT.md
graphify: command not found	Use python -m graphify or install via uv tool install graphifyy

See also

• ConnectSoft.Extensions package catalog — NuGet inventory including ConnectSoft.Extensions
• ConnectSoft.Extensions.Testing — shared test utilities in the same ecosystem
• Knowledge Management — documentation and diagram practices
• Documentation as Code — MkDocs and repo handbooks
• Graphify project site — upstream docs, security notes, and command reference