knowledge-graph

name	knowledge-graph
description	Build, update, and query a persistent project knowledge graph from skills, memory, docs, and code structure — stdlib Python only, no external tools. Dual-mode: skill-library (agent-loom) or application (any consumer repo). Load when the user asks for a knowledge graph, project map, skill relationships, query the graph, update the graph, or trace how components connect. Auto-runs on memory-handoff and project-setup bootstrap. Also triggers on "build the graph", "what connects to X", "map this project".
license	MIT
metadata	{"author":"dvy1987","version":"2.3","category":"project-specific","sources":"safishamsi/graphify patterns (native stdlib impl, no pip install)","resources":{"references":["schema.md","integration.md","examples.md"],"scripts":["build_graph.py","query_graph.py","graph_health.py"]}}

Knowledge Graph

You maintain a queryable project graph at docs/knowledge-graph/. Stdlib Python only — no Graphify, no pip deps, no external URLs in outputs.

Deployment Context

Host	Mode	Typical use
agent-loom (skill library)	skill-library	Map skill invoke chains, memory, handoffs
Any consumer project	application	Map modules, docs, memory for GRAPHIFY-style project management

Mode auto-detects from authoritative skill-library files: docs/skill-graph.md and docs/SKILL-INDEX.md → skill-library label; otherwise application. Both modes always perform a repo-wide scan — skills, all application source (any path), packages, config, docs, memory, directories. Never skills-only.

Hard Rules

• Full repo, always. build_graph.py walks the entire repository for source files. .agents/skills/ is indexed as skills, not skipped — but application code in packages/, artifacts/, lib/, etc. must appear as module nodes.
• Query before rebuild. Relational questions → query_graph.py first.
• Authoritative > inferred. invokes from docs/skill-graph.md + SKILL-INDEX.md Calls: lines are authoritative; references edges are hypotheses.
• Shrink guard. No --force unless user confirms or graph is corrupt.
• Handoff sync. Every memory-handoff → --incremental build.
• No secrets. Skip .env, credentials, tokens by path name.

Common Rationalizations

Excuse	Reality
"I'll just grep"	Grep misses invoke chains and handoff lineage. Query the graph.
"Graph is stale, full rebuild"	Try --incremental first; authoritative sources may be unchanged.
"INFERRED edge = fact"	Read source_file / provenance before acting.
"Skip graph on handoff"	Next agent loses relational context.
"Need Graphify pip package"	Native stdlib scripts; patterns only, no install.
"Only for agent-loom"	Bootstrap in every project via project-setup.
"Many skills = skills-only graph"	Wrong — repo-wide scan always runs; read build stdout Why: line.

---

Workflow

Step 1 — Check existing graph

Read GRAPH_INDEX.md and GRAPH_REPORT.md when present.

Step 2 — Build or update

python3 .agents/skills/knowledge-graph/scripts/build_graph.py              # full repo scan
python3 .agents/skills/knowledge-graph/scripts/build_graph.py --incremental  # handoff/default
python3 .agents/skills/knowledge-graph/scripts/build_graph.py --force       # override shrink guard
python3 .agents/skills/knowledge-graph/scripts/build_graph.py --strict      # fail if source on disk but 0 modules

Stdout always prints: auto mode label, why that label was chosen, and scan layers (skills, code dirs, docs, memory). Read it before assuming skills-only — both modes scan the full repository.

Step 3 — Query

python3 .agents/skills/knowledge-graph/scripts/query_graph.py query "memory handoff connections"
python3 .agents/skills/knowledge-graph/scripts/query_graph.py path memory-handoff knowledge-graph
python3 .agents/skills/knowledge-graph/scripts/query_graph.py explain validate-skills

Cite path, confidence, and provenance for every hit. routing_note in JSON output confirms authoritative-first ordering — prefer invokes edges from skill-graph.md over INFERRED heuristics when choosing skills.

Step 4 — Health audit (optional / validate-skills hook)

python3 .agents/skills/knowledge-graph/scripts/graph_health.py

Step 5 — Report

Summarize: mode, node/edge counts, authoritative vs inferred ratio, hub nodes, communities, top query results.

---

Handoff Hook (mandatory for memory-handoff)

After appending to agent-handoffs.md:

python3 .agents/skills/knowledge-graph/scripts/build_graph.py --incremental

If build fails, note in handoff ### Graph — do not block save.

---

Output Format

## Knowledge graph — [full | incremental | query | health]

Mode: [skill-library | application]
Stats: [N] nodes, [E] edges ([A] authoritative invokes)
Hub nodes: [top 3]
Query: "[question]" → [matches with confidence tags]
Files: graph.json, call-graph.json, GRAPH_INDEX.md, GRAPH_REPORT.md

---

Verification

• graph.json, GRAPH_INDEX.md, GRAPH_REPORT.md exist under docs/knowledge-graph/
• Build stdout shows repo-wide source layer (not skills-only)
• Consumer repos with code have module nodes in graph.json stats
• call-graph.json present when mode=skill-library
• Shrink guard respected (or --force approved)
• Query results cite path + confidence + provenance
• Handoff hook ran --incremental when invoked from memory-handoff
• No secrets or external URLs in graph artifacts

---

Red Flags

• Full graph rebuild run before query_graph for relational ask
• Inferred edges override authoritative Calls: from SKILL-INDEX
• Repo walk skipped — partial graph presented as complete
• graph.json stale versus latest handoff not rebuilt

Reference Files

• references/schema.md — node/edge types, provenance priority
• references/integration.md — producers/consumers, project-setup bootstrap
• scripts/build_graph.py — full/incremental build
• scripts/query_graph.py — query, path, explain
• scripts/graph_health.py — dangling invokes, stale graph, orphan skills

---

File Output

Append to docs/skill-outputs/SKILL-OUTPUTS.md:

| YYYY-MM-DD HH:MM | knowledge-graph | docs/knowledge-graph/ | [N] nodes, [E] edges, mode=[mode] |

---

Examples

Build a knowledge graph for this project. Ran `build_graph.py` → mode=skill-library, 120 nodes, 412 edges (164 authoritative invokes). Hubs: universal-skill-creator, validate-skills, secure-skill. Saved to `docs/knowledge-graph/`. See `GRAPH_REPORT.md` for communities and suggested questions. How does memory-handoff connect to knowledge-graph? `query_graph.py path memory-handoff knowledge-graph` → 1 hop via `invokes` [EXTRACTED, provenance: memory-handoff/SKILL.md]. Neighbors: memory-capture, agent-handoffs [recorded_in].

---

Prune Log

Last pruned: 2026-07-04

• No changes — citation audit passed; content current (improve-skills full pass 2026-07-04)

Impact Report

Knowledge graph: [full/incremental/query/health]
Mode: [skill-library|application] | Nodes: [N] | Edges: [E]
Authoritative invokes: [A] | EXTRACTED: [E] | INFERRED: [I]
Shrink guard: [ok/refused/forced] | Handoff sync: [yes/no]
Consumers notified: [list or n/a]