dvy1987 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.pywalks the entire repository for source files..agents/skills/is indexed as skills, not skipped — but application code inpackages/,artifacts/,lib/, etc. must appear asmodulenodes. - Query before rebuild. Relational questions →
query_graph.pyfirst. - Authoritative > inferred.
invokesfromdocs/skill-graph.md+SKILL-INDEX.mdCalls: lines are authoritative;referencesedges are hypotheses. - Shrink guard. No
--forceunless user confirms or graph is corrupt. - Handoff sync. Every
memory-handoff→--incrementalbuild. - 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.mdexist underdocs/knowledge-graph/ - Build stdout shows
repo-wide sourcelayer (not skills-only) - Consumer repos with code have
modulenodes ingraph.jsonstats -
call-graph.jsonpresent when mode=skill-library - Shrink guard respected (or
--forceapproved) - Query results cite path + confidence + provenance
- Handoff hook ran
--incrementalwhen invoked frommemory-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 priorityreferences/integration.md— producers/consumers, project-setup bootstrapscripts/build_graph.py— full/incremental buildscripts/query_graph.py— query, path, explainscripts/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
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]